Merge pull request #1 from microsoft/main

merge changes from main repo to fork

Author: Kanchan-Microsoft

.github/workflows/deploy-KMGeneric.yml

@@ -14,7 +14,7 @@ on:
 env:
   GPT_MIN_CAPACITY: 150
   TEXT_EMBEDDING_MIN_CAPACITY: 80
-  BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
+  BRANCH_NAME: ${{ github.event.workflow_run.head_branch || github.head_ref || github.ref_name }}
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -112,15 +112,19 @@ jobs:
           echo "Generated SOLUTION_PREFIX: ${UNIQUE_SOLUTION_PREFIX}" 
       - name: Determine Tag Name Based on Branch
         id: determine_tag
-        run: echo "tagname=${{ github.ref_name == 'main' && 'latest_fdp' || github.ref_name == 'dev' && 'dev' || github.ref_name == 'demo' && 'demo' || github.ref_name == 'dependabotchanges' && 'dependabotchanges' || github.head_ref || 'default' }}" >> $GITHUB_OUTPUT
+        run: echo "tagname=${{ github.ref_name == 'main' && 'latest_waf' || github.ref_name == 'dev' && 'dev' || github.ref_name == 'demo' && 'demo' || github.ref_name == 'dependabotchanges' && 'dependabotchanges' || 'latest_waf' }}" >> $GITHUB_OUTPUT
       - name: Deploy Bicep Template
         id: deploy
         run: |
           set -e
+
+          # Generate current timestamp in desired format: YYYY-MM-DDTHH:MM:SS.SSSSSSSZ
+            current_date=$(date -u +"%Y-%m-%dT%H:%M:%S.%7NZ")
+          
           az deployment group create \
             --resource-group ${{ env.RESOURCE_GROUP_NAME }} \
             --template-file infra/main.bicep \
-            --parameters solutionName=${{env.SOLUTION_PREFIX}} contentUnderstandingLocation="swedencentral" secondaryLocation="${{ env.AZURE_LOCATION }}" imageTag=${{ steps.determine_tag.outputs.tagname }} gptDeploymentCapacity=150 aiDeploymentsLocation="${{ env.AZURE_LOCATION }}" createdBy="Pipeline" 
+            --parameters solutionName=${{env.SOLUTION_PREFIX}} contentUnderstandingLocation="swedencentral" secondaryLocation="${{ env.AZURE_LOCATION }}" imageTag=${{ steps.determine_tag.outputs.tagname }} gptDeploymentCapacity=150 azureAiServiceLocation="${{ env.AZURE_LOCATION }}" createdBy="Pipeline" tags="{'SecurityControl':'Ignore','Purpose':'Deploying and Cleaning Up Resources for Validation','CreatedDate':'$current_date'}"
 
      
 

.github/workflows/docker-build.yml

@@ -49,7 +49,7 @@ jobs:
         id: determine_tag
         run: |
          if [[ "${{ github.ref_name }}" == "main" ]]; then
-          echo "tagname=latest_fdp" >> $GITHUB_OUTPUT
+          echo "tagname=latest_waf" >> $GITHUB_OUTPUT
          elif [[ "${{ github.ref_name }}" == "dev" ]]; then
           echo "tagname=dev" >> $GITHUB_OUTPUT
          elif [[ "${{ github.ref_name }}" == "demo" ]]; then

azure.yaml

@@ -7,7 +7,7 @@ environment:
 name: conversation-knowledge-mining
 
 requiredVersions:
-  azd: ">= 1.15.0"
+  azd: ">= 1.18.0"
 
 metadata:
   template: [email protected]

documents/ACRBuildAndPushGuide.md

