Update post deployment steps and other supporting documentation

Author: Mike Swantek

README.md

@@ -42,6 +42,18 @@ If you only want a small Foundry demo or a basic RAG sample, this repo is heavie
 
 For the first attempt, the lowest-risk path is to keep Fabric and Purview disabled unless you already have their prerequisites in place.
 
+> **Important:** The checked-in values in `infra/main.bicepparam` are an opinionated end-to-end provisioning path for this accelerator, not a neutral baseline for every scenario. They are useful for demonstrating the full stack and the automation flow, but they might enable services, networking, mirroring behavior, or governance hooks that you do not want in your target deployment.
+>
+> Before running `azd up`, review the active settings across:
+> - repo wrapper parameters in `infra/main.bicepparam`
+> - AI Landing Zone feature flags and topology implied by the preprovision deployment
+> - postprovision automation expectations in `azure.yaml`
+> - supporting server-specific settings such as PostgreSQL networking, mirroring mode, and Fabric/Purview inputs
+>
+> Treat the current defaults as the repo's "golden path" for a broad end-to-end demo and validation flow. Adjust them deliberately if you want a smaller, cheaper, or less integrated deployment.
+
+> **Security note (PostgreSQL mirroring):** The mirroring prep script must run from a VNet-connected host when Key Vault and PostgreSQL are private. If you need a non-VNet demo, temporarily open access to both Key Vault and PostgreSQL, run the script, then lock them down. See [docs/post_deployment_steps.md](./docs/post_deployment_steps.md) for the manual steps, including the temporary Key Vault override.
+
 ### Dependency Map
 
 | Area | Required to enable it | If missing |
@@ -98,7 +110,7 @@ Follow the deployment guide to deploy this solution to your own Azure subscripti
 
 1. Run `azd auth login` and confirm the target subscription with `az account show`
 2. Create a new environment and set `AZURE_SUBSCRIPTION_ID` and `AZURE_LOCATION`
-3. Review `infra/main.bicepparam`, especially `principalId`, `aiSearchAdditionalAccessObjectIds`, `fabricCapacityPreset`, `fabricWorkspacePreset`, `fabricCapacityAdmins`, `purviewAccountResourceId`, `networkIsolation`, and `postgreSqlNetworkIsolation`
+3. Review `infra/main.bicepparam`, especially `principalId`, `aiSearchAdditionalAccessObjectIds`, `fabricCapacityPreset`, `fabricWorkspacePreset`, `fabricCapacityAdmins`, `purviewAccountResourceId`, `networkIsolation`, `postgreSqlNetworkIsolation`, and `postgreSqlAllowAzureServices`
 4. Run `azd up`
 5. Follow [docs/post_deployment_steps.md](./docs/post_deployment_steps.md) to verify the deployment
 

azure.yaml

@@ -76,7 +76,7 @@ hooks:
     - run: ./scripts/automationScripts/FabricWorkspace/mirror/prepare_postgresql_for_mirroring.ps1
       interactive: false
       shell: pwsh
-      continueOnError: false
+      continueOnError: true
 
     # Stage 8: Setup Fabric Workspace Private Link (for VNet integration)
     - run: ./scripts/automationScripts/FabricWorkspace/SecureWorkspace/setup_fabric_private_link.ps1

docs/DeploymentGuide.md

@@ -144,6 +144,18 @@ azd env set AZURE_LOCATION eastus2
 
 ### Step 3: Configure Parameters
 
+> **Important:** The values currently checked into `infra/main.bicepparam` represent an opinionated end-to-end path for provisioning this accelerator, including AI Landing Zone infrastructure, Fabric-related automation, PostgreSQL options, and postprovision hooks. They are not guaranteed to be the right settings for every deployment.
+>
+> Before you run `azd up`, verify the feature flags and automation inputs you are inheriting from:
+> - `infra/main.bicepparam`
+> - the AI Landing Zone submodule deployment that runs in preprovision
+> - `azure.yaml` postprovision hooks and their prerequisites
+> - service-specific settings such as Fabric, Purview, network isolation, PostgreSQL mirroring mode, and Azure-services firewall access
+>
+> If your goal is not the full end-to-end accelerator flow, change the flags first instead of treating the current defaults as universally safe.
+
+> **Security note (PostgreSQL mirroring):** The mirroring prep script requires VNet access when Key Vault and PostgreSQL are private. If you need to demo mirroring end-to-end from a non-VNet machine, temporarily open access to both Key Vault and PostgreSQL before running the script and lock them down afterward. See [docs/postgresql_mirroring.md](./postgresql_mirroring.md).
+
 <details>
   <summary><b>Required Parameters</b></summary>
 

docs/PARAMETER_GUIDE.md

@@ -444,6 +444,7 @@ Use these in `infra/main.bicepparam` when deploying via this repo. `postgreSqlNe
 ```bicep-params
 param deployPostgreSql = true
 param postgreSqlNetworkIsolation = networkIsolation
+param postgreSqlAllowAzureServices = false
 param postgreSqlMirrorConnectionMode = 'fabricUser'
 param postgreSqlAuthConfig = {
   activeDirectoryAuth: 'Enabled'
@@ -453,6 +454,13 @@ param postgreSqlAuthConfig = {
 
 When `postgreSqlNetworkIsolation` is `false`, PostgreSQL uses public access and does not create private endpoints or private DNS resources.
 
+`postgreSqlAllowAzureServices` controls whether deployment also creates the PostgreSQL firewall rule that allows Azure services to connect (`0.0.0.0` to `0.0.0.0`). This is the declarative equivalent of the Azure portal **Allow public access from any Azure service within Azure to this server** setting.
+
+Recommended combinations:
+
+- Public/manual Fabric path: `postgreSqlNetworkIsolation = false` and `postgreSqlAllowAzureServices = true`
+- Private/gateway path: `postgreSqlNetworkIsolation = true` and `postgreSqlAllowAzureServices = false`
+
 `postgreSqlAuthConfig` should remain set to both authentication modes enabled if you plan to configure Fabric mirroring after deployment. This ensures the server is created with password authentication available for the `fabric_user` connection instead of relying on a later hook to change the auth mode.
 
 `postgreSqlMirrorConnectionMode` controls which credential the manual Fabric PostgreSQL connection should use after deployment:

docs/post_deployment_steps.md

@@ -53,6 +53,15 @@ Use these short steps to verify the PostgreSQL mirroring follow-up flow. For ful
 
 Mirroring in the current branch is a separate follow-up activity. Fabric connection creation and mirrored database creation are not part of `azd up`.
 
+> **Security step (required for manual mirroring):** The mirroring prep script must run from a VNet-connected host when Key Vault and PostgreSQL are private. If you want to demo mirroring end-to-end from a non-VNet machine, temporarily open access to both Key Vault and PostgreSQL before running the script, then lock them down afterward.
+
+If you must run the mirroring prep from a non-VNet host, set the temporary Key Vault override before you run the script:
+
+```powershell
+$env:POSTGRES_TEMP_ENABLE_KV_PUBLIC_ACCESS = "true"
+pwsh ./scripts/automationScripts/FabricWorkspace/mirror/prepare_postgresql_for_mirroring.ps1
+```
+
 For post-deployment verification, the important distinction is simple:
 
 - If you did not intentionally run the mirroring follow-up, treat mirroring as deferred and do not use it as a deployment success criterion.

docs/postgresql_mirroring.md

@@ -2,8 +2,16 @@
 
 This guide explains how to complete PostgreSQL mirroring in Microsoft Fabric after deployment.
 
+> **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.
+
 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`.
+
+- `postgreSqlNetworkIsolation = false` makes PostgreSQL publicly reachable.
+- `postgreSqlAllowAzureServices = true` creates the PostgreSQL `AllowAzureServices` firewall rule (`0.0.0.0` to `0.0.0.0`), which is the deployment equivalent of the Azure portal **Allow public access from any Azure service within Azure to this server** setting.
+- That combination is the recommended configuration when you want `azd up` to leave PostgreSQL ready for a manual Fabric connection without using a VNet gateway.
+
 If you want full PostgreSQL isolation, the database deployment can still succeed, but end-to-end Fabric mirroring moves to the Fabric VNet gateway path.
 
 If you are not changing the network approach right now, there are only two valid post-deployment outcomes:
@@ -26,13 +34,21 @@ Choose one path up front:
 
 Use this path when the PostgreSQL server has `publicNetworkAccess=Enabled`. In this repo, that corresponds to `postgreSqlNetworkIsolation = false`.
 
+Recommended deployment settings for this path:
+
+```bicep-params
+param postgreSqlNetworkIsolation = false
+param postgreSqlAllowAzureServices = true
+```
+
 1. In Azure Portal, open the PostgreSQL Flexible Server.
 2. Open **Fabric Mirroring** on the server and let the portal prepare the server-side prerequisites.
    - Microsoft documentation explicitly calls out this page as the path that automates the server-side mirroring prerequisites.
    - This overlaps with what `prepare_postgresql_for_mirroring.ps1` is trying to automate.
    - It does **not** create the Fabric connection object or the mirrored database item in the Fabric workspace.
 3. In **Networking**, make sure Fabric can reach the server.
-   - Shortest path: add the `0.0.0.0` firewall rule to allow Azure services.
+   - If `postgreSqlAllowAzureServices = true`, deployment should already have created the Azure-services firewall rule.
+   - If it is not enabled in deployment, add the `0.0.0.0` firewall rule manually.
    - If you only need to read the password secret yourself, temporarily add only your client IP to Key Vault, retrieve the secret, then remove the IP again.
 4. In Fabric, create a new **Mirrored Azure Database for PostgreSQL** item.
 5. Use these deployment values instead of hardcoding names:
@@ -134,6 +150,7 @@ If preflight fails, fix the runner first instead of continuing into SQL prep or
 What is automated today:
 
 - PostgreSQL server deployment during `azd up`.
+- Optional PostgreSQL Azure-services firewall rule creation during `azd up` when `postgreSqlAllowAzureServices = true` and PostgreSQL public access is enabled.
 - PostgreSQL mirroring prep during `azd up` postprovision (server parameters, auth mode, mirroring role/grants, and seed table).
 - Manual or follow-up Fabric connection creation for PostgreSQL mirroring.
 - Manual or follow-up mirror creation after the Fabric connection is resolved.
@@ -149,6 +166,7 @@ The Fabric mirroring API requires a Fabric "connection" object that stores the P
 - PostgreSQL authentication mode is **PostgreSQL and Microsoft Entra authentication** (password auth enabled).
 - You have access to the Key Vault that stores the PostgreSQL secrets.
 - Decide which connection mode you are using: `fabricUser` (default) or `admin` via `postgreSqlMirrorConnectionMode`.
+- If you are using the public/manual path, prefer `postgreSqlAllowAzureServices = true` so Fabric can reach PostgreSQL without a VNet gateway.
 
 ## Step 1: Confirm PostgreSQL Details
 
@@ -172,6 +190,15 @@ pwsh ./scripts/automationScripts/FabricWorkspace/Mirror/prepare_postgresql_for_m
 
 Re-run it manually only if you need to repair or reapply the PostgreSQL mirroring readiness settings.
 
+> **Security step (manual demo path):** If you are not running from a VNet-connected host, temporarily enable Key Vault access and PostgreSQL firewall access for your client before running the script. Restore the locked-down settings immediately after.
+
+If you need the script to temporarily enable Key Vault public access while it runs, set:
+
+```powershell
+$env:POSTGRES_TEMP_ENABLE_KV_PUBLIC_ACCESS = "true"
+pwsh ./scripts/automationScripts/FabricWorkspace/mirror/prepare_postgresql_for_mirroring.ps1
+```
+
 ### Manual rerun
 
 Run:

img/Architecture/Deploy-AI-App-in-Prod-Architecture_final.png

@@ -218,6 +218,9 @@ param postgreSqlServerName string = 'pg${resourceToken}'
 @description('Enable network isolation for PostgreSQL (private DNS + private endpoint).')
 param postgreSqlNetworkIsolation bool = networkIsolation
 
+@description('Allow connections from Azure services to the PostgreSQL server when public access is enabled. This creates the 0.0.0.0 firewall rule equivalent to the portal Allow Azure services setting.')
+param postgreSqlAllowAzureServices bool = false
+
 @description('Create and link the PostgreSQL private DNS zone to the VNet.')
 param deployPostgreSqlPrivateDnsLink bool = true
 
@@ -406,6 +409,22 @@ module postgreSqlFlexibleServer 'br/public:avm/res/db-for-postgre-sql/flexible-s
   }
 }
 
+resource postgreSqlFlexibleServerResource 'Microsoft.DBforPostgreSQL/flexibleServers@2025-06-01-preview' existing = if (deployPostgreSql) {
+  name: postgreSqlServerName
+}
+
+resource postgreSqlAllowAzureServicesFirewallRule 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2025-01-01-preview' = if (deployPostgreSql && !postgreSqlNetworkIsolation && postgreSqlAllowAzureServices) {
+  parent: postgreSqlFlexibleServerResource
+  name: 'AllowAzureServices'
+  properties: {
+    startIpAddress: '0.0.0.0'
+    endIpAddress: '0.0.0.0'
+  }
+  dependsOn: [
+    postgreSqlFlexibleServer
+  ]
+}
+
 resource postgreSqlAdminSecret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = if (deployPostgreSql && enablePostgreSqlKeyVaultSecret) {
   name: postgreSqlAdminSecretName
   parent: keyVault

img/Architecture/Depoly-AI-App-in-Prod-Architecture-final.png

@@ -32,12 +32,15 @@ param aiSearchAdditionalAccessObjectIds = ['']
 
 param deploymentTags = {}
 param appConfigLabel = 'ai-lz'
+// Create the provisioning of the AI landing zone with network isolation (vnet,private end points, etc)
 param networkIsolation = true
 
 // Coordinate PostgreSQL networking with the overall isolation flag by default.
-param postgreSqlNetworkIsolation = networkIsolation
+param postgreSqlNetworkIsolation = false
+// Allow Fabric and other Azure services to reach PostgreSQL when public access is enabled.
+param postgreSqlAllowAzureServices = true
 // Skip this if a PostgreSQL private DNS zone is already linked to the VNet.
-param deployPostgreSqlPrivateDnsLink = true
+param deployPostgreSqlPrivateDnsLink = false
 // Optional: use an existing VNet link name to avoid conflicts.
 param postgreSqlPrivateDnsLinkNameOverride = ''