Add custom management groups to ALZ sync process (#1018)

Co-authored-by: Anthony Watherston <[email protected]>

Author: anwather

Docs/Images/new-management-groups.png

@@ -211,3 +211,101 @@ Example to generate assignments with guardrails assignments included.
 # Sync the ALZ policies and assign to the "epac-dev" PAC environment.
 Sync-ALZPolicyFromLibrary -DefinitionsRootFolder .\Definitions -Type ALZ -PacEnvironmentSelector "epac-dev" -CreateGuardrailAssignments
 ```
+
+### Using a custom library for custom management group structures
+
+Azure environments may not always be aligned with the default management group structure suggested by Azure Landing Zones. In this case it is required to maintain your own version of the Azure Landing Zone library repository and make changes in there to the default structure. This will increase the overall complexity in maintaining synchronisation as you will have to manage any updates to the forked repository.
+
+In the example below it follows a typical customer customization where instead of having a corp/online management group structure it has been elected to use a non-production/production management group structure.
+
+The updated management group structure would follow similar to below:-
+
+```
+--Azure Landing Zones MG
+ |_Non-Production MG
+ |_ Production MG
+```
+
+1. Create a fork of the [Azure Landing Zone Library](https://github.com/Azure/Azure-Landing-Zones-Library) and clone it locally. When later running the `New-ALZPolicyDefaultStructure` and `Sync-ALZPolicyFromLibrary` commands you will need to ensure the `-LibraryPath` parameter points to this cloned repo.
+2. For ALZ there are two files which need to be updated - firstly we need to add the new management group archetypes into the `\platform\alz\architecture_definitions\alz.alz_architecture_definition.json` file. In this example I will remove the `corp` and `online` entries from this file and replace them with a non-production and production key as below:-
+
+```
+{
+      "archetypes": [
+        "non-production"
+      ],
+      "display_name": "Non-Production",
+      "exists": false,
+      "id": "non-production",
+      "parent_id": "landingzones"
+    },
+    {
+      "archetypes": [
+        "production"
+      ],
+      "display_name": "Production",
+      "exists": false,
+      "id": "production",
+      "parent_id": "landingzones"
+    }
+```
+
+3. Now that the new archetypes have been added there needs to be archetype defintion files created - which tie together which assignments are associated to these archetypes. For this example we will apply the same assignments as what would have been applied to the `corp` management group to the new management groups.
+4. In the forked repository in the folder `\platform\alz\archetype_definitions` we can copy the `corp.alz_archetype_definition.json` file twice and rename it to `non-production.alz_archetype_definition.json` and `production.alz_archetype_definition.json`. For each file update the `name` key in the file to match e.g.
+
+```
+{
+  "$schema": "https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/archetype_definition.json",
+  "name": "production",
+  "policy_assignments": [
+    "Audit-PeDnsZones",
+    "Deny-HybridNetworking",
+    "Deny-Public-Endpoints",
+    "Deny-Public-IP-On-NIC",
+    "Deploy-Private-DNS-Zones"
+  ],
+  "policy_definitions": [],
+  "policy_set_definitions": [],
+  "role_definitions": []
+}
+```
+
+5. Since the `corp` and `online` archetypes no longer exist I can rename the archetype files for these with a `.bak` extension so the sync script does not include them.
+6. The new structure file can now be generated - for example:-
+
+```
+New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions\ -Type ALZ -LibraryPath ..\alz-library-fork\ -PacEnvironmentSelector epac-dev
+```
+
+This file will contain the new management groups in the structure file as below:-
+
+```
+"non-production": {
+  "value": "/providers/Microsoft.Management/managementGroups/non-production",
+  "management_group_function": "Non-Production"
+},
+"production": {
+  "value": "/providers/Microsoft.Management/managementGroups/production",
+  "management_group_function": "Production"
+}
+```
+
+7. Run the sync command to import the policies and generate the assignments - for example:-
+
+```
+Sync-ALZPolicyFromLibrary.ps1 -DefinitionsRootFolder .\Definitions\ -Type ALZ -LibraryPath ..\alz-library-fork\ -PacEnvironmentSelector epac-dev
+```
+
+8. There are now two new folders in the `policyAssignments\ALZ` folder as below, and looking at the assigned scope for the assignments we can see they are going to be assigned to the correct management group.
+
+![Assignment File Overview Diagram](Images/new-management-groups.png)
+
+```
+"scope": {
+    "epac-dev": [
+      "/providers/Microsoft.Management/managementGroups/non-production"
+    ]
+  }
+```
+
+9. When maintaining parity with updates from the ALZ team including policy changes and new assignments it will be necessary to sync your forked repo and carefully check the incoming changes.

Docs/integrating-with-alz-library.md

@@ -48,10 +48,9 @@ if ($Tag -eq "") {
 
 if ($LibraryPath -eq "") {
     $LibraryPath = Join-Path -Path (Get-Location) -ChildPath "temp"
+    git clone --config advice.detachedHead=false --depth 1 --branch $Tag https://github.com/Azure/Azure-Landing-Zones-Library.git $LibraryPath
 }
 
-git clone --config advice.detachedHead=false --depth 1 --branch $Tag https://github.com/Azure/Azure-Landing-Zones-Library.git $LibraryPath
-
 $jsonOutput = [ordered]@{
     managementGroupNameMappings = [ordered]@{}
     enforcementMode             = "Default"
@@ -141,7 +140,7 @@ foreach ($parameter in $policyDefaults) {
     if ($Type -eq "AMBA") {
         $assignmentFileName = $assignmentFileName -replace ("-", "_")
     }
-    $file = Get-ChildItem -Recurse -Path ".\temp" -Filter "$assignmentFileName" -File | Select-Object -First 1
+    $file = Get-ChildItem -Recurse -Path $LibraryPath -Filter "$assignmentFileName" -File | Select-Object -First 1
     $jsonContent = Get-Content -Path $file.FullName -Raw | ConvertFrom-Json
     $tempDefaultParamValue = $jsonContent.properties.parameters.$parameterAssignmentName.value
 

Scripts/CloudAdoptionFramework/New-ALZPolicyDefaultStructure.ps1

@@ -18,28 +18,27 @@ Param(
 
 # Latest tag values
 if ($Tag -eq "") {
-   switch ($Type) {
-       'ALZ' {
-           $Tag = "platform/alz/2025.02.0"
-       }
-       'FSI' {
-           $Tag = "platform/fsi/2025.03.0"
-       }
-       'AMBA' {
-           $Tag = "platform/amba/2025.05.0"
-       }
-       'SLZ' {
-           $Tag = "platform/slz/2025.03.0"
-       }
-   }
+    switch ($Type) {
+        'ALZ' {
+            $Tag = "platform/alz/2025.02.0"
+        }
+        'FSI' {
+            $Tag = "platform/fsi/2025.03.0"
+        }
+        'AMBA' {
+            $Tag = "platform/amba/2025.05.0"
+        }
+        'SLZ' {
+            $Tag = "platform/slz/2025.03.0"
+        }
+    }
 }
 
 if ($LibraryPath -eq "") {
     $LibraryPath = Join-Path -Path (Get-Location) -ChildPath "temp"
+    git clone --config advice.detachedHead=false --depth 1 --branch $Tag https://github.com/Azure/Azure-Landing-Zones-Library.git $LibraryPath
 }
 
-git clone --config advice.detachedHead=false --depth 1 --branch $Tag https://github.com/Azure/Azure-Landing-Zones-Library.git $LibraryPath
-
 if ($DefinitionsRootFolder -eq "") {
     if ($null -eq $env:PAC_DEFINITIONS_FOLDER) {
         if ($ModuleRoot) {