Azure · jtracey93 · Nov 2, 2022 · Oct 27, 2022 · Oct 27, 2022 · Oct 31, 2022
diff --git a/docs/wiki/PolicyDeepDive.md b/docs/wiki/PolicyDeepDive.md
@@ -70,4 +70,169 @@ Please see the following wiki article that explains this process further: [Addin
 
 ## How do we assign a built-in or custom Azure Policy?
 
-Please see the following wiki article that explains this process further: [Assigning Azure Policies](https://github.com/Azure/ALZ-Bicep/wiki/AssigningPolicies)
+Please see the following wiki article that explains this process further: [Assigning Azure Policies](https://github.com/Azure/ALZ-Bicep/wiki/AssigningPolicies)
+
+## How to migrate ALZ custom policies to Azure built-in policies
+
+Every so often there will be a new Azure built-in policy or policy initiative that replicates functionality previously found only in ALZ custom policies. When this happens, a new release of ALZ-Bicep will contain details around the policies involved as well as upgrade considerations. The below describes generic scenarios for migrating from ALZ custom policies to Azure built-in policies, leveraging ALZ-Bicep functionality. fixme assuming that ALZ-Bicep is leveraged completely i.e. with default policy assignments.
+
+### Update scenarios
+There are the following scenarios for ALZ custom policies being superseded by Azure built-in policies, listed in order of complexity:
+1. A single ALZ custom policy, which is not assigned anywhere in your Azure estate, is superseded by an Azure built-in policy.
+2. A single ALZ custom policy, which is assigned at one or more scopes in your Azure estate, is superseded by an Azure built-in policy. The process for managing this is described in [Migrate single ALZ custom policy to built-in policy](#migrate-single-pol).
+3. One or more ALZ custom policies, assigned via ALZ custom policy intiative, which are superseded by Azure built-in policies. The process for managing this is described in [Migrate ALZ custom policies in initiatives to built-in policies](#migrate-multiple-pol).
+
+#### Migrate single ALZ custom policy to built-in policy
+For this scenario we will use the ALZ custom policy _Deny the creation of public IP_ which will be migrated to the built-in policy _Not allowed resource types_
+
+To carry out the instructions in the scenario the operator will require Resource Policy Permissions at the root of the ALZ management group hierarchy
+
+- Go to https://portal.azure.com
+- Open Policy
+- Go to Definitions and in Search find the ALZ custom policy.
+
+  ![alz-custom-policy-def-search](media/alz-update-to-builtin-01.png)
+
+- Click on the hyperlink for the policy definition
+- To determine if the policy is assigned at any scope in the ALZ management group structure start by getting the policy definition ID
+
+  ![alz-custom-policy-def-name](media/alz-determine-policy-assign-01.png)
+
+- Since there is no easy way to get the various scopes a policy is assigned to, go to Azure Resource Graph Explorer
+- Ensure that scope for the query is Directory and then execute the following kusto query:
+
+  ```kusto
+    PolicyResources |
+    where kind =~ 'policyassignments' and tostring(properties.policyDefinitionId) =~ '/providers/Microsoft.Management/managementGroups/contoso/providers/Microsoft.Authorization/policyDefinitions/Deny-PublicIP'
+    | extend
+        assignmentScope = tostring(properties.scope),
+        assignmmentNotScopes = tostring(properties.notScopes),
+        assignmmentParameters = tostring(properties.parameters)
+    | project assignmentScope,
+        assignmmentNotScopes,
+        assignmmentParameters
+  ```
+
+- The above command will give different results depending on whether the policy is assigned or not. If the policy is not assigned, you can jump directly to the Delete Policy Definition step in the following. If the policy is assigned though you should get a result somewhat similar to what is shown below.
+
+  ![alz-custom-policy-assignments](media/alz-determine-policy-assign-02.png)
+
+- As can be seen this particular policy is assigned with only a simple Deny effect parameter at the following levels in the management group structure
+  - Contoso/contoso-landingzones/contoso-landingzones-corp
+  - Contoso/contoso-platform/contoso-platform-identity
+
+> Note that the provided example has a simple parameter set. If more complex parameters are assigned to a policy which is to be migrated those should be noted down. In that respect the possibility to download the query results as CSV could be leveraged.
+
+- Switch from Azure Resource Graph Explorer back to the Policy view
+- Change the scope to include the scopes determined in the previous step. and search for the relevant policy
+
+  ![alz-delete-policy-assignments](media/alz-delete-policy-assign-01.png)
+
+- For each assignment, click the ellipsis and select Delete Assignment.
+- Once all policy assignments are deleted, go to the Definitions pane, search for the definition. Once found click the ellipsis and choose Delete Policy Definition
+- Follow the next steps in fixme to deploy policy assignments with the Azure built-in policy
+
+### Migrate ALZ custom policies in initiatives to built-in policies
+
+For this scenario we will use the ALZ custom initiative _Deploy Diagnostic Settings to Azure Services_ which is leveraging quite a large number of ALZ custom policies to apply diagnostics settings for various resources.
+
+To carry out the instructions in the scenario the operator will require Resource Policy Permissions at the root of the ALZ management group hierarchy
+
+[Azure Portal](#tab/azure-portal)
+
+- Go to https://portal.azure.com
+- Open Policy
+- Go to Definitions and in Search find the ALZ custom policy initiative.
+
+  ![alz-custom-initiative-def-search](media/alz-update-initiative-with-builtin-01.png)
+
+- Click on the hyperlink for the initiative definition
+- To determine where the initiative is assigned at any scope in the ALZ management group structure start by getting the initiative name
+
+  ![alz-custom-initiative-def-name](media/alz-update-initiative-with-builtin-02.png)
+
+- Since there is no easy way to get the various scopes an initiative is assigned to, got Azure Resource Graph Explorer
+- Ensure that scope for the query is Directory and then execute the following kusto query:
+
+  ```kusto
+    PolicyResources |
+    where kind =~ 'policyassignments' and tostring(properties.policyDefinitionId) =~ '/providers/Microsoft.Management/managementGroups/contoso/providers/Microsoft.Authorization/policySetDefinitions/Deploy-Diagnostics-LogAnalytics'
+    | extend
+        assignmentScope = tostring(properties.scope),
+        assignmmentNotScopes = tostring(properties.notScopes),
+        assignmmentParameters = tostring(properties.parameters)
+    | project assignmentScope,
+        assignmmentNotScopes,
+        assignmmentParameters
+  ```
+
+- The above command will give a result similar to what is shown below
+
+  ![alz-custom-initiative-assignments](media/alz-update-initiative-with-builtin-03.png)
+
+- As can be seen this particular initiative is assigned with only a single parameter at the following levels in the management group structure
+  - Contoso/
+
+> Note
+that the provided example has a simple parameter set. If more complex parameters are assigned to a policy which is to be migrated those should be noted down. In that respect the possibility to download the query results as CSV could be leveraged.
+
+- Switch from Azure Resource Graph Explorer back to the Policy view
+- Change the scope to include the scope described above, and search for the relevant initiative
+
+  ![alz-delete-initiative-assignments](media/alz-update-initiative-with-builtin-04.png)
+
+- For each assignment, click the ellipsis and select Delete Assignment.
+- Once all initiative assignments are deleted, go to the Definitions pane, search for the initiative definition. Once found click the ellipsis and choose Delete Policy Definition
+
+    ![alz-custom-initiative-def-search](media/alz-update-initiative-with-builtin-01.png)
+
+
+
+### Synchronize your local repo with ALZ-Bicep
+
+To get the latest updates from the ALZ-Bicep repo and download to you local repo, do the following.
+- On a client where you have already cloned your version of the ALZ-Bicep repo, start a PowerShell command prompt
+- Navigate to the root of the local version of the repo
+- Verify that you are on the main branch and up-to-date by running the following commands
+
+  ```posh
+  git checkout main
+  git pull
+  ```
+
+- Synchronize your local repo with the ALZ-Bicep repo by running the following
+command
+  ```posh
+  .github/scripts/Invoke-GitHubReleaseFetcher.ps1 -githubRepoUrl "https://github.com/Azure/ALZ-Bicep"
+  ```
+
+- When you have synchronized your repo perform the following verification tasks
+  - Verify that removed policy definition has been removed from ./infra-as-code/bicep/modules/policy/definitions/customPolicyDefinitions.bicep
+  - Verify that ./infra-as-code/bicep/modules/policy/assignments/alzdefaults/alzDefaultPolicyAssignments.bicep has been updated to no longer include assignments for the removed ALZ custom policy
+  - Verify that the built-in policy has been added to ./infra-as-code/bicep/modules/policy/assignments/alzdefaults/alzDefaultPolicyAssignments.bicep. fixme this depends on whether the policy is part of default assignments some verbiage around this.
+  - If the built-in policy requires input parameters, verify that samples of those are included in ./infra-as-code/bicep/modules/policy/assignments/alzdefaults/parameters/alzDefaultPolicyAssignments.parameters.all.json, and modify your own version of the parameter file accordingly. fixme reference to general guidance for managing ALZ with Bicep, i.e. specifically to isolate parameter files so they are not overwritten.
+
+### Deploy changed policy assignments
+
+- Create a branch for the updates by running the following commands
+
+  ```posh
+  git branch <your branch name>
+  git checkout <your branch name>
+  ```
+
+- Run git status to verify which files are modified
+- Run git add <`filename`> to add the relevant files to staging. The following files could be in scope:
+  - ./infra-as-code/bicep/modules/policy/assignments/alzdefaults/alzDefaultPolicyAssignments.bicep
+  - ./infra-as-code/bicep/modules/policy/assignments/alzdefaults/parameters/alzDefaultPolicyAssignments.parameters.all.json
+  - ./infra-as-code/bicep/modules/policy/assignments/alzdefaults/parameters/<your default policy assignment parameter file>
+  - ./infra-as-code/bicep/modules/policy/definitions/customPolicyDefinitions.bicep
+  - ./infra-as-code/bicep/modules/policy/definitions/lib/policy_definitions/<removed ALZ custom policy definition file>
+  - ./infra-as-code/bicep/modules/policy/definitions/lib/policy_set_definitions/<removed ALZ custom policy initiative definition file>
+- Leveraging the guidance in [Module: Custom Policy Definitions](https://github.com/Azure/ALZ-Bicep/tree/main/infra-as-code/bicep/modules/policy/definitions), deploy the updated custom policy definitions to your [canary environment](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/testing-approach). After deploying verify that only the expected policy definitions has been created.
+- Leveraging the guidance in [Module: ALZ Default Policy Assignments](https://github.com/Azure/ALZ-Bicep/tree/main/infra-as-code/bicep/modules/policy/assignments/alzDefaults), deploy the updated default policy assignments to your [canary environment](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/testing-approach). After deploying verify that only the expected policy assignments has been created.
+- Test that policies are working as intended.
+- After the above steps have completed, leverage the guidance in [Module: Custom Policy Definitions](https://github.com/Azure/ALZ-Bicep/tree/main/infra-as-code/bicep/modules/policy/definitions), deploy the updated custom policy definitions to your production environment
+- Leveraging the guidance in [Module: ALZ Default Policy Assignments](https://github.com/Azure/ALZ-Bicep/tree/main/infra-as-code/bicep/modules/policy/assignments/alzDefaults), deploy the updated default policy assignments to your production environment
+
+
diff --git a/docs/wiki/media/alz-delete-policy-assign-01.png b/docs/wiki/media/alz-delete-policy-assign-01.png
diff --git a/docs/wiki/media/alz-determine-policy-assign-01.png b/docs/wiki/media/alz-determine-policy-assign-01.png
diff --git a/docs/wiki/media/alz-determine-policy-assign-02.png b/docs/wiki/media/alz-determine-policy-assign-02.png
diff --git a/docs/wiki/media/alz-update-initiative-with-builtin-01.png b/docs/wiki/media/alz-update-initiative-with-builtin-01.png
diff --git a/docs/wiki/media/alz-update-initiative-with-builtin-02.png b/docs/wiki/media/alz-update-initiative-with-builtin-02.png
diff --git a/docs/wiki/media/alz-update-initiative-with-builtin-03.png b/docs/wiki/media/alz-update-initiative-with-builtin-03.png
diff --git a/docs/wiki/media/alz-update-initiative-with-builtin-04.png b/docs/wiki/media/alz-update-initiative-with-builtin-04.png
diff --git a/docs/wiki/media/alz-update-to-builtin-01.png b/docs/wiki/media/alz-update-to-builtin-01.png