Updating and adding guidance for brownfield deployments

docs/content/patterns/alz/Cleaning-Up-Preview-Version-Deployment.md

@@ -0,0 +1,55 @@
+---
+title: Cleaning up preview version deployment
+geekdocCollapseSection: true
+weight: 70
+---
+
+In some scenarios, it may be necessary to remove everything deployed by the ALZ Monitor solution. The instructions below detail execution of a PowerShell script to delete all resources deployed, including:
+
+- Metric Alerts
+- Activity Log Alerts
+- Resource Groups (created for to contain alert resources)
+- Policy Assignments
+- Policy Definitions
+- Policy Set Definitions
+- Policy Assignment remediation identity role assignments
+
+All resources deployed as part of the initial ALZ Monitor deployment and the resources created by dynamically by 'deploy if not exist' policies are either tagged, marked in metadata, or in description (depending on what the resource supports) with the value `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is used to execute the cleanup of deployed resources; _if it has been removed or modified the cleanup script will not include those resources_.
+
+## Cleanup Script Execution
+
+### Download the script file
+
+Follow the instructions below to download the cleanup script file. Alternatively, clone the repo from GitHub and ensure you are working from the latest version of the file by fetching the latest `main` branch.
+
+1. Navigate AMBA [project in GitHub](https://github.com/Azure/azure-monitor-baseline-alerts)
+2. In the folder structure, browse to the `patterns/alz/scripts` directory
+3. Open the **Start-ALZMonitorCleanup.ps1** script file
+4. Click the **Raw** button
+5. Save the open file as **Start-ALZMonitorCleanup.ps1**
+
+### Executing the Script
+
+1. Open PowerShell
+2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph`
+3. Change directories to the location of the **Start-ALZMonitorCleanup.ps1** script
+4. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope.
+5. Execute the script using the option below
+
+**Generate a list of the resource IDs which would be deleted by this script:**
+
+  ```powershell
+  ./Start-ALZMonitorCleanup.ps1 -ReportOnly
+  ```
+
+**Show output of what would happen if deletes executed:**
+
+  ```powershell
+  ./Start-ALZMonitorCleanup.ps1 -WhatIf
+  ```
+
+**Delete all resources deployed by the ALZ-Monitor IaC without prompting for confirmation:**
+
+  ```powershell
+  ./Start-ALZMonitorCleanup.ps1 -Force
+  ```

docs/content/patterns/alz/Cleaning-up-a-Deployment.md

@@ -23,18 +23,18 @@ All resources deployed as part of the initial AMBA deployment and the resources
 Follow the instructions below to download the cleanup script file. Alternatively, clone the repo from GitHub and ensure you are working from the latest version of the file by fetching the latest `main` branch.
 
 1. Navigate AMBA [project in GitHub](https://github.com/Azure/azure-monitor-baseline-alerts)
-1. In the folder structure, browse to the `patterns/alz/scripts` directory
-1. Open the **Start-AMBACleanup.ps1** script file
-1. Click the **Raw** button
-1. Save the open file as **Start-AMBACleanup.ps1**
+2. In the folder structure, browse to the `patterns/alz/scripts` directory
+3. Open the **Start-AMBACleanup.ps1** script file
+4. Click the **Raw** button
+5. Save the open file as **Start-AMBACleanup.ps1**
 
 ### Executing the Script
 
 1. Open PowerShell
-1. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph`
-1. Change directories to the location of the **Start-AMBACleanup.ps1** script
-1. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope.
-1. Execute the script using the option below
+2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph`
+3. Change directories to the location of the **Start-AMBACleanup.ps1** script
+4. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope.
+5. Execute the script using the option below
 
 **Generate a list of the resource IDs which would be deleted by this script:**
 

docs/content/patterns/alz/Known-Issues.md

@@ -6,9 +6,36 @@ weight: 100
 
 ## VM Log Alert policies fail to remediate
 
-#### Error includes 
+### Error includes
 
 *failed to resolve table or column expression named*
 
-#### Cause
-The underlying data is not present in the Log Analytics table. For VM Alerts please enable [VM Insights](../Monitoring-and-Alerting#log-alerts)
+### Cause
+
+The underlying data is not present in the Log Analytics table.
+
+### Resolution
+
+For VM Alerts please enable [VM Insights](Monitoring-and-Alerting#log-alerts).
+
+## Failed to deploy because of role assignemnt issue
+
+Deployment of AMBA fails when there are orphaned role assignements.
+
+### Error includes
+
+*"error": { </br>
+&emsp;"code": "RoleAssignmentUpdateNotPermitted", </br>
+&emsp;"message": "Tenant ID, application ID, principal ID, and scope are not allowed to be updated." </br>
+&emsp;}*
+
+### Cause
+
+When a role or a role assignement is removed, some orphaned object can still appear, preventing a successful deployment.
+
+### Resolution
+
+1. Navigate to ***Management Groups***
+2. Select the management group (corresponding to the value entered for the *enterpriseScaleCompanyPrefix* during the deployment) were AMBA deployment was targeted to
+3. Select ***Access control (IAM)***
+4. Under the ***Contributor*** role, select all records named ***Identity not found*** entry and click ***Remove***

docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md

@@ -3,6 +3,10 @@ title: Deploy with Azure PowerShell
 weight: 40
 ---
 
+{{< hint type=Important >}}
+Updating from a preview version is not supported. If you deployed a preview version, please proceed with [Cleaning Up Preview Version Deployment](../Cleaning-Up-Preview-Version-Deployment) before continuing.
+{{< /hint >}}
+
 ## 1. Parameter configuration
 
 To start, you can either download a copy of the parameter file or clone/fork the repository.
@@ -13,31 +17,41 @@ The following changes apply to all scenarios, whether you are aligned or unalign
 
 - Change the value of _enterpriseScaleCompanyPrefix_ to the management group where you wish to deploy the policies and the initiatives. This is usually the so called "pseudo root management group", e.g. in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the so called "Intermediate Root Management Group" (directly beneath the "Tenant Root Group").
 - Change the value of _ALZMonitorResourceGroupName_ to the name of the resource group where the activity logs, resource health alerts, actions groups and alert processing rules will be deployed in.
+<!--
 - Change the value of _ALZMonitorResourceGroupTags_ to specify the tags to be added to said resource group.
+-->
 - Change the value of _ALZMonitorResourceGroupLocation_ to specify the location for said resource group.
 - Change the value of _ALZMonitorActionGroupEmail_ (specific to the Service Health initiative) to the email address where notifications of the alerts are sent to.
 - If you would like to disable initiative assignments, you can change the value on one or more of the following parameters; _enableAMBAConnectivity_, _enableAMBAIdentity_, _enableAMBALandingZone_, _enableAMBAManagement_, _enableAMBAServiceHealth_ to "No".
 
 ### If you are aligned to ALZ
+
+- Change the value of _platformManagementGroup_ to the management group id for Platform.
 - Change the value of _IdentityManagementGroup_ to the management group id for Identity.
 - Change the value of _managementManagementGroup_ to the management group id for Management.
 - Change the value of _connectivityManagementGroup_ to the management group id for Connectivity.
 - Change the value of _LandingZoneManagementGroup_ to the management group id for Landing Zones.
 
 ### If you are unaligned to ALZ
+
+- Change the value of _platformManagementGroup_ to the management group id for Platform. The same management group id may be repeated.
 - Change the value of _IdentityManagementGroup_ to the management group id for Identity. The same management group id may be repeated.
 - Change the value of _managementManagementGroup_ to the management group id for Management. The same management group id may be repeated.
 - Change the value of _connectivityManagementGroup_ to the management group id for Connectivity. The same management group id may be repeated.
-- Change the value of _LandingZoneManagementGroup_ to the management group id for Landing Zones. The same management group id may be repeated
+- Change the value of _LandingZoneManagementGroup_ to the management group id for Landing Zones. The same management group id may be repeated.
+
 {{< hint type=note >}}
 For ease of deployment and maintenance we have kept the same variables. If, for example, you combined Identity, Management and Connectivity into one management group you should configure the variables _identityManagementGroup_, _managementManagementGroup_ and _connectivityManagementGroup_ with the same management group id.
 {{< /hint >}}
 
 ### If you have a single management group
+
+- Change the value of _platformManagementGroup_ to the pseudo root management group id, also called the "Intermediate Root Management Group".
 - Change the value of _IdentityManagementGroup_ to the pseudo root management group id, also called the "Intermediate Root Management Group".
 - Change the value of _managementManagementGroup_ to the pseudo root management group id, also called the "Intermediate Root Management Group".
 - Change the value of _connectivityManagementGroup_ to the pseudo root management group id, also called the "Intermediate Root Management Group".
 - Change the value of _LandingZoneManagementGroup_ to the pseudo root management group id, also called the "Intermediate Root Management Group".
+
 {{< hint type=note >}}
 For ease of deployment and maintenance we have kept the same variables. Configure the variables _enterpriseScaleCompanyPrefix_, _identityManagementGroup_, _managementManagementGroup_, _connectivityManagementGroup_ and _LZManagementGroup_ with the pseudo root management group id.
 {{< /hint >}}
@@ -54,6 +68,9 @@ Note that the parameter file shown below has been truncated for brevity, compare
         "enterpriseScaleCompanyPrefix": {
             "value": "contoso"
         },
+        "platformManagementGroup": {
+            "value": "contoso-platform"
+        },
         "IdentityManagementGroup": {
             "value": "contoso-identity"
         },
@@ -101,7 +118,8 @@ Note that the parameter file shown below has been truncated for brevity, compare
 ```
 
 ## 3. Configuring variables for deployment
-The following commands apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group.
+
+The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group.
 
 Open a PowerShell prompt, navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives.
 
@@ -117,7 +135,8 @@ Above-mentioned "pseudoRootManagementGroup" variable value, being the so called
 {{< /hint >}}
 
 ## 4. Deploy the policy definitions, initiatives and policy assignments with default settings
-The following commands apply to all scenarios, whether you are aligned or unaligned with ALZ or don't have management groups.
+
+The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group.
 
 Using a PowerShell prompt, if you closed your previous session, navigate again to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives.
 
@@ -129,5 +148,6 @@ This should be tested in a safe environment. If you are subsequently looking to
 New-AzManagementGroupDeployment -ManagementGroupId $pseudoRootManagementGroup -Location $location -TemplateUri "https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/alzArm.json" -TemplateParameterFile ".\patterns\alz\alzArm.param.json"
 ```
 
-# Next steps
-- To remediate non-compliant policies, please proceed with [Policy remediation](../Remediate-Policies)
+## Next steps
+
+To remediate non-compliant policies, please proceed with [Policy remediation](../Remediate-Policies)