Extending AzOps Native Handling with Azure Deployment Stacks

[Jefajers]

Overview/Summary

This PR adds capabilities in AzOps to handle Azure Deployment Stack natively and fixes #919.

This means that AzOps will attempt to perform New-AzResourceGroupDeploymentStack, New-AzSubscriptionDeploymentStack or New-AzManagementGroupDeploymentStack for the custom template and parameter file in scope of the new AzOps deployment stack configuration settings file.

Deletion is supported for the AzOps created DeploymentStack.

The setting files evaluated can have the following patterns: .deploymentStacks.json, <templateName>.deploymentStacks.json or <templateName>.<templateMultiParameterName>.deploymentStacks.json.
If multiple stacks are found they will be processed in the order of the most specific <templateName>.<templateMultiParameterName>.deploymentStacks.json up to root level .deploymentStacks.json at the template scope. The first one matched and not excluded will be used.

Example of folder and file structure where .deploymentStack.json is used for most custom templates but not necessarily all:

MG root/
├── Intermediate Root MG/
│   ├── .deploymentStacks.json
│   ├── metropolis.bicep
│   ├── LZ/
│   │   ├── Sub 1/
│   │   │   ├── .deploymentStacks.json
│   │   │   ├── e2e-aks.bicep
│   │   │   ├── ai-foundry.deploymentStacks.json
│   │   │   ├── ai-foundry.bicep
│   │   │   ├── RG 1/
│   │   │   └── RG 2/
│   │   │       ├── .deploymentStacks.json
│   │   │       └── workload.bicep
│   │   ├── Sub 2/
│   │   │   ├── stuff.bicep
│   │   │   ├── RG 1/
│   │   │   └── RG 2/
│   │   │       ├── .workload.bicep
│   │   │       ├── .workload.x1.deploymentStacks.json
│   │   │       ├── .workload.x2.bicepparam
│   │   │       ├── .workload.x2.deploymentStacks.json
│   │   │       └── .workload.x2.bicepparam
│   ├── Platform/
│   │   ├── Sub 3/
│   │   └── Sub 4/

Example of the deploymentStacks.json file structure:

{
    "actionOnUnmanage": "deleteResources",
    "bypassStackOutOfSyncError": false,
    "denySettingsMode": "DenyDelete",
    "excludedAzOpsFiles": [
        "dontLookAtMe.bicep"
    ]
}

This PR fixes/adds/changes/removes

1. Changes Invoke-AzOpsPush.ps1
2. Adds Get-AzOpsDeploymentStackSetting.ps1
3. Changes Get-AzOpsResource.ps1
4. Changes New-AzOpsDeployment.ps1
5. Changes Remove-AzOpsDeployment.ps1
6. Changes Set-AzOpsRemoveOrder.ps1
7. Changes Set-AzOpsWhatIfOutput.ps1
8. Changes Strings.psd1
9. Adds DeploymentStacks.md
10. Changes _Sidebar.md
11. Changes azuredeploy.jsonc
12. Adds deploystacksatmg.bicep
13. Adds deploystacksatmg.x1.bicepparam
14. Adds deploystacksatmg.x1.deploymentStacks.json
15. Adds deploystacksatrg.bicep
16. Adds deploystacksatrg.deploymentStacks.json
17. Adds deploystacksatsub.bicep
18. Adds deploystacksatsub.bicepparam
19. Adds deploystacksatsub.deploymentStacks.json
20. Adds deploystacksatsubrename.deploymentStacks.json

Breaking Changes

1. N/A

Testing Evidence

PR contains three added automated test cases for DeploymentStacks.

As part of this Pull Request I have

• Checked for duplicate Pull Requests
• Associated it with relevant issues, for tracking and closure.
• Ensured my code/branch is up-to-date with the latest changes in the main branch
• Performed testing and provided evidence.
• Updated relevant and associated documentation.

[Copilot]

Pull Request Overview

This PR extends AzOps native handling to support Azure Deployment Stack by adding new deployment stack settings functions, updating existing deployment, deletion, and push functions, and enhancing localized strings for deployment stack logging.

• Added new command Get-AzOpsDeploymentStackSetting with helper functions to resolve deployment stack configuration.
• Updated deployment and removal functions (e.g. New-AzOpsDeployment, Remove-AzOpsDeployment, Invoke-AzOpsPush) to support the new deployment stack process.
• Minor modifications across several internal functions (e.g. Get-AzOpsResource, role assignment functions) to enforce consistent parameter typing and incorporate deployment stack parameters.

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/localized/en-us/Strings.psd1	Added new localized strings for handling deployment stack logs and errors.
src/internal/functions/Set-AzOpsWhatIfOutput.ps1	Updated function signature and result headline generation to include an optional DeploymentStackTemplateFilePath.
src/internal/functions/Set-AzOpsRemoveOrder.ps1	Adjusted deletion priority by incorporating deploymentStacks in the priority array when DeploymentStackSettings exists.
src/internal/functions/Remove-AzOpsDeployment.ps1	Included additional parameters and conditions for deployment stack deletion scenarios.
src/internal/functions/New-AzOpsDeployment.ps1	Updated deployment logic to choose appropriate deploymentStack cmdlets based on new settings.
src/internal/functions/Invoke-AzOpsRestMethod.ps1, Get-AzOpsRole*.ps1, Get-AzOpsPim.ps1	Standardized parameter type casing.
src/internal/functions/Get-AzOpsResource.ps1	Added DeploymentStackName parameter and logic to retrieve deployment stack resources.
src/internal/functions/Get-AzOpsDeploymentStackSetting.ps1	New, complex function with helper routines for resolving deployment stack configuration and exclusions.
src/functions/Invoke-AzOpsPush.ps1	Enhanced processing to handle deployment stack templates, including temporary file creation for parallel processing and deletion list path normalization.