feat: Standardize Bicep Parameters for km-generic

Author: Avijit-Microsoft

documents/CustomizingAzdParameters.md

@@ -3,51 +3,38 @@
 By default this template will use the environment name as the prefix to prevent naming collisions within Azure. The parameters below show the default values. You only need to run the statements below if you need to change the values. 
 
 
-> To override any of the parameters, run `azd env set <key> <value>` before running `azd up`. On the first azd command, it will prompt you for the environment name. Be sure to choose 3-20 characters alphanumeric unique name. 
+> To override any of the parameters, run `azd env set <PARAMETER_NAME> <VALUE>` before running `azd up`. On the first azd command, it will prompt you for the environment name. Be sure to choose 3-20 charaters alphanumeric unique name. 
 
-Change the Content Understanding Location (allowed values: Sweden Central, Australia East)
+## Parameters
 
-```shell
-azd env set AZURE_CONTENT_UNDERSTANDING_LOCATION 'swedencentral'
-```
-
-Change the Secondary Location (example: eastus2, westus2, etc.)
-
-```shell
-azd env set AZURE_SECONDARY_LOCATION eastus2
-```
-
-Change the Model Deployment Type (allowed values: Standard, GlobalStandard)
-
-```shell
-azd env set AZURE_OPEN_AI_MODEL_DEPLOYMENT_TYPE GlobalStandard
-```
-
-Set the Model Name (allowed values: gpt-4o-mini, gpt-4o, gpt-4)
+| Name                                      | Type    | Default Value            | Purpose                                                                    |
+| ----------------------------------------- | ------- | ------------------------ | -------------------------------------------------------------------------- |
+| `AZURE_LOCATION`                          | string  | ` ` *(empty)*            | Sets the Azure region for resource deployment.                             |
+| `AZURE_ENV_NAME`                          | string  | `env_name`               | Sets the environment name prefix for all Azure resources.                  |
+| `AZURE_CONTENT_UNDERSTANDING_LOCATION`    | string  | `swedencentral`          | Specifies the region for content understanding resources.                  |
+| `AZURE_SECONDARY_LOCATION`                | string  | `eastus2`                | Specifies a secondary Azure region.                                        |
+| `AZURE_OPEN_AI_MODEL_DEPLOYMENT_TYPE`     | string  | `GlobalStandard`         | Defines the model deployment type (allowed: `Standard`, `GlobalStandard`). |
+| `AZURE_OPEN_AI_DEPLOYMENT_MODEL`          | string  | `gpt-4o-mini`            | Specifies the GPT model name (e.g., `gpt-4`, `gpt-4o-mini`).               |
+| `AZURE_ENV_MODEL_VERSION`                 | string  | `2024-07-18`             | Sets the Azure model version (allowed: `2024-08-06`, etc.).                |
+| `AZURE_OPENAI_API_VERSION`            | string  | `2025-01-01-preview`     | Specifies the API version for Azure OpenAI.                                |
+| `AZURE_OPEN_AI_DEPLOYMENT_MODEL_CAPACITY` | integer | `30`                     | Sets the GPT model capacity.                                               |
+| `AZURE_OPENAI_EMBEDDING_MODEL`            | string  | `text-embedding-ada-002` | Sets the name of the embedding model to use.                               |
+| `AZURE_ENV_IMAGETAG`                      | string  | `latest`        | Sets the image tag (`latest`, `dev`, `hotfix`, etc.).   |
+| `AZURE_OPENAI_EMBEDDING_MODEL_CAPACITY`   | integer | `80`                     | Sets the capacity for the embedding model deployment.                      |
+| `AZURE_ENV_LOG_ANALYTICS_WORKSPACE_ID`    | string  | ` ` *(empty)*            | Reuses an existing Log Analytics Workspace instead of creating a new one.  |
 
-```shell
-azd env set AZURE_OPEN_AI_DEPLOYMENT_MODEL gpt-4o-mini
-```
 
-Change the Model Capacity (choose a number based on available GPT model capacity in your subscription)
 
-```shell
-azd env set AZURE_OPEN_AI_DEPLOYMENT_MODEL_CAPACITY 30
-```
+## How to Set a Parameter
 
-Change the Embedding Model 
+To customize any of the above values, run the following command **before** `azd up`:
 
-```shell
-azd env set AZURE_OPENAI_EMBEDDING_MODEL text-embedding-ada-002
+```bash
+azd env set <PARAMETER_NAME> <VALUE>
 ```
 
-Change the Embedding Deployment Capacity (choose a number based on available embedding model capacity in your subscription)
-
-```shell
-azd env set AZURE_OPENAI_EMBEDDING_MODEL_CAPACITY 80
-```
+**Example:**
 
-Set the Log Analytics Workspace Id if you need to reuse the existing workspace which is already existing
-```shell
-azd env set AZURE_ENV_LOG_ANALYTICS_WORKSPACE_ID '/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.OperationalInsights/workspaces/<workspace-name>'
+```bash
+azd env set AZURE_LOCATION westus2
 ```

documents/DeploymentGuide.md

@@ -103,20 +103,24 @@ Consider the following settings during your deployment to modify specific settin
 <details>
   <summary><b>Configurable Deployment Settings</b></summary>
 
-When you start the deployment, most parameters will have **default values**, but you can update the following settings:
-
-| **Setting** | **Description** | **Default value** |
-|------------|----------------|------------|
-| **Azure Region** | The region where resources will be created. | eastus | 
-| **Environment Name** | A **3-20 character alphanumeric value** used to generate a unique ID to prefix the resources. | kmtemplate |
-| **Azure AI Content Understanding Location** | Select from a drop-down list of values. | swedencentral |
-| **Secondary Location** | A **less busy** region for **Azure SQL and Azure Cosmos DB**, useful in case of availability constraints. | eastus2 |
-| **Deployment Type** | Select from a drop-down list. | GlobalStandard |
-| **GPT Model** | Choose from **gpt-4, gpt-4o, gpt-4o-mini** | gpt-4o-mini |  
-| **GPT Model Deployment Capacity** | Configure capacity for **GPT models**. | 30k |
-| **Embedding Model** | Default: **text-embedding-ada-002**. | text-embedding-ada-002 |
-| **Embedding Model Capacity** | Set the capacity for **embedding models**. | 80k |
-| **Existing Log analytics workspace** | To reuse the existing Log analytics workspace Id. |  |
+When you start the deployment, most parameters will have **default values**, but you can update the following settings [here](../documents/CustomizingAzdParameters.md):
+
+| **Setting**                                 | **Description**                                                                                           | **Default value**      |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------- |
+| **Azure Region**                            | The region where resources will be created.                                                               | *(empty)*              |
+| **Environment Name**                        | A **3–20 character alphanumeric value** used to generate a unique ID to prefix the resources.             | env\_name              |
+| **Azure AI Content Understanding Location** | Region for content understanding resources.                                                               | swedencentral          |
+| **Secondary Location**                      | A **less busy** region for **Azure SQL and Azure Cosmos DB**, useful in case of availability constraints. | eastus2                |
+| **Deployment Type**                         | Select from a drop-down list (allowed: `Standard`, `GlobalStandard`).                                     | GlobalStandard         |
+| **GPT Model**                               | Choose from **gpt-4, gpt-4o, gpt-4o-mini**.                                                               | gpt-4o-mini            |
+| **GPT Model Version**                       | The version of the selected GPT model.                                                                    | 2024-07-18             |
+| **OpenAI API Version**                      | The Azure OpenAI API version to use.                                                                      | 2025-01-01-preview     |
+| **GPT Model Deployment Capacity**           | Configure capacity for **GPT models** (in thousands).                                                     | 30k                    |
+| **Embedding Model**                         | Default: **text-embedding-ada-002**.                                                                      | text-embedding-ada-002 |
+| **Embedding Model Capacity**                | Set the capacity for **embedding models** (in thousands).                                                 | 80k                    |
+| **Image Tag**                               | Docker image tag to deploy. Common values: `latest`, `dev`, `hotfix`.                  | latest\_migrated       |
+| **Existing Log Analytics Workspace**        | To reuse an existing Log Analytics Workspace ID.                                                          | *(empty)*              |
+
 
 
 </details>

infra/main.bicep

@@ -37,7 +37,8 @@ param gptModelName string = 'gpt-4o-mini'
 @description('Version of the GPT model to deploy:')
 param gptModelVersion string = '2024-07-18'
 
-var azureOpenAIApiVersion = '2025-01-01-preview'
+param azureOpenAIApiVersion string = '2025-01-01-preview'
+
 
 @minValue(10)
 @description('Capacity of the GPT deployment:')

infra/main.bicepparam

@@ -7,7 +7,9 @@ param secondaryLocation = readEnvironmentVariable('AZURE_SECONDARY_LOCATION', 'e
 param deploymentType = readEnvironmentVariable('AZURE_OPEN_AI_MODEL_DEPLOYMENT_TYPE', 'GlobalStandard')
 param gptModelName = readEnvironmentVariable('AZURE_OPEN_AI_DEPLOYMENT_MODEL', 'gpt-4o-mini')
 param gptModelVersion = readEnvironmentVariable('AZURE_ENV_MODEL_VERSION', '2024-07-18')
+param azureOpenAIApiVersion = readEnvironmentVariable('AZURE_OPENAI_API_VERSION', '2025-01-01-preview')
 param gptDeploymentCapacity = int(readEnvironmentVariable('AZURE_OPEN_AI_DEPLOYMENT_MODEL_CAPACITY', '30'))
 param embeddingModel = readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL', 'text-embedding-ada-002')
+param imageTag = readEnvironmentVariable('AZURE_ENV_IMAGETAG', 'latest')
 param embeddingDeploymentCapacity = int(readEnvironmentVariable('AZURE_OPENAI_EMBEDDING_MODEL_CAPACITY', '80'))
 param existingLogAnalyticsWorkspaceId = readEnvironmentVariable('AZURE_ENV_LOG_ANALYTICS_WORKSPACE_ID', '')

infra/main.json

@@ -5,7 +5,7 @@
     "_generator": {
       "name": "bicep",
       "version": "0.36.1.42791",
-      "templateHash": "14571116812938220669"
+      "templateHash": "2363441728169448979"
     }
   },
   "parameters": {
@@ -71,6 +71,10 @@
         "description": "Version of the GPT model to deploy:"
       }
     },
+    "azureOpenAIApiVersion": {
+      "type": "string",
+      "defaultValue": "2025-01-01-preview"
+    },
     "gptDeploymentCapacity": {
       "type": "int",
       "defaultValue": 30,
@@ -336,7 +340,6 @@
       }
     },
     "abbrs": "[variables('$fxv#0')]",
-    "azureOpenAIApiVersion": "2025-01-01-preview",
     "solutionLocation": "[if(empty(parameters('AZURE_LOCATION')), resourceGroup().location, parameters('AZURE_LOCATION'))]",
     "uniqueId": "[toLower(uniqueString(subscription().id, parameters('environmentName'), variables('solutionLocation')))]",
     "solutionPrefix": "[format('km{0}', padLeft(take(variables('uniqueId'), 12), 12, '0'))]",
@@ -601,7 +604,7 @@
             "value": "[parameters('gptModelVersion')]"
           },
           "azureOpenAIApiVersion": {
-            "value": "[variables('azureOpenAIApiVersion')]"
+            "value": "[parameters('azureOpenAIApiVersion')]"
           },
           "gptDeploymentCapacity": {
             "value": "[parameters('gptDeploymentCapacity')]"
@@ -2492,7 +2495,7 @@
             "value": {
               "AZURE_OPEN_AI_DEPLOYMENT_MODEL": "[parameters('gptModelName')]",
               "AZURE_OPEN_AI_ENDPOINT": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_ai_foundry'), '2022-09-01').outputs.aiServicesTarget.value]",
-              "AZURE_OPENAI_API_VERSION": "[variables('azureOpenAIApiVersion')]",
+              "AZURE_OPENAI_API_VERSION": "[parameters('azureOpenAIApiVersion')]",
               "AZURE_OPENAI_RESOURCE": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_ai_foundry'), '2022-09-01').outputs.aiServicesName.value]",
               "AZURE_AI_AGENT_ENDPOINT": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_ai_foundry'), '2022-09-01').outputs.projectEndpoint.value]",
               "AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME": "[parameters('gptModelName')]",
@@ -2505,7 +2508,7 @@
               "SQLDB_SERVER": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_sql_db'), '2022-09-01').outputs.sqlServerName.value]",
               "SQLDB_USERNAME": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_sql_db'), '2022-09-01').outputs.sqlDbUser.value]",
               "SQLDB_USER_MID": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_managed_identity'), '2022-09-01').outputs.managedIdentityBackendAppOutput.value.clientId]",
-              "OPENAI_API_VERSION": "[variables('azureOpenAIApiVersion')]",
+              "OPENAI_API_VERSION": "[parameters('azureOpenAIApiVersion')]",
               "AZURE_AI_SEARCH_ENDPOINT": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_ai_foundry'), '2022-09-01').outputs.aiSearchTarget.value]",
               "AZURE_AI_SEARCH_API_KEY": "[format('@Microsoft.KeyVault(SecretUri={0}secrets/AZURE-SEARCH-KEY/)', reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_keyvault'), '2022-09-01').outputs.keyvaultUri.value)]",
               "AZURE_AI_SEARCH_INDEX": "call_transcripts_index",
@@ -3240,15 +3243,15 @@
     },
     "AZURE_OPENAI_API_VERSION": {
       "type": "string",
-      "value": "[variables('azureOpenAIApiVersion')]"
+      "value": "[parameters('azureOpenAIApiVersion')]"
     },
     "AZURE_OPENAI_RESOURCE": {
       "type": "string",
       "value": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, resourceGroup().name), 'Microsoft.Resources/deployments', 'deploy_ai_foundry'), '2022-09-01').outputs.aiServicesName.value]"
     },
     "OPENAI_API_VERSION": {
       "type": "string",
-      "value": "[variables('azureOpenAIApiVersion')]"
+      "value": "[parameters('azureOpenAIApiVersion')]"
     },
     "REACT_APP_LAYOUT_CONFIG": {
       "type": "string",