Updates and clarification of post provisioning script and environment validation.

Update PostgreSQL mirroring steps

Author: Mike Swantek

docs/deploy_app_from_foundry.md

@@ -6,6 +6,8 @@ This guide explains how to deploy a chat application directly from the Microsoft
 
 Microsoft Foundry provides a built-in capability to publish playground experiences as web applications. This accelerator deploys the required infrastructure (App Service, managed identity, networking) so you can publish directly from the Foundry playground.
 
+> **UI note:** The new Foundry experience (the "New Foundry" toggle) does not currently show **Deploy to a web app**. Use the classic Foundry UI to publish for now. We will update this guide once the new UI supports web app deployment.
+
 ## Prerequisites
 
 - Completed deployment of this accelerator (`azd up`)
@@ -42,6 +44,8 @@ Since all resources are deployed with private endpoints, you must access Microso
 
 ### 4. Deploy to Web App
 
+> **UI note:** If the "New Foundry" toggle is enabled, the **Deploy to a web app** option may be hidden. Switch to the classic Foundry UI to publish the web app.
+
 1. Click **Deploy** → **Deploy to a web app**
 2. Configure deployment options:
    - **Create new** or **Update existing** web app

docs/post_deployment_steps.md

@@ -1,6 +1,6 @@
 # Post Deployment Steps
 
-After running `azd up` or `azd provision` followed by `azd hooks run postprovision`, use these steps to verify that all components were deployed correctly and are functioning as expected.
+After running `azd up` or `azd provision` which then trigger the `azd hooks run postprovision`, use these steps to verify that all components were deployed correctly and are functioning as expected.
 
 ---
 