@@ -0,0 +1,93 @@
+# Azure Container Registry (ACR) – Build & Push Guide
+
+This guide provides step-by-step instructions to build and push Docker images for **WebApp** and **Backend** services into Azure Container Registry (ACR).
+
+## 📋 Prerequisites
+Before starting, ensure you have:
+- An active [Azure Subscription](https://portal.azure.com/)
+- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) installed and logged in
+- [Docker Desktop](https://docs.docker.com/get-docker/) installed and running
+- Access to your Azure Container Registry (ACR)
+- To create an Azure Container Registry (ACR), you can refer to the following guides:
+
+    - [Create Container Registry using Azure CLI](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-get-started-azure-cli)
+
+    - [Create Container Registry using Azure Portal](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-get-started-portal?tabs=azure-cli)
+
+    - [Create Container Registry using PowerShell](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-get-started-powershell)
+
+    - [Create Container Registry using ARM Template](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-get-started-geo-replication-template)
+
+    - [Create Container Registry using Bicep](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-get-started-bicep?tabs=CLI)
+
+---
+
+Login to ACR :
+``` bash
+az acr login --name $ACR_NAME
+```
+
+## 🚀 Build and Push Images
+
+**Backend :** 
+ 
+ ```bash 
+az acr login --name <containerregname>
+docker build --no-cache -f api/ApiApp.Dockerfile -t <acrloginserver>/<repo>:<tagname> .
+docker push <acrloginserver>/<repo>:<tagname>
+ ```
+
+If you want to update image tag and image manually you can follow below steps:
+- Go to your api App Service in the [Azure Portal](https://portal.azure.com/#home).
+- In the left menu, select Deployment → Deployment Center
+- Under Registry settings, you can configure:
+
+    - Image Source → (e.g., Azure Container Registry / Docker Hub / Other).
+
+    - Image Name → e.g., myapp/backend.
+
+    - Tag → e.g., v1.2.3.
+
+![alt text](./Images/AppServiceContainer.png)
+
+**WebApp :**
+
+```bash
+az acr login --name <containerregname>
+docker build --no-cache -f App/WebApp.Dockerfile -t <acrloginserver>/<repo>:<tagname> .
+docker push <acrloginserver>/<repo>:<tagname>
+```
+
+If you want to update image tag and image manually you can follow below steps:
+- Go to your App Service in the [Azure Portal](https://portal.azure.com/#home).
+- In the left menu, select Deployment → Deployment Center
+- Under Registry settings, you can configure:
+
+    - Image Source → (e.g., Azure Container Registry / Docker Hub / Other).
+
+    - Image Name → e.g., myapp/backend.
+
+    - Tag → e.g., v1.2.3.
+
+![alt text](./Images/AppServiceContainer.png)
+
+
+## ✅ Verification
+
+Run the following command to verify that images were pushed successfully:
+```bash
+az acr repository list --name $ACR_NAME --output table
+```
+
+You should see repositories in the output.
+
+## 📝 Notes
+
+- Always use meaningful tags (v1.0.0, staging, prod) instead of just latest.
+
+- If you are pushing from a CI/CD pipeline, make sure the pipeline agent has access to Docker and ACR.
+
+- For private images, ensure your services (e.g., Azure Container Apps, AKS, App Service) are configured with appropriate ACR pull permissions.
+
+
+

documents/CustomizeData.md

@@ -21,3 +21,17 @@ If you would like to update the solution to leverage your own data please follow
     ```
     a. resourcegroupname_param - the name of the resource group.
 
+> Note (WAF‑aligned deployments): If you deployed the solution with the WAF / private networking option enabled, you must run the data processing script **from inside the deployed VM (jumpbox / processing VM)** so it can reach the private endpoints. Follow these steps:
+>
+> 1. Connect to the VM (Azure Bastion, SSH, or RDP depending on OS).
+> 2. Ensure the repo (or the `infra/scripts` folder) is present. If not, clone or pull it.
+> 3. Open a Bash-compatible shell (Git Bash on Windows, or native bash on Linux).
+> 4. Run `az login` (add `--tenant <tenantId>` if required by your org policy).
+> 5. Navigate to `infra/scripts` and execute:
+>    ```bash
+>    bash run_process_data_scripts.sh <resource-group-name>
+>    ```
+> 6. Replace `<resource-group-name>` with the name of the resource group you deployed (same value used for `resourcegroupname_param`).
+>
+> Tip: If Azure CLI is not installed on the VM, install it first (see official docs) before running the script.
+

documents/CustomizingAzdParameters.md

@@ -19,12 +19,13 @@ By default this template will use the environment name as the prefix to prevent
 | `AZURE_OPENAI_API_VERSION`            | string  | `2025-01-01-preview`     | Specifies the API version for Azure OpenAI.                                |
 | `AZURE_OPENAI_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_ENV_IMAGETAG`                      | string  | `latest_waf`        | Sets the image tag (`latest_waf`, `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  | Guide to get your [Existing Workspace ID](/documents/re-use-log-analytics.md)            | Reuses an existing Log Analytics Workspace instead of creating a new one.  |
 | `USE_LOCAL_BUILD`    | string  | `false`           | Indicates whether to use a local container build for deployment.  |
 | `AZURE_EXISTING_AI_PROJECT_RESOURCE_ID`    | string  | `<Existing AI Project resource Id>`            | Reuses an existing AIFoundry and AIFoundryProject 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

documents/DeploymentGuide.md

@@ -32,6 +32,45 @@ This will allow the scripts to run for the current session without permanently c
 
 ## 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.
+
+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:
+
+  - Enhanced network security (e.g., Network protection with private endpoints)
+  - Stricter access controls and managed identities
+  - Logging, monitoring, and diagnostics enabled by default
+  - Resource tagging and cost management recommendations
+
+**How to choose your deployment configuration:**
+
+* 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`
+
+---
+
+### VM Credentials Configuration
+
+By default, the solution sets the VM administrator username and password from environment variables.
+
+To set your own VM credentials before deployment, use:
+
+```sh
+azd env set AZURE_ENV_VM_ADMIN_USERNAME <your-username>
+azd env set AZURE_ENV_VM_ADMIN_PASSWORD <your-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.
+
+> [!IMPORTANT]
+> The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates.
+
+### Deployment Steps
+
 Pick from the options below to see step-by-step instructions for GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.
 
 | [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Conversation-Knowledge-Mining-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/Conversation-Knowledge-Mining-Solution-Accelerator) | 
@@ -80,7 +119,7 @@ If you're not using one of the above options for opening the project, then you'l
 
 1. Make sure the following tools are installed:
     - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.5) <small>(v7.0+)</small> - available for Windows, macOS, and Linux.
-    - [Azure Developer CLI (azd)](https://aka.ms/install-azd) <small>(v1.15.0+)</small> - version
+    - [Azure Developer CLI (azd)](https://aka.ms/install-azd) <small>(v1.18.0+)</small> - version
     - [Python 3.9+](https://www.python.org/downloads/)
     - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
     - [Git](https://git-scm.com/downloads)
@@ -118,7 +157,7 @@ When you start the deployment, most parameters will have **default values**, but
 | **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       |
+| **Image Tag**                               | Docker image tag to deploy. Common values: `latest_waf`, `dev`, `hotfix`.                  | latest_waf       |
 | **Use Local Build**                         | Boolean flag to determine if local container builds should be used.                         | false             |
 | **Existing Log Analytics Workspace**        | To reuse an existing Log Analytics Workspace ID.                                                          | *(empty)*              |
 | **Existing Azure AI Foundry Project**        | To reuse an existing Azure AI Foundry Project ID instead of creating a new one.              | *(empty)*          |

documents/Images/AppServiceContainer.png

@@ -15,7 +15,7 @@ Install these tools before you start:
 - [PowerShell 7.0+](https://github.com/PowerShell/PowerShell#get-powershell).
 - [Node.js (LTS)](https://nodejs.org/en).
 - [Git](https://git-scm.com/downloads).
-- [Azure Developer CLI (azd) v1.15.0+](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd).
+- [Azure Developer CLI (azd) v1.18.0+](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd).
 - [Microsoft ODBC Driver 17](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) for SQL Server.