From bdbf32504ca40fc705a2b88b6af7e1568a4a6a00 Mon Sep 17 00:00:00 2001 From: Abdul-Microsoft Date: Tue, 2 Sep 2025 15:36:04 +0530 Subject: [PATCH 1/3] Enhance documentation and configuration for Azure deployment parameters, including VM credentials and Azure Developer CLI requirements. --- docs/CustomizingAzdParameters.md | 2 ++ docs/DeploymentGuide.md | 56 +++++++++++++++++++++++--------- infra/main.bicep | 5 ++- infra/main.parameters.json | 4 +-- infra/main.waf.parameters.json | 4 +-- 5 files changed, 51 insertions(+), 20 deletions(-) diff --git a/docs/CustomizingAzdParameters.md b/docs/CustomizingAzdParameters.md index bc28fc345..79830249a 100644 --- a/docs/CustomizingAzdParameters.md +++ b/docs/CustomizingAzdParameters.md @@ -19,6 +19,8 @@ By default this template will use the environment name as the prefix to prevent | `AZURE_ENV_IMAGETAG` | string | `latest` | Docker image tag used for container deployments. | | `AZURE_ENV_ENABLE_TELEMETRY` | bool | `true` | Enables telemetry for monitoring and diagnostics. | | `AZURE_ENV_LOG_ANALYTICS_WORKSPACE_ID` | string | Guide to get your [Existing Workspace ID](/docs/re-use-log-analytics.md) | Set this if you want to reuse an existing Log Analytics Workspace instead of creating a new one. | +| `AZURE_ENV_VM_ADMIN_USERNAME` | string | `take(newGuid(), 20)` | The administrator username for the virtual machine. | +| `AZURE_ENV_VM_ADMIN_PASSWORD` | string | `newGuid()` | The administrator password for the virtual machine. | --- ## How to Set a Parameter diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index fb4fca41a..83c109e59 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -26,17 +26,41 @@ Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass This will allow the scripts to run for the current session without permanently changing your system's policy. +### **Azure Developer CLI (azd) Requirement** + +Ensure that you are using the latest version of the [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/overview). +The `azd` version must be **1.18.0 or higher**. + +Upgrade commands by OS: + +* **Windows (using winget):** + + ```bash + winget install microsoft.azd + ``` + +* **Linux (using apt):** + + ```bash + curl -fsSL https://aka.ms/install-azd.sh | bash + ``` + +* **macOS (using Homebrew):** + + ```bash + brew update && brew tap azure/azd && brew install azd + ``` + ## Deployment Options & Steps ### Sandbox or WAF Aligned Deployment Options The [`infra`](../infra) folder of the Multi Agent Solution Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution. -When running `azd up`, you’ll now be prompted to choose between a **WAF-aligned configuration** and a **sandbox configuration** using a simple selection: +By default, the `azd up` command uses the `main.parameters.json` file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration. -- A **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration. +For **production deployments**, the repository also provides [`main.waf.parameters.json`](../infra/main.waf.parameters.json), which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as: -- A **production deployments environment**, which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as: - Enhanced network security (e.g., Network protection with private endpoints) - Stricter access controls and managed identities - Logging, monitoring, and diagnostics enabled by default @@ -44,24 +68,26 @@ When running `azd up`, you’ll now be prompted to choose between a **WAF-aligne **How to choose your deployment configuration:** -When prompted during `azd up`: +* Use the default `main.parameters.json` file for a **sandbox/dev environment** +* For a **WAF-aligned, production-ready deployment**, copy the contents of `main.waf.parameters.json` into `main.parameters.json` before running `azd up` + +--- -![useWAFAlignedArchitecture](images/macae_waf_prompt.png) +### VM Credentials Configuration -- Select **`true`** to deploy a **WAF-aligned, production-ready environment** -- Select **`false`** to deploy a **lightweight sandbox/dev environment** +By default, the solution sets the VM administrator username and password from environment variables. +If you do not configure these values, a randomly generated GUID will be used for both the username and password. + +To set your own VM credentials before deployment, use: + +```sh +azd env set AZURE_ENV_VM_ADMIN_USERNAME +azd env set AZURE_ENV_VM_ADMIN_PASSWORD +``` > [!TIP] > Always review and adjust parameter values (such as region, capacity, security settings and log analytics workspace configuration) to match your organization’s requirements before deploying. For production, ensure you have sufficient quota and follow the principle of least privilege for all identities and role assignments. -> To reuse an existing Log Analytics workspace, update the existingWorkspaceResourceId field under the logAnalyticsWorkspaceConfiguration parameter in the .bicep file with the resource ID of your existing workspace. -For example: -``` -param logAnalyticsWorkspaceConfiguration = { - dataRetentionInDays: 30 - existingWorkspaceResourceId: '/subscriptions//resourceGroups//providers/Microsoft.OperationalInsights/workspaces/' -} -``` > [!IMPORTANT] > The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates. diff --git a/infra/main.bicep b/infra/main.bicep index 77b791f19..1fc9582c4 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -709,13 +709,16 @@ module maintenanceConfiguration 'br/public:avm/res/maintenance/maintenance-confi } var dataCollectionRulesResourceName = 'dcr-${solutionSuffix}' +var dataCollectionRulesLocation = useExistingLogAnalytics + ? existingLogAnalyticsWorkspace!.location + : logAnalyticsWorkspace!.outputs.location module windowsVmDataCollectionRules 'br/public:avm/res/insights/data-collection-rule:0.6.1' = if (enablePrivateNetworking && enableMonitoring) { name: take('avm.res.insights.data-collection-rule.${dataCollectionRulesResourceName}', 64) params: { name: dataCollectionRulesResourceName tags: tags enableTelemetry: enableTelemetry - location: location + location: dataCollectionRulesLocation dataCollectionRuleProperties: { kind: 'Windows' dataSources: { diff --git a/infra/main.parameters.json b/infra/main.parameters.json index 51a67a7cf..14965085a 100644 --- a/infra/main.parameters.json +++ b/infra/main.parameters.json @@ -24,10 +24,10 @@ "value": "${AZURE_ENV_MODEL_CAPACITY}" }, "backendContainerImageTag": { - "value": "${AZURE_ENV_IMAGE_TAG}" + "value": "${AZURE_ENV_IMAGE_TAG=latest}" }, "frontendContainerImageTag": { - "value": "${AZURE_ENV_IMAGE_TAG}" + "value": "${AZURE_ENV_IMAGE_TAG=latest}" }, "enableTelemetry": { "value": "${AZURE_ENV_ENABLE_TELEMETRY}" diff --git a/infra/main.waf.parameters.json b/infra/main.waf.parameters.json index 1da6bfd32..c6fd16c49 100644 --- a/infra/main.waf.parameters.json +++ b/infra/main.waf.parameters.json @@ -24,10 +24,10 @@ "value": "${AZURE_ENV_MODEL_CAPACITY}" }, "backendContainerImageTag": { - "value": "${AZURE_ENV_IMAGE_TAG}" + "value": "${AZURE_ENV_IMAGE_TAG=latest}" }, "frontendContainerImageTag": { - "value": "${AZURE_ENV_IMAGE_TAG}" + "value": "${AZURE_ENV_IMAGE_TAG=latest}" }, "enableTelemetry": { "value": "${AZURE_ENV_ENABLE_TELEMETRY}" From b339965bc1d4bfe4ca8f3fd0971638bba1dc04db Mon Sep 17 00:00:00 2001 From: Abdul-Microsoft Date: Tue, 2 Sep 2025 15:39:34 +0530 Subject: [PATCH 2/3] Fix link formatting for main.parameters.json in Deployment Guide --- docs/DeploymentGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 83c109e59..e41c4422c 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -57,7 +57,7 @@ Upgrade commands by OS: The [`infra`](../infra) folder of the Multi Agent Solution Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution. -By default, the `azd up` command uses the `main.parameters.json` file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration. +By default, the `azd up` command uses the [`main.parameters.json`](../infra/main.parameters.json)` file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration. For **production deployments**, the repository also provides [`main.waf.parameters.json`](../infra/main.waf.parameters.json), which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as: From b3c771f77bd2ee7dc2d4815508ffffc4e9556e76 Mon Sep 17 00:00:00 2001 From: Abdul-Microsoft Date: Tue, 2 Sep 2025 15:41:14 +0530 Subject: [PATCH 3/3] Fix formatting issue in Deployment Guide for main.parameters.json reference --- docs/DeploymentGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index e41c4422c..7cc4aced2 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -57,7 +57,7 @@ Upgrade commands by OS: The [`infra`](../infra) folder of the Multi Agent Solution Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution. -By default, the `azd up` command uses the [`main.parameters.json`](../infra/main.parameters.json)` file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration. +By default, the `azd up` command uses the [`main.parameters.json`](../infra/main.parameters.json) file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration. For **production deployments**, the repository also provides [`main.waf.parameters.json`](../infra/main.waf.parameters.json), which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as: