Merge pull request #976 from Azure/feature/apy/ALZSyncEnhancements

Feature/apy/alz sync enhancements

Author: apybar

Docs/integrating-with-alz-library.md

@@ -1,45 +1,15 @@
-# Integrating EPAC with the Azure Landing Zones Library
+# Integrating EPAC with the Azure Landing Zones Library (New)
 
-The [Azure Landing Zones Library](https://azure.github.io/Azure-Landing-Zones-Library/) contains the source of all policy definitions, set definition and assignments for not only the Azure Landing Zone deployment but associated projects such as the Azure Monitor Baseline Alerts and Sovereign Landing Zone accelerator. Previous integration with EPAC involved manually updating the assignments provided and was complex and difficult to maintain.
-
-This new method of maintaining and deploying the policies provides the following benefits: -
-
-- One process for ALZ / AMBA / SLZ instead of separate processes.
-- Pin to a version of the library by specifying a tag during sync - or refer to an already cloned copy.
-- Modify the cloned repository to add new assignments, management group archetypes, parameters.
-- A single file provides the default values for the policy assignments making it easier to maintain. Add new parameter values as required.
-
-## Why and when should you use EPAC to manage ALZ deployed policies
-
-EPAC can be used to manage Azure Policy deployed using ALZ Bicep or Terraform using the scenarios below. Some reasons you may want to switch to EPAC policy management include:
-
-- You have existing unmanaged policies in a brownfield environment that you want to deploy in the new ALZ environment. [Export the existing policies](start-extracting-policy-resources.md) and manage them with EPAC alongside the ALZ policy objects.
-- You have ALZ deployed in a non standard way e.g. multiple management group structures for testing, non-conventional management group structure. The default assignment structure provided by other ALZ deployment methods may not fit your strategy.
-- A team that is not responsible for infrastructure deployment e.g. a security team may want to deploy and manage policies.
-- You require features from policy not available in the ALZ deployments e.g. policy exemptions, documentation, assignment customization.
-- Non-compliance reporting and remediation task management.
-
-## Recommendation for existing deployment using EPAC
-
-If you already use the `Sync-ALZPolicies` command you should move to the new process as the assignments are no longer being maintained. Follow the instructions below to create a policy structure file and then perform a sync. The main difference existing users will notice is there is that all the assignments have been split out into single files instead of the existing structure. For ease of use these are now grouped into folders based on landing zone archetypes.
-
-## Scenarios
-
-1. Existing Azure Landing Zones deployment and EPAC is to be used as the policy engine moving forward.
-2. Using EPAC to deploy and manage the Azure Landing Zone policies.
-
-In both cases it is now recommended that if you have the default ALZ policies deployed you should use the new method to provide a consistent sync process.
-
-## Using the new Azure Landing Zone Library sync process
-
-### Pre-requisites
+## Pre-requisites
 
 To use the ALZ policies in an environment successfully there are some Azure Resources that need to be created. This is normally completed by using one of the ALZ accelerators to deploy the environment however if you have written your own code or modified the default deployment ensure you have the following resources in place to support the ALZ policies.
 
 - Log Analytics workspace
 - DCR rules to support monitoring - [data collection rule templates](https://github.com/Azure/Enterprise-Scale/tree/main/eslzArm/resourceGroupTemplates)
 - User Assigned Managed Identity to support Azure Monitor Agent - [sample template](https://github.com/Azure/Enterprise-Scale/blob/main/eslzArm/resourceGroupTemplates/userAssignedIdentity.json)
 
+## Using the new Azure Landing Zone Library sync process
+
 ### Create a policy default structure file
 
 This file contains information that drives the sync process. The file includes management group IDs, default enforcement mode, and parameter values. **It must be generated at least once before executing the sync process.**
@@ -48,8 +18,8 @@ This file contains information that drives the sync process. The file includes m
 2. Use to code to clone the library repository and create the default file. There are examples below on how to run this commnand - you will only need to run one of these depending on your requirements.
 
 ```ps1
-# Create a default file for ALZ policies using the latest version of the ALZ Library 
-New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type ALZ
+# Create a Pac Environment default file for ALZ policies using the latest version of the ALZ Library 
+New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type ALZ -PacEnvironmentSelector "epac-dev"
 
 # Create a default file for ALZ policies specifiying a tagged version of the ALZ Library 
 New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type ALZ -Tag "platform/alz/2025.02.0"
@@ -95,9 +65,11 @@ Modify the default enforcement mode
 "enforcementMode": "Default" // Can be Default or DoNotEnforce
 ```
 
+### Sync with ALZ Policy Repo
+
 The next command will generate policy assignments based on the values in this file so ensure they are correct for your environment.
 
-4. Use to code to sync the policy files and update scopes and parameters based on the information in the previously created file. There are examples below on how to run this command - you will only need to run one of these depending on your requirements. The files will be copied into their own folder to separate them from any definitions already in the repository.
+1. Use to code to sync the policy files and update scopes and parameters based on the information in the previously created file. There are examples below on how to run this command - you will only need to run one of these depending on your requirements. The files will be copied into their own folder to separate them from any definitions already in the repository.
 
 ```ps1
 # Sync the ALZ policies and assign to the "epac-dev" PAC environment.
@@ -115,11 +87,64 @@ Sync-ALZPolicyFromLibrary -DefinitionsRootFolder .\Definitions -Type AMBA -PacEn
 
 Carefully review the generated policy assigments and ensure all parameter and scope information is correct.
 
-5. When complete run `Build-DeploymentPlans` to ensure the correct changes are made. During the first sync for either a new or existing environment there will be many changes due to updating of the existing policies.
+2. When complete run `Build-DeploymentPlans` to ensure the correct changes are made. During the first sync for either a new or existing environment there will be many changes due to updating of the existing policies.
+
+## Example
+
+### ALZ
+
+```ps1
+# Create a Pac Environment default file for ALZ policies using the latest version of the ALZ Library 
+New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type ALZ -PacEnvironmentSelector "epac-dev"
+
+# Sync the ALZ policies and assign to the "epac-dev" PAC environment.
+Sync-ALZPolicyFromLibrary -DefinitionsRootFolder .\Definitions -Type ALZ -PacEnvironmentSelector "epac-dev"
+```
+
+### AMBA (ALZ)
+
+For users interested in deploying the [Azure Monitor Baseline Alerts](https://azure.github.io/azure-monitor-baseline-alerts/welcome/) project with EPAC - these policies have been extracted and converted to the EPAC format and are available at the [amba-export](https://github.com/anwather/amba-export) repository.
+
+```ps1
+# Create a Pac Environment default file for ALZ policies using the latest version of the ALZ Library 
+New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type AMBA -PacEnvironmentSelector "epac-dev"
+
+# Sync the ALZ policies and assign to the "epac-dev" PAC environment.
+Sync-ALZPolicyFromLibrary -DefinitionsRootFolder .\Definitions -Type AMBA -PacEnvironmentSelector "epac-dev"
+```
+
+### SLZ
+
+For users interested in deploying the [Sovereignty Policy Baseline](https://github.com/Azure/sovereign-landing-zone/blob/main/docs/scenarios/Sovereignty-Baseline-Policy-Initiatives.md) project with EPAC - these policies have been extracted and converted to the EPAC format and are available at the [spb-export](https://github.com/anwather/spb-export) repository.
+
+```ps1
+# Create a Pac Environment default file for ALZ policies using the latest version of the ALZ Library 
+New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type AMBA -PacEnvironmentSelector "epac-dev"
+
+# Sync the ALZ policies and assign to the "epac-dev" PAC environment.
+Sync-ALZPolicyFromLibrary -DefinitionsRootFolder .\Definitions -Type AMBA -PacEnvironmentSelector "epac-dev"
+```
 
 ## Advanced Scenarios
 
 Using the format of the Azure Landing Zones repository it is possible to extend the management groups defined and provide your own archetypes. You must maintain a local copy of the library for this purpose. Details will be provided at a later stage on how to customize this for different scenarios including:
 
 - Modifying the management group structure (add new groups and archetypes)
 - Add/Remove policies from an archetype
+
+### Maintaining multiple ALZ/AMBA environment with different parameter / management group values
+
+If you need to have separate parameter values or different management group names for different PAC environments you can follow steps below.
+
+1. Generate a policy structure file using `New-ALZPolicyDefaultStructure` and specify the `-PacEnvironmentSelector` parameter.
+
+This generates a standard file structure however the file's name will now include the Pac Selector given. This default structure will now be used everytime you run the "Sync-ALZPolicyFromLibrary" command with the matching PacEnvironmentSelector.
+
+For example: -
+
+```
+alz.policy_default_structure.<PAC SELECTOR>.jsonc
+```
+
+2. When syncing policies run the `Sync-ALZPolicyFromLibrary` once for each PAC Environment. A folder specific for that Pac Selector will now be placed within the ALZ Type.
+

Docs/integrating-with-alz-monitor.md

@@ -0,0 +1,28 @@
+# Integrating EPAC with Azure Landing Zones
+
+## What are Azure Landing Zones (ALZ)?
+
+Azure Landing Zones (ALZ) are a set of best practices, templates, and resources provided by Microsoft to help organizations set up a secure, scalable, and compliant foundation in Azure. They are part of the broader Cloud Adoption Framework (CAF), which is Microsoft's guidance for cloud adoption across strategy, planning, readiness, governance, and management.
+
+Microsoft publishes and maintains a [list of Policies, Policy Sets and Assignments](https://aka.ms/alz/policies) which are deployed as part of the Cloud Adoption Framework Azure Landing Zones deployment. The central repository that contains these policies acts as the source of truth for ALZ deployments via the portal, Bicep and Terraform.
+
+To enable customers to use the Enterprise Policy as Code solution and combine Microsoft's policy recommendations there is a script which will pull the Policies, Policy Sets and Policy Assignments from the central repository and allow you to deploy them using this solution.
+
+As the policies and assignments change in main repository the base files in this solution can be updated to match.
+
+## Why and when should you use EPAC to manage ALZ deployed policies
+
+EPAC can be used to manage Azure Policy deployed using ALZ Bicep or Terraform using the scenarios below. Some reasons you may want to switch to EPAC policy management include:
+
+- You have existing unmanaged policies in a brownfield environment that you want to deploy in the new ALZ environment. [Export the existing policies](start-extracting-policy-resources.md) and manage them with EPAC alongside the ALZ policy objects.
+- You have ALZ deployed in a non standard way e.g. multiple management group structures for testing, non-conventional management group structure. The default assignment structure provided by other ALZ deployment methods may not fit your strategy.
+- A team that is not responsible for infrastructure deployment e.g. a security team may want to deploy and manage policies.
+- You require features from policy not available in the ALZ deployments e.g. policy exemptions, documentation, assignment customization.
+- Non-compliance reporting and remediation task management.
+
+## Scenarios
+
+1. Existing Azure Landing Zones deployment and EPAC is to be used as the policy engine moving forward.
+2. Using EPAC to deploy and manage the Azure Landing Zone policies.
+
+In both cases it is now recommended that if you have the default ALZ policies deployed you should use the [new method](integrating-with-alz-library.md) to provide a consistent sync process.

Docs/integrating-with-alz-overview.md

@@ -1,31 +1,4 @@
-# Integrating EPAC with Azure Landing Zones
-
-## Rationale
-
-Microsoft publishes and maintains a [list of Policies, Policy Sets and Assignments](https://aka.ms/alz/policies) which are deployed as part of the Cloud Adoption Framework Azure Landing Zones deployment. The central repository that contains these policies acts as the source of truth for ALZ deployments via the portal, Bicep and Terraform. A current list of policies which are deployed using these solutions is found at this link.
-
-To enable customers to use the Enterprise Policy as Code solution and combine Microsoft's policy recommendations there is a script which will pull the Policies, Policy Sets and Policy Assignments from the central repository and allow you to deploy them using this solution.
-
-As the policies and assignments change in main repository the base files in this solution can be updated to match.
-
-## Why and when should you use EPAC to manage ALZ deployed policies
-
-EPAC can be used to manage Azure Policy deployed using ALZ Bicep or Terraform using the scenarios below. Some reasons you may want to switch to EPAC policy management include:
-
-- You have existing unmanaged policies in a brownfield environment that you want to deploy in the new ALZ environment. [Export the existing policies](start-extracting-policy-resources.md) and manage them with EPAC alongside the ALZ policy objects.
-- You have ALZ deployed in a non standard way e.g. multiple management group structures for testing, non-conventional management group structure. The default assignment structure provided by other ALZ deployment methods may not fit your strategy.
-- A team that is not responsible for infrastructure deployment e.g. a security team may want to deploy and manage policies.
-- You require features from policy not available in the ALZ deployments e.g. policy exemptions, documentation, assignment customization.
-- Non-compliance reporting and remediation task management.
-
-Instructions are provided below for integrating with Bicep and Terraform deployments.
-
-## Scenarios
-
-There are two scenarios for integrating EPAC with ALZ.
-
-1. Existing Azure Landing Zone deployment and EPAC is to be used as the policy engine moving forward.
-2. Using EPAC to deploy and manage the Azure Landing Zone policies.
+# Integrating EPAC with the Azure Landing Zones Library (Legacy)
 
 ## Scenario 1 - Existing Deployment
 

Docs/integrating-with-alz.md

@@ -1,5 +1,5 @@
+
 Param(
-   
     [Parameter(Mandatory = $true)]
     [string] $DefinitionsRootFolder,
 
@@ -8,7 +8,9 @@ Param(
 
     [string]$LibraryPath,
 
-    [string]$Tag
+    [string]$Tag,
+
+    [string] $PacEnvironmentSelector
 )
 
 if ($DefinitionsRootFolder -eq "") {
@@ -35,7 +37,6 @@ if ($LibraryPath -eq "") {
     }
 }
 
-
 $jsonOutput = @{
     managementGroupNameMappings = @{}
     defaultParameterValues      = @{}
@@ -44,8 +45,7 @@ $jsonOutput = @{
 
 # Get Management Group Names
 
-$archetypeDefinitionFile = Get-Content -Path "$LibraryPath\platform\$($Type.ToLower())\architecture_definitions\$($Type.ToLower()).alz_architecture_definition.json" | `
-    ConvertFrom-Json
+$archetypeDefinitionFile = Get-Content -Path "$LibraryPath\platform\$($Type.ToLower())\architecture_definitions\$($Type.ToLower()).alz_architecture_definition.json" | ConvertFrom-Json
 
 foreach ($mg in $archetypeDefinitionFile.management_groups) {
     $obj = @{
@@ -66,7 +66,7 @@ foreach ($parameter in $policyDefaultFile.defaults) {
     $assignment = $parameter.policy_assignments[0]
 
     $assingmentFileName = ("$($assignment.policy_assignment_name).alz_policy_assignment.json")
-    if ($type -eq "AMBA") {
+    if ($Type -eq "AMBA") {
         $assingmentFileName = $assingmentFileName -replace ("-", "_")
     }
     $file = Get-ChildItem -Recurse -Path ".\temp" -Filter "$assingmentFileName" -File | Select-Object -First 1
@@ -85,12 +85,20 @@ foreach ($parameter in $policyDefaultFile.defaults) {
     $jsonOutput.defaultParameterValues.Add($parameter.default_name, $obj)
 }
 
-Out-File "$DefinitionsRootFolder\$($Type.ToLower()).policy_default_structure.jsonc" -InputObject ($jsonOutput | ConvertTo-Json -Depth 10) -Encoding utf8 -Force
+# Ensure the output directory exists
+$outputDirectory = "$DefinitionsRootFolder\policyStructures"
+if (-not (Test-Path -Path $outputDirectory)) {
+    New-Item -ItemType Directory -Path $outputDirectory
+}
 
+if ($PacEnvironmentSelector) {
+    Out-File "$outputDirectory\$($Type.ToLower()).policy_default_structure.$PacEnvironmentSelector.jsonc" -InputObject ($jsonOutput | ConvertTo-Json -Depth 10) -Encoding utf8 -Force
+}
+else {
+    Out-File "$outputDirectory\$($Type.ToLower()).policy_default_structure.jsonc" -InputObject ($jsonOutput | ConvertTo-Json -Depth 10) -Encoding utf8 -Force
+}
 
 $tempPath = Join-Path -Path (Get-Location) -ChildPath "temp"
 if ($LibraryPath -eq $tempPath) {
     Remove-Item $LibraryPath -Recurse -Force -ErrorAction SilentlyContinue
 }
-
-