chore: merge dev into main

[Harmanpreet-Microsoft]

Purpose

This pull request introduces several improvements to high availability, redundancy, and documentation for Azure resource deployment. The main changes include enhanced support for Cosmos DB failover locations, improved handling of Log Analytics workspace deletion when replication is enabled, and updates to infrastructure parameters and documentation for clarity and operational reliability.

High Availability & Redundancy Improvements:

• Added a secondaryCosmosLocation parameter to support specifying a secondary failover region for Cosmos DB, improving high availability and disaster recovery. The default for cosmosLocation is now the resource group location, and the secondary defaults to canadacentral. The Cosmos DB configuration now uses these parameters directly for primary and secondary locations. (infra/main.bicep, infra/main.parameters.json, infra/main.waf.parameters.json, [1] [2] [3] [4]
• Removed the hardcoded region pairing logic for Cosmos DB high availability, relying instead on explicit parameters for greater flexibility and transparency. (infra/main.bicep, infra/main.bicepL234-L257)

Resource Deletion & Replication Handling:

• Added a new guide, LogAnalyticsReplicationDisable.md, with step-by-step instructions to disable replication on Log Analytics workspaces before deletion, preventing resource group deletion failures. The deployment guide now references this process for users deploying with redundancy enabled. (docs/LogAnalyticsReplicationDisable.md, docs/DeploymentGuide.md, [1] [2]

Infrastructure Configuration Updates:

• Changed the Key Vault SKU to premium when scalability is enabled, supporting advanced features in scalable environments. (infra/main.bicep, infra/main.bicepL560-R546)
• Separated the SQL Server private endpoint configuration into its own module for improved clarity and maintainability. (infra/main.bicep, [1] [2]
• Adjusted the web server farm and search service SKUs and redundancy settings to align with the current deployment strategy and Azure best practices. (infra/main.bicep, [1] [2]

Documentation Updates:

• Updated parameter documentation to clarify the purpose and default values for Cosmos DB locations, including links to Azure documentation for supported regions. (docs/CustomizingAzdParameters.md, docs/CustomizingAzdParameters.mdL13-R14)

These changes collectively improve the reliability, clarity, and operational safety of Azure deployments using this infrastructure codebase.

• ...

Does this introduce a breaking change?

• Yes
• No

Golden Path Validation

• I have tested the primary workflows (the "golden path") to ensure they function correctly without errors.

Deployment Validation

• I have validated the deployment process successfully and all services are running as expected with this change.

What to Check

Verify that the following are valid

• ...

Other Information

[Copilot]

Pull request overview

This pull request merges development branch into main with several infrastructure improvements focused on high availability, redundancy, and operational documentation for Azure resource deployment.

Key Changes:

• Introduced explicit Cosmos DB location parameters (cosmosLocation and secondaryCosmosLocation) replacing hardcoded region pairing logic for better flexibility
• Separated SQL Server private endpoint configuration into a dedicated module for improved maintainability
• Modified resource SKU configurations: Key Vault uses premium SKU when scalability is enabled, while App Service Plan is now fixed to B3 tier, and Search Service conditionally uses standard vs basic

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
infra/main.bicep	Core infrastructure changes including Cosmos DB location parameters, Key Vault SKU conditional logic, SQL Server private endpoint separation, and App Service/Search Service SKU adjustments
infra/main.parameters.json	Added secondaryCosmosLocation parameter mapping for standard deployments
infra/main.waf.parameters.json	Added secondaryCosmosLocation parameter mapping for WAF-aligned deployments
infra/main.json	Compiled ARM template with updated Bicep version (0.39.26.7824) and API version updates (2025-04-01)
docs/LogAnalyticsReplicationDisable.md	New operational guide for disabling Log Analytics workspace replication before deletion
docs/DeploymentGuide.md	Added reference to Log Analytics replication handling for users deploying with redundancy enabled
docs/CustomizingAzdParameters.md	Updated parameter documentation for new Cosmos DB location parameters with links to supported regions
docs/TroubleShootingSteps.md	Major restructure from collapsible sections to categorized tables with quick reference summary and new error scenarios

Comments suppressed due to low confidence (1)

infra/main.bicep:846

• When redundancy is disabled (enableRedundancy=false), the Cosmos DB failover location uses solutionLocation instead of cosmosLocation. This creates an inconsistency where:

• The primary Cosmos DB location is set to cosmosLocation (line 773)
• But the failover location (when redundancy is disabled) uses solutionLocation (line 842)

This could cause issues if a user sets a custom cosmosLocation different from the resource group location. In non-redundancy mode, the Cosmos DB would be deployed to the custom cosmosLocation, but the failover configuration would reference solutionLocation (which defaults to the resource group location if the location parameter is not set).

Consider using cosmosLocation for consistency in line 842 instead of solutionLocation.

      : [
          {
            locationName: solutionLocation
            failoverPriority: 0
            isZoneRedundant: enableRedundancy
          }
        ]

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The troubleshooting guide has been significantly restructured and improved. However, there are a few items that could be enhanced:

1. The "ServiceDeleting" error (line 142) is newly documented but doesn't appear in the "Most Frequently Encountered Errors" summary table at the top. Consider adding it if it's a common issue.

2. The "Conflict - No available instances to satisfy this request" error (line 64) is a valuable addition for App Service capacity issues. Good documentation of retry strategies and alternative approaches.

The overall reorganization into categorized tables significantly improves readability and usability compared to the previous collapsible format.

[Copilot]

The guide provides clear instructions for disabling Log Analytics replication before deletion. However, there's a potential improvement:

The command on line 9 uses a hardcoded resource ID template. Consider adding a note that users can find their actual resource ID from the Azure Portal or by running:

az monitor log-analytics workspace show --workspace-name {logAnalyticsName} --resource-group {resourceGroupName} --query id -o tsv

This would help users who might struggle with manually constructing the resource ID.

[Copilot]

The documentation correctly describes the new AZURE_ENV_COSMOS_SECONDARY_LOCATION parameter, but there's a minor inconsistency:

Line 13 states the primary Cosmos location defaults to "Same as resource group location", but the actual Bicep code (infra/main.bicep:13) uses resourceGroup().location which is the same thing. However, the description could be clearer by stating it explicitly matches the AZURE_LOCATION value when not specified, since users set AZURE_LOCATION to determine the resource group location.

Also consider clarifying that both locations should support zone redundancy when enableRedundancy=true, as mentioned in the link provided.

Suggested change

	| `AZURE_ENV_COSMOS_LOCATION` | string | `Same as resource group location` | Primary location for the Cosmos DB instance. When enabling redundancy, verify the region supports zone redundancy. [Check supported regions](https://learn.microsoft.com/en-us/azure/reliability/regions-list). |
	| `AZURE_ENV_COSMOS_SECONDARY_LOCATION` | string | `canadacentral` | Secondary failover location for Cosmos DB when enableRedundancy is true. [Check supported regions](https://learn.microsoft.com/en-us/azure/reliability/regions-list). |
	| `AZURE_ENV_COSMOS_LOCATION` | string | `AZURE_LOCATION` (resource group location) | Primary location for the Cosmos DB instance. Defaults to the value of `AZURE_LOCATION` (the resource group location). **If `enableRedundancy=true`, this region must support zone redundancy.** [Check supported regions](https://learn.microsoft.com/en-us/azure/reliability/regions-list). |
	| `AZURE_ENV_COSMOS_SECONDARY_LOCATION` | string | `canadacentral` | Secondary failover location for Cosmos DB when `enableRedundancy` is true. **This region must also support zone redundancy if `enableRedundancy=true`.** [Check supported regions](https://learn.microsoft.com/en-us/azure/reliability/regions-list). |

[Copilot]

The Key Vault SKU is now set to 'premium' when enableScalability is true. However, the PR description states this is to "support advanced features in scalable environments" but doesn't specify which features require the premium SKU.

The main differences between standard and premium Key Vault SKUs are:

• Premium: HSM-backed keys for additional security
• Standard: Software-backed keys

Consider documenting why premium SKU is necessary for scalability scenarios. If the primary reason is HSM-backed keys for enhanced security in production/scalable environments, this should be clarified in comments or documentation. If this is not required for the solution's functionality, it may unnecessarily increase costs for users who enable scalability.

Suggested change

	tags: tags
	tags: tags
	// Use 'premium' SKU when scalability is enabled to support advanced features such as HSM-backed keys (for enhanced security and FIPS 140-2 compliance) that may be required in scalable/production environments.
	// If your scenario does not require HSM-backed keys or other premium features, consider using the 'standard' SKU to reduce costs.

[Copilot]

The web server farm configuration has been changed to always use SKU 'B3' with skuCapacity of 1 and zoneRedundant set to false, regardless of the enableScalability or enableRedundancy parameters. This is a significant behavioral change from the previous configuration which used 'P1v3' SKU when either scalability or redundancy was enabled.

While the inline comment on line 1067 explains the zone redundancy change (requires minimum 2 instances), the removal of the dynamic SKU selection based on enableScalability or enableRedundancy is not explained in the PR description or comments.

This change could impact:

1. Performance in scalable deployments (B3 is Basic tier vs P1v3 Premium tier)
2. Available features (Premium tiers offer more features than Basic)
3. SLA guarantees (Basic tier has lower SLA than Premium)

Consider documenting this change more explicitly in the PR description or adding a comment explaining why Basic tier is now used for all scenarios.

[Copilot]

The note added about disabling Log Analytics replication is helpful and necessary. However, there's a minor grammatical issue in the sentence structure.

The phrase "else resource group delete will fail" should be "otherwise resource group deletion will fail" for better clarity and grammatical correctness.

Suggested change

> **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down`, else resource group delete will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`.

> **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down`, otherwise resource group deletion will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`.