Merge pull request microsoft#78 from microsoft/TemplateReadMeUpdates

Template read me updates

Author: TravisHilbert

README.md

@@ -75,28 +75,24 @@ This diagram double-clicks into the agentic framework for the code conversion pr
 QUICK DEPLOY
 </h2>
 
-
-| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Modernize-your-Code-Solution-Accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Modernize-your-Code-Solution-Accelerator) | [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FModernize-your-code-solution-accelerator%2Frefs%2Fheads%2Fmain%2Finfra%2Fmain.json) |
-|---|---|---|
-
 ### **Prerequisites**
 
 To deploy this solution accelerator, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups and resources**. Follow the steps in  [Azure Account Set Up](./docs/AzureAccountSetUp.md) 
 
 Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=all&regions=all) page and select a **region** where the following services are available:  
 
 - Azure AI Foundry 
-- Azure OpenAI Service 
-- Embedding Deployment Capacity  
+- Azure OpenAI Service  
 - GPT Model Capacity
 
 Here are some example regions where the services are available: East US, East US2, Japan East, UK South, Sweden Central.
 
-This accelerator can be deployed with or without authentication. 
+### ⚠️ Important: Check Azure OpenAI Quota Availability  
 
-* To install with authentication requires that the installer have the rights to create and register an application identity in their Azure environment.
-After installation is complete, follow the directions in the [App Authentication](./docs/AddAuthentication.md) document to enable authentication.
-* Note: If you install with authentication, all processing history and current processing will be performed for your specific user. If you deploy without authentication, all batch history from the tool will be visible to all users.
+➡️ To ensure sufficient quota is available in your subscription, please follow **[Quota check instructions guide](./docs/quota_check.md)** before you deploy the solution.
+
+| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Modernize-your-Code-Solution-Accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Modernize-your-Code-Solution-Accelerator) |
+|---|---|
 
 ### **Configurable Deployment Settings**  
 
@@ -109,13 +105,17 @@ When you start the deployment, most parameters will have **default values**, but
 | **AI Location** | Location for all AI services resources. This location can be different from the resource group location | None |
 | **Capacity** | Configure capacity for **gpt-4o**. |  5k |
 
+This accelerator can be configured to  use authentication. 
+
+* To use authentication the installer must have the rights to create and register an application identity in their Azure environment.
+After installation is complete, follow the directions in the [App Authentication](./docs/AddAuthentication.md) document to enable authentication.
+* Note: If you enable authentication, all processing history and current processing will be performed for your specific user. Without authentication, all batch history from the tool will be visible to all users.
+
 ### [Optional] Quota Recommendations  
 By default, the **GPT model capacity** in deployment is set to **5k tokens**.  
 > **We recommend increasing the capacity to 200k tokens for optimal performance.** 
 
-To adjust quota settings, follow these [steps](./docs/AzureGPTQuotaSettings.md)  
-
-**⚠️ Warning:**  **Insufficient quota can cause application errors.** Please ensure you have the recommended capacity or request for additional capacity before deploying this solution. 
+To adjust quota settings, follow these [steps](./docs/AzureGPTQuotaSettings.md)
 
 ### Deployment Options
 Pick from the options below to see step-by-step instructions for: GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.
@@ -178,16 +178,6 @@ If you're not using one of the above options for opening the project, then you'l
 
 4. Continue with the [deploying steps](#deploying).
 
-</details>
-<details>
-  <summary><b>Deploy with Bicep/ARM template</b></summary>
-
-### Bicep
-
-   Click the following deployment button to create the required resources for this accelerator directly in your Azure Subscription.
-
-   [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmarktayl1%2Ftestdeploy%2Frefs%2Fheads%2Fmain%2FCodeGenDeploy.json)
-
 </details>
 
 ### Deploying
@@ -246,8 +236,7 @@ Responsible AI Transparency FAQ
 
 Please refer to [Transparency FAQ](./TRANSPARENCY_FAQ.md) for responsible AI transparency details of this solution accelerator.
 
-<h2><img src="./docs/images/read_me/supportingDocuments.png" width="64" style="max-width: 100%;">
-</br>
+<h2>
 Supporting Documentation
 </h2>
 

docs/AzureAccountSetUp.md

@@ -0,0 +1,14 @@
+## Azure account setup
+
+1. Sign up for a [free Azure account](https://azure.microsoft.com/free/) and create an Azure Subscription.
+2. Check that you have the necessary permissions:
+    * Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner).
+    * Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
+
+You can view the permissions for your account and subscription by following the steps below: 
+- Navigate to the [Azure Portal](https://portal.azure.com/) and click on `Subscriptions` under 'Navigation' 
+- Select the subscription you are using for this accelerator from the list. 
+    - If you try to search for your subscription and it does not come up, make sure no filters are selected.
+- Select `Access control (IAM)` and you can see the roles that are assigned to your account for this subscription. 
+    - If you want to see more information about the roles, you can go to the `Role assignments`
+     tab and search by your account name and then click the role you want to view more information about.

docs/images/read_me/agentArchitecture.png

@@ -9,18 +9,18 @@ param aiServicesEndpoint string
 param aiServicesKey string
 param aiServicesId string
 
-var storageName = '${solutionName}hubstorage'
+var storageName = '${solutionName}hubst'
 var storageSkuName = 'Standard_LRS'
-var aiServicesName = '${solutionName}-aiservices'
-var workspaceName = '${solutionName}-workspace'
+var aiServicesName = '${solutionName}-ais'
+var workspaceName = '${solutionName}-log'
 var keyvaultName = '${solutionName}-kv'
 var location = solutionLocation 
-var aiHubName = '${solutionName}-aihub'
-var aiHubFriendlyName = aiHubName
+var azureAiHubName = '${solutionName}-hub'
+var aiHubFriendlyName = azureAiHubName
 var aiHubDescription = 'AI Hub for KM template'
-var aiProjectName = '${solutionName}-aiproject'
+var aiProjectName = '${solutionName}-prj'
 var aiProjectFriendlyName = aiProjectName
-var aiSearchName = '${solutionName}-search'
+var aiSearchName = '${solutionName}-srch'
 
 
 resource keyVault 'Microsoft.KeyVault/vaults@2022-07-01' existing = {
@@ -112,7 +112,7 @@ resource storageroleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-
 }
 
 resource aiHub 'Microsoft.MachineLearningServices/workspaces@2023-08-01-preview' = {
-  name: aiHubName
+  name: azureAiHubName
   location: location
   identity: {
     type: 'SystemAssigned'
@@ -129,7 +129,7 @@ resource aiHub 'Microsoft.MachineLearningServices/workspaces@2023-08-01-preview'
   kind: 'hub'
 
   resource aiServicesConnection 'connections@2024-07-01-preview' = {
-    name: '${aiHubName}-connection-AzureOpenAI'
+    name: '${azureAiHubName}-connection-AzureOpenAI'
     properties: {
       category: 'AIServices'
       target: aiServicesEndpoint

docs/images/read_me/solArchitecture.png

@@ -10,7 +10,7 @@ param solutionName string
 param solutionLocation string
 
 @description('Name')
-param miName string = '${ solutionName }-managed-identity'
+param miName string = '${ solutionName }-id'
 
 resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
   name: miName

infra/deploy_ai_foundry.bicep

@@ -30,12 +30,13 @@ param Prefix string
   'westus3'
 ])
 @description('Location for all Ai services resources. This location can be different from the resource group location.')
-param AiLocation string  // The location used for all deployed resources.  This location must be in the same region as the resource group.
+param AzureAiServiceLocation string  // The location used for all deployed resources.  This location must be in the same region as the resource group.
 param capacity int = 5
 
 var uniqueId = toLower(uniqueString(subscription().id, Prefix, resourceGroup().location))
-var ResourcePrefix = 'cm${padLeft(take(uniqueId, 12), 12, '0')}'
-var imageVersion = 'rc1'
+var UniquePrefix = 'cm${padLeft(take(uniqueId, 12), 12, '0')}'
+var ResourcePrefix = take('cm${Prefix}${UniquePrefix}', 15)
+var imageVersion = 'rc1' // Change to 'fnd01' when ready
 var location  = resourceGroup().location
 var dblocation  = resourceGroup().location
 var cosmosdbDatabase  = 'cmsadb'
@@ -46,9 +47,9 @@ var deploymentType  = 'GlobalStandard'
 var containerName  = 'appstorage'
 var llmModel  = 'gpt-4o'
 var storageSkuName = 'Standard_LRS'
-var storageContainerName = '${ResourcePrefix}ctstor'
+var storageContainerName = '${ResourcePrefix}cast'
 var gptModelVersion = '2024-08-06'
-var aiServicesName = '${ResourcePrefix}-aiservices'
+var azureAiServicesName = '${ResourcePrefix}-ais'
 
 
 
@@ -65,24 +66,24 @@ var aiModelDeployments = [
   }
 ]
 
-resource aiServices 'Microsoft.CognitiveServices/accounts@2024-04-01-preview' = {
-  name: aiServicesName
+resource azureAiServices 'Microsoft.CognitiveServices/accounts@2024-04-01-preview' = {
+  name: azureAiServicesName
   location: location
   sku: {
     name: 'S0'
   }
   kind: 'AIServices'
   properties: {
-    customSubDomainName: aiServicesName
+    customSubDomainName: azureAiServicesName
     apiProperties: {
       statisticsEnabled: false
     }
   }
 }
 
 @batchSize(1)
-resource aiServicesDeployments 'Microsoft.CognitiveServices/accounts/deployments@2023-05-01' = [for aiModeldeployment in aiModelDeployments: {
-  parent: aiServices //aiServices_m
+resource azureAiServicesDeployments 'Microsoft.CognitiveServices/accounts/deployments@2023-05-01' = [for aiModeldeployment in aiModelDeployments: {
+  parent: azureAiServices //aiServices_m
   name: aiModeldeployment.name
   properties: {
     model: {
@@ -124,26 +125,26 @@ module kvault 'deploy_keyvault.bicep' = {
 
 
 // ==========AI Foundry and related resources ========== //
-module aifoundry 'deploy_ai_foundry.bicep' = {
+module azureAifoundry 'deploy_ai_foundry.bicep' = {
   name: 'deploy_ai_foundry'
   params: {
     solutionName: ResourcePrefix
-    solutionLocation: AiLocation
+    solutionLocation: AzureAiServiceLocation
     keyVaultName: kvault.outputs.keyvaultName
     gptModelName: llmModel
     gptModelVersion: gptModelVersion
     managedIdentityObjectId:managedIdentityModule.outputs.managedIdentityOutput.objectId
-    aiServicesEndpoint: aiServices.properties.endpoint
-    aiServicesKey: aiServices.listKeys().key1
-    aiServicesId: aiServices.id
+    aiServicesEndpoint: azureAiServices.properties.endpoint
+    aiServicesKey: azureAiServices.listKeys().key1
+    aiServicesId: azureAiServices.id
   }
   scope: resourceGroup(resourceGroup().name)
 }
 
 module containerAppsEnvironment 'br/public:avm/res/app/managed-environment:0.9.1' = {
   name: toLower('${ResourcePrefix}conAppsEnv')
   params: {
-    logAnalyticsWorkspaceResourceId: aifoundry.outputs.logAnalyticsId
+    logAnalyticsWorkspaceResourceId: azureAifoundry.outputs.logAnalyticsId
     name: toLower('${ResourcePrefix}manenv')
     location: location
     zoneRedundant: false
@@ -152,10 +153,10 @@ module containerAppsEnvironment 'br/public:avm/res/app/managed-environment:0.9.1
 }
 
 module databaseAccount 'br/public:avm/res/document-db/database-account:0.9.0' = {
-  name: toLower('${ResourcePrefix}database')
+  name: toLower('${ResourcePrefix}cosmos')
   params: {
     // Required parameters
-    name: toLower('${ResourcePrefix}databaseAccount')
+    name: toLower('${ResourcePrefix}cosno')
     // Non-required parameters
     enableAnalyticalStorage: true
     location: dblocation
@@ -219,7 +220,7 @@ module databaseAccount 'br/public:avm/res/document-db/database-account:0.9.0' =
 }
 
 module containerAppFrontend 'br/public:avm/res/app/container-app:0.13.0' = {
-  name: toLower('${ResourcePrefix}Frontend')
+  name: toLower('${ResourcePrefix}-Fnt-ca')
   params: {
     managedIdentities: {
       systemAssigned: true
@@ -249,15 +250,15 @@ module containerAppFrontend 'br/public:avm/res/app/container-app:0.13.0' = {
     scaleMinReplicas: 1
     scaleMaxReplicas: 1
     environmentResourceId: containerAppsEnvironment.outputs.resourceId
-    name: toLower('${ResourcePrefix}Frontend')
+    name: toLower('${ResourcePrefix}Fnt')
     // Non-required parameters
     location: location
   }
 }
 
 
 resource containerAppBackend 'Microsoft.App/containerApps@2023-05-01' = {
-  name: toLower('${ResourcePrefix}Backend')
+  name: toLower('${ResourcePrefix}Bck-ca')
   location: location
   identity: {
     type: 'SystemAssigned'
@@ -310,7 +311,7 @@ resource containerAppBackend 'Microsoft.App/containerApps@2023-05-01' = {
             }
             {
               name: 'AZURE_OPENAI_ENDPOINT'
-              value: 'https://${aifoundry.outputs.aiServicesName}.openai.azure.com/'
+              value: 'https://${azureAifoundry.outputs.aiServicesName}.openai.azure.com/'
             }
             {
               name: 'MIGRATOR_AGENT_MODEL_DEPLOY'
@@ -413,7 +414,7 @@ var openAiContributorRoleId = 'a001fd3d-188f-4b5d-821b-7da978bf7442'  // Fixed R
 
 resource openAiRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
   name: guid(containerAppBackend.id, openAiContributorRoleId)
-  scope: aiServices
+  scope: azureAiServices
   properties: {
     roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', openAiContributorRoleId) // OpenAI Service Contributor
     principalId: containerAppBackend.identity.principalId
@@ -430,7 +431,7 @@ resource containers 'Microsoft.Storage/storageAccounts/blobServices/containers@2
   properties: {
     publicAccess: 'None'
   }
-  dependsOn: [aifoundry]
+  dependsOn: [azureAifoundry]
 }]
 
 

infra/deploy_managed_identity.bicep

@@ -1,4 +1,4 @@
 using './main.bicep'
 
-param AiLocation = readEnvironmentVariable('AZURE_LOCATION','japaneast')
+param AzureAiServiceLocation = readEnvironmentVariable('AZURE_LOCATION','japaneast')
 param Prefix = readEnvironmentVariable('AZURE_ENV_NAME','azdtemp')