@@ -10,8 +10,9 @@ After running `azd up` or `azd provision` followed by `azd hooks run postprovisi
 |-----------|---------------|----------------|
 | Fabric Capacity | Azure Portal → Microsoft Fabric capacities | **Active** (not Paused) |
 | Fabric Workspace | [app.fabric.microsoft.com](https://app.fabric.microsoft.com) | Workspace visible with 3 lakehouses |
+| PostgreSQL Flexible Server | Azure Portal → Azure Database for PostgreSQL flexible servers | **Ready** |
 | Microsoft Foundry project | [ai.azure.com](https://ai.azure.com) | Project accessible, models deployed |
-| AI Search Index | Azure Portal → AI Search → Indexes | `onelake-index` exists with documents |
+| AI Search Index | Azure Portal → AI Search → Indexes | `onelake-index` exists |
 | Purview Scan | Purview Portal → Data Map → Sources | Fabric data source registered |
 
 ---
@@ -45,33 +46,30 @@ az fabric capacity resume --capacity-name <capacity-name> --resource-group <rg-n
    - **gold** — Curated analytics-ready data
 
 5. Open the **bronze** lakehouse and verify the `Files/documents` folder structure exists
-6. In the workspace, check each lakehouse (**bronze**, **silver**, **gold**) and confirm the **Sensitivity label** matches the value set in the parameter file.
 
 ### Optional PostgreSQL Mirroring Follow-Up
 
-End-to-end mirroring is not part of `azd up` or post-provisioning. Some steps are manual.
+End-to-end mirroring is not complete when running `azd up` or post-provisioning. Some steps are manual.
 
 For the full steps (including the Fabric portal **New item** mirror), follow [PostgreSQL mirroring](./postgresql_mirroring.md).
 
 ---
 
-## 3. Verify Microsoft Foundry Project
+## 3. Verify PostgreSQL Flexible Server (if enabled)
 
-1. Navigate to [ai.azure.com](https://ai.azure.com)
-2. Sign in and select your Microsoft Foundry project
-3. Verify:
-   - **Models** — Check that GPT-4o and text-embedding-ada-002 (or configured models) are deployed
-   - **Connections** — AI Search connection should be listed
-   - **Playground** — Test the chat playground with a sample query
+The PostgreSQL server must be in **Running** state to accept connections.
 
-### Testing AI Search Connection in Playground
+1. Navigate to **Azure Portal** → **Azure Database for PostgreSQL flexible servers**
+2. Select the server created by the deployment
+3. Verify the **Status** shows **Ready** and the **State** shows **Running**
 
-1. In Microsoft Foundry, go to **Playgrounds** → **Chat**
-2. Click **Add your data**
-3. Select your AI Search index (`onelake-index`)
-4. Ask a question about your indexed documents
+### Optional: Test PostgreSQL Connectivity
 
-If the connection fails, verify RBAC roles are assigned (see Troubleshooting section).
+Use the connection details from the Azure Portal **Connection strings** blade or from your `azd` environment values.
+
+```bash
+psql "host=<server>.postgres.database.azure.com port=5432 dbname=<db-name> user=<username> sslmode=require"
+```
 
 ---
 
@@ -108,12 +106,46 @@ If no documents appear, check:
 
 ---
 
-## 5. Verify Purview Integration (if enabled)
+## 5. Verify Microsoft Foundry Project
+
+1. Navigate to [ai.azure.com](https://ai.azure.com)
+2. Sign in and select your Microsoft Foundry project
+3. Verify:
+   - **Models** — Check that GPT-4o and text-embedding-ada-002 (or configured models) are deployed
+   - **Connections** — AI Search connection should be listed
+   - **Playground** — Test the chat playground with a sample query
+
+### Testing AI Search Connection in Playground
+
+Before testing, upload at least one sample PDF into the bronze lakehouse (Files/documents) and re-run the indexer.
+
+Re-run the indexer in the Azure portal:
+
+1. Navigate to **Azure Portal** → **AI Search** → your search service
+2. Go to **Indexers** and select `onelake-indexer`
+3. Click **Run**
+
+Or run it from the CLI:
+
+```bash
+az search indexer run --name onelake-indexer --service-name <search-name> --resource-group <rg>
+```
+
+1. In Microsoft Foundry, go to **Playgrounds** → **Chat**
+2. Click **Add your data**
+3. Select your AI Search index (`onelake-index`)
+4. Ask a question about your indexed documents
+
+If the connection fails, verify RBAC roles are assigned (see Troubleshooting section).
+
+---
+
+## 6. Verify Purview Integration (if enabled)
 
 1. Navigate to the **Microsoft Purview governance portal**
 2. Go to **Data Map** → **Sources**
-3. Verify the Fabric data source is registered (e.g., `Fabric-Workspace-<id>`)
-4. Check **Scans** to see if the initial scan completed
+3. Verify the Fabric data source is registered at the container level and the collection is `collection-<envname>`
+4. Check **Scans** to confirm the workspace-scoped scan completed
 
 If `purviewCollectionName` is left empty in [infra/main.bicepparam](../infra/main.bicepparam), the automation now uses `collection-<AZURE_ENV_NAME>`.
 
@@ -131,9 +163,9 @@ Lineage appears only after you run data movement or transformation jobs (for exa
 
 ---
 
-## 6. Verify Network Isolation (if enabled)
+## 7. Verify Network Isolation in Azure Portal (if enabled)
 
-When `networkIsolation` is set to `true`:
+When `networkIsolation` is set to `true` in [infra/main.bicepparam](../infra/main.bicepparam) during provisioning:
 
 ### Check Microsoft Foundry Network Settings
 
@@ -159,7 +191,7 @@ This is **expected behavior** — the resources are only accessible from within
 
 ---
 
-## 7. Connecting via Bastion (Network Isolated Deployments)
+## 8. Connecting via Bastion (Network Isolated Deployments)
 
 For network-isolated deployments, use Azure Bastion to access resources:
 
@@ -176,6 +208,9 @@ For network-isolated deployments, use Azure Bastion to access resources:
    ![Image showing bastion blade](../img/provisioning/checkNetworkIsolation7.png)
 
 4. Enter the VM admin credentials (set during deployment) and click **Connect**
+   - Admin username: `vmUserName` in [infra/main.bicep](../infra/main.bicep)
+   - Admin password: `vmAdminPassword` in [infra/main.bicepparam](../infra/main.bicepparam) (defaults to the `VM_ADMIN_PASSWORD` environment variable)
+   - If you do not have them, reset the password in **Azure Portal** → **Virtual machine** → **Reset password**.
 
    ![Image showing bastion login](../img/provisioning/checkNetworkIsolation8.png)
 
@@ -232,6 +267,7 @@ pwsh ./scripts/automationScripts/OneLakeIndex/06_setup_ai_foundry_search_rbac.ps
 
 1. Verify documents exist in the bronze lakehouse:
    - Go to Fabric → bronze lakehouse → Files → documents
+   - If needed, follow [Testing AI Search Connection in Playground](#testing-ai-search-connection-in-playground) to upload a sample PDF
 
 2. Check indexer status:
    - Azure Portal → AI Search → Indexers → `onelake-indexer`
@@ -275,8 +311,10 @@ pwsh ./scripts/automationScripts/<path-to-script>.ps1
 
 Once verification is complete:
 
-1. **Upload documents** to the bronze lakehouse for indexing
-2. **Test the Microsoft Foundry playground** with your indexed content
-3. **Configure additional models** if needed
-4. **[Deploy your app](./deploy_app_from_foundry.md)** from the Microsoft Foundry playground
-5. **Review governance** in Microsoft Purview
+1. **Upload documents** to the bronze lakehouse for indexing (if you haven't already in previous steps)
+2. **Test PostgreSQL connectivity** (if you plan to use the database)
+3. **Complete PostgreSQL mirroring in Fabric** (if needed) — follow [PostgreSQL mirroring](./postgresql_mirroring.md)
+4. **Test the Microsoft Foundry playground** with your indexed content
+5. **Configure additional models** if needed
+6. **[Deploy your app](./deploy_app_from_foundry.md)** from the Microsoft Foundry playground
+7. **Review governance** in Microsoft Purview

docs/postgresql_mirroring.md

@@ -4,6 +4,13 @@ This guide explains how to complete PostgreSQL mirroring in Microsoft Fabric aft
 
 > **Security-critical note:** The mirroring prep script must run from a VNet-connected host when Key Vault and PostgreSQL are private. If you want to demo the full end-to-end mirroring flow from a non-VNet machine, you must temporarily open access to both Key Vault and PostgreSQL before running the script, then re-lock them afterward. Treat this as a deliberate security step, not a default configuration.
 
+> **Resource naming note:** The AI Landing Zone submodule deploys Foundry and agent resources with an `ai-` prefix, including a separate Key Vault, Storage Account, and Cosmos DB. PostgreSQL mirroring uses the main deployment Key Vault from `keyVaultResourceId` (this is where the `postgreSql*` secrets live), not the `ai-` prefixed Key Vault. When a step says "Key Vault" in this doc, use the Key Vault from `keyVaultResourceId`.
+>
+> **How to find `keyVaultResourceId`:**
+> - Run `azd env get-value keyVaultResourceId` from the repo root.
+> - Or run `azd env get-values` and look for `keyVaultResourceId`.
+> - Or in Azure Portal, open the Key Vault used for deployment and copy its **Resource ID** from the **Overview** blade.
+
 Mirroring automation in the current branch is set for PostgreSQL deployments where `postgreSqlNetworkIsolation = false`.
 
 For the public/manual path, this repo now supports a declarative firewall toggle through `postgreSqlAllowAzureServices`.
@@ -36,30 +43,38 @@ param postgreSqlNetworkIsolation = false
 param postgreSqlAllowAzureServices = true
 ```
 
-1. Run `azd up` and let postprovision finish (mirroring prep may fail on a non-VNet host).
-2. In Azure Portal, open the Key Vault and temporarily enable public networking.
-3. Re-run the prep script from your machine:
+1. Run `azd up` and let postprovision finish (mirroring prep may warn on a non-VNet host).
+2. Re-run the prep script from your machine (it configures PostgreSQL auth, creates the mirror user/role grants, and ensures a seed table exists for Fabric). The script will temporarily enable Key Vault public access for its own secret operations, then disable it again:
 
 ```powershell
 pwsh ./scripts/automationScripts/FabricWorkspace/mirror/prepare_postgresql_for_mirroring.ps1
 ```
 
-4. Copy the `fabric_user` password from Key Vault:
+3. In Azure Portal, open the Key Vault from `keyVaultResourceId` and temporarily enable public networking so you can copy the password:
+   - Azure Portal -> search for **Key Vaults** -> select the Key Vault that matches the name in the resource ID
+   - Go to **Networking** -> set **Public network access** to **Enabled**
+   - Select **Apply** to save
+4. Copy the `fabric_user` password from that Key Vault (you will paste it into the Fabric connection wizard):
 
 ```powershell
 azd env get-value postgreSqlMirrorConnectionSecretNameOut
 az keyvault secret show --vault-name <keyvault-name> --name <secret-name> --query value -o tsv
 ```
 
 5. In Fabric, create a new **Mirrored Azure Database for PostgreSQL** item:
-
-- Server: PostgreSQL FQDN from `azd env get-value postgreSqlServerFqdn`
-- Database: `postgres` (or your custom DB)
-- Username: `fabric_user`
-- Password: the Key Vault secret value
-
-6. Select **Connect** and verify the mirrored database appears.
-7. Re-lock the Key Vault by disabling public networking after the connection succeeds.
+    - Go to [app.fabric.microsoft.com](https://app.fabric.microsoft.com) and open your workspace (for example, `workspace-<envname>`)
+    - Select **New item** -> **Mirror data** -> **Azure Database for PostgreSQL**
+    - Enter:
+       - Server: PostgreSQL FQDN from `azd env get-value postgreSqlServerFqdn`
+       - Database: `postgres` (or your custom DB)
+       - Username: `fabric_user`
+       - Password: the Key Vault secret value
+   - For full portal screenshots and walkthrough, see [Tutorial: Configure Microsoft Fabric mirrored databases from Azure Database for PostgreSQL](https://learn.microsoft.com/fabric/mirroring/azure-database-postgresql-tutorial).
+
+6. Choose **Select data**, pick the `public.fabric_mirror_seed` table, preview the row, then select **Connect**.
+7. On the next screen, name the mirror (or accept the default) and select **Create mirrored database**.
+8. Verify the mirrored database appears.
+9. Re-lock the Key Vault by disabling public networking after the connection succeeds.
 
 If the database or login fails, confirm `postgreSqlAllowAzureServices = true` (or add the `0.0.0.0` firewall rule) and re-run the prep script.