-
Notifications
You must be signed in to change notification settings - Fork 981
ALZ AMA PowerShell Script
Important
This script intended for Azure Landing Zone Portal Accelerator deployments only. It is not for Terraform and Bicep deployments of ALZ.
We have created a script that can assist you with updating the Azure Landing Zones components. This script can automatically do the following tasks, you can turn on or off some parts of the script, see the Syntax section for more details:
- Update Policies and Initiatives.
- Delete outdated Policy Assignments.
- Deploy a User Assigned Managed Identity for the AMA agent.
- Deploys Data Collection Rules.
- Assign new Policies and Initiatives.
- Remove Legacy Solutions
- Create remediation tasks for the newly assigned Policies and initiatives.
- Remove obsolete User Assigned Managed Identities (that were deployed with releases starting 2024-01-31 until 2024-04-24)
Important
The script will NOT remove the MMA agent. Please see Removing MMA & additional steps.
The ALZ team will support the PowerShell script for six months after MMA deprecation date, until February 28, 2025. Please report any issues here: Issues
- PowerShell 7 (Tested with version 7.4.2 on Windows)
- Az Modules
- Az.Resources (Tested with version 7.1.0)
- Az.Accounts (Tested with version 3.0.0)
- Az.MonitoringSolutions (Tested with version 0.1.1)
- Az.ResourceGraph (Tested with version 1.0.0)
- Git
Note
While other configurations and versions may work, please update first if you run into any issues before raising an Issue
Update-AzureLandingZonesToAMA
[-location <string>] (Required)
[-eslzRoot <string>] (Required)
[-managementResourceGroupName <string>] (Required)
[-workspaceResourceId <string>] (Required)
[-workspaceRegion <string>] (Required)
[-migrationPath <string>, accepted values "MMAToAMA", "UpdateAMA"] (Required)
[-deployUserAssignedManagedIdentity <switch>] (Optional)
[-deployVMInsights <switch>] (Optional)
[-deployChangeTracking <switch>] (Optional)
[-deployMDfCDefenderSQL <switch>] (Optional)
[-deployAzureUpdateManager <switch>] (Optional)
[-remediatePolicies <switch>] (Optional)
[-removeLegacyPolicyAssignments <switch>] (Optional)
[-removeLegacySolutions <switch>] (Optional)
[-updatePolicyDefinitions <switch>] (Optional)
[-removeObsoleteUAMI <switch>] (Optional).\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law" -workspaceRegion "northeurope" -migrationPath MMAToAMA -updatePolicyDefinitions
Updating Policies ...
- Updating Policy Definitions: Resource changes: 32 to create, 58 to modify, 68 no change. ...
- Updating Policy Set Definitions: Resource changes: 32 to create, 8 to modify, 5 no change. ....\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law" -workspaceRegion "northeurope" -migrationPath MMAToAMA -removeLegacyPolicyAssignments -deployVMInsights
Removing legacy Policy Assignments ...
- Removing legacy Policy Assignments: Deploy-VM-Monitoring from scope contoso ...
- Removing legacy Policy Assignments: Deploy-VMSS-Monitoring from scope contoso ...
Deploying User Assigned Managed Identity ...
- Deploying User Assigned Managed Identity: Name: id-ama-prod-northeurope-001 to resource group contoso-mgmt; Resource changes: 1 to create, 12 to ignore. ...
- Assigning 'DenyAction-DeleteUAMIAMA' policy to scope contoso-platform ...
Deploying VMInsights ...
- Deploying a data collection rule for VMInsights: Name: dcr-vminsights-prod-northeurope-001 to resource group contoso-mgmt; Resource changes: 1 to create, 13 to ignore. ...
- Assigning policies for VMInsights: DINE-VMMonitoringPolicyAssignment.json to scope contoso-platform; Resource changes: 5 to create. ...
- Assigning policies for VMInsights: DINE-VMSSMonitoringPolicyAssignment.json to scope contoso-platform; Resource changes: 5 to create. ...
- Assigning policies for VMInsights: DINE-VMHybridMonitoringPolicyAssignment.json to scope contoso-platform; Resource changes: 3 to create. ...
- Assigning policies for VMInsights: DINE-VMMonitoringPolicyAssignment.json to scope contoso-landingzones; Resource changes: 5 to create. ...
- Assigning policies for VMInsights: DINE-VMSSMonitoringPolicyAssignment.json to scope contoso-landingzones; Resource changes: 5 to create. ...
- Assigning policies for VMInsights: DINE-VMHybridMonitoringPolicyAssignment.json to scope contoso-landingzones; Resource changes: 3 to create. ....\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law" -workspaceRegion "northeurope" -migrationPath MMAToAMA -removeLegacySolutions -WhatIf
Removing legacy solutions ...
What if: Performing the operation "- Removing legacy solutions: VMInsights(contoso-law)" on target "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law".
What if: Performing the operation "- Removing legacy solutions: AgentHealthAssessment(contoso-law)" on target "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law".
What if: Performing the operation "- Removing legacy solutions: Updates(contoso-law)" on target "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law".
What if: Performing the operation "- Removing legacy solutions: SQLAssessment(contoso-law)" on target "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law".
What if: Performing the operation "- Removing legacy solutions: SQLAdvancedThreatProtection(contoso-law)" on target "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law".
What if: Performing the operation "- Removing legacy solutions: SQLVulnerabilityAssessment(contoso-law)" on target "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law".
What if: Performing the operation "- Removing legacy solutions: Security(contoso-law)" on target "/subscriptions/{subscriptionId}/resourcegroups/contoso-mgmt/providers/microsoft.operationalinsights/workspaces/contoso-law".The deployment location.
| Type | String |
|---|---|
| Required | True |
| Default value | None |
Intermediate root management group id.
| Type | String |
|---|---|
| Required | True |
| Default value | None |
The management Resource Group name. This is eslzRoot-mgmt. For example contoso-mgmt.
| Type | String |
|---|---|
| Required | True |
| Default value | None |
Log Analytics workspace id. Expected format /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}
| Type | String |
|---|---|
| Required | True |
| Default value | None |
The Log Analytics workspace region.
| Type | String |
|---|---|
| Required | True |
| Default value | None |
This parameter determines what parts of the script are available depending on your migration scenario.
- Use
MMAToAMAif you are currently using MMA and need to perform a full migration. Applies to release 2024-01-07 and earlier. - Use
UpdateAMAif you are currently using AMA that was deployed by the Portal Accelerator over the past months. Applies to releases; 2024-04-24, 2024-03-08, 2024-03-04, 2024-02-14, 2024-02-12, 2024-02-07, 2024-02-05, 2024-01-31.
| Type | String |
|---|---|
| Required | True |
| Default value | None |
| Allowed values | "MMAToAMA", "UpdateAMA" |
Available parameters for MMAToAMA
|
UpdatePolicyDefinitionsRemoveLegacyPolicyAssignmentsDeployUserAssignedManagedIdentityDeployVMInsightsDeployChangeTrackingDeployMDfCDefenderSQLDeployAzureUpdateManagerRemoveLegacySolutionsRemediatePolicies
|
Available parameters for UpdateAMA
|
UpdatePolicyDefinitionsRemoveLegacyPolicyAssignmentsDeployUserAssignedManagedIdentityDeployVMInsightsDeployChangeTrackingDeployMDfCDefenderSQLRemediatePoliciesremoveObsoleteUAMI
|
Deploys a User Assigned Managed Identity to the Management Resource Group.
- Checks for an existing User Assignment Managed Identity
id-ama-prod-$location-001in the management resource group. - Checks for an existing policy assignment
DenyAction-DeleteUAMIAMAon the platform management group scope. - Deploys a User Assigned Managed Identity template userAssignedIdentity.json.
- Deploys a Policy Assignment template DENYACTION-DeleteUAMIAMAPolicyAssignment.json.
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Deploys the Data Collection Rule for VM Insights and assigns new policies. When it is run to Update AMA it will update the existing Policy Assignments to enable the single centralized UAMI by setting the feature flag restrictBringYourOwnUserAssignedIdentityToSubscription to false. Due to dependencies, running this command will also deploy the User Assigned Managed Identity resources.
- Checks for an existing Data Collection rule
dcr-vminsights-prod-$location-001in the management Resource Group. - Checks for existing policy assignments
Deploy-VM-Monitoring,Deploy-VMSS-Monitoring,Deploy-vmHybr-Monitoringon the platform and landing zone scopes. - Deploys a Data Collection Rule template dataCollectionRule-VmInsights.json.
- Deploys Policy Assignment templates; DINE-VMMonitoringPolicyAssignment.json, DINE-VMSSMonitoringPolicyAssignment.json, DINE-VMHybridMonitoringPolicyAssignment.json
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Deploys the Data Collection Rule for Change Tracking and assigns new policies. When it is run to Update AMA it will update the existing Policy Assignments to enable the single centralized UAMI by setting the feature flag restrictBringYourOwnUserAssignedIdentityToSubscription to false. Due to dependencies, running this command will also deploy the User Assigned Managed Identity resources.
- Checks for an existing Data Collection rule
dcr-changetracking-prod-$location-001in the management Resource Group. - Checks for existing policy assignments
Deploy-VM-ChangeTrack,Deploy-VMSS-ChangeTrack,Deploy-vmArc-ChangeTrackon the platform and landing zone scopes. - Deploys a Data Collection Rule template dataCollectionRule-CT.json.
- Deploys Policy Assignment templates; DINE-ChangeTrackingVMPolicyAssignment.json, DINE-ChangeTrackingVMSSPolicyAssignment.json, DINE-ChangeTrackingVMArcPolicyAssignment.json
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Deploys the Data Collection Rule for Defender for SQL and assigns new policies. Due to dependencies, running this command will also deploy the User Assigned Managed Identity resources.
- Checks for an existing Data Collection rule
dcr-defendersql-prod-$location-001in the management Resource Group. - Checks for an existing policy assignment
Deploy-MDFC-DefSQL-AMAon the platform and landing zone scopes. - Deploys a Data Collection Rule template dataCollectionRule-DefenderSQL.json.
- Deploys Policy Assignment template DINE-MDFCDefenderSQLAMAPolicyAssignment.json.
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Configures Azure Update Manager.
- Checks for an existing policy assignment
Enable-AUM-CheckUpdates. - Deploys Policy Assignment template MODIFY-AUM-CheckUpdatesPolicyAssignment.json.
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Creates remediation tasks for the following Policy Assignments:
- [Preview]: Enable ChangeTracking and Inventory for virtual machine scale sets
- [Preview]: Enable ChangeTracking and Inventory for virtual machines
- [Preview]: Enable ChangeTracking and Inventory for Arc-enabled virtual machines
- Enable Azure Monitor for VMSS with Azure Monitoring Agent(AMA)
- Enable Azure Monitor for VMs with Azure Monitoring Agent(AMA)
- Enable Azure Monitor for Hybrid VMs with AMA
- Configure SQL VMs and Arc-enabled SQL Servers to install Microsoft Defender for SQL and AMA with a user-defined LA workspace
- Deploy-AUM-CheckUpdates
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Removes deprecated policy assignments.
When combined with parameter -MMAToAMA it removes assignments:
- deploy-vm-monitoring
- deploy-vmss-monitoring
When combined with parameter -UpdateAMA it removes assignments:
- deploy-mdfc-defensql-ama
- deploy-uami-vminsights
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Removes all Legacy Solutions from the specified Log Analytics workspace except for SecurityInsights which is used by Microsoft Sentinel and ChangeTracking.
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Updates custom Policy and Policy Set Definitions.
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Initially a User Assigned Identity was created for each subscription. After implementing the AMA updates a new centralized UAMI will replace the existing Identities. When the centralized Identity is assigned to the VM/VMSS it is highly recommended to removed the previously created identities.
If the Identity resource group is empty, it will also be removed.
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
Specify the resource group name of the obsolete User Assigned Managed Identity.
| Type | String |
|---|---|
| Required | False |
| Default value | "rg-ama-prod-001" |
Shows what would happen if the script runs. The script is not run.
| Type | SwitchParameter |
|---|---|
| Required | False |
| Default value | None |
- What's New?
- Community Calls
- Frequently Asked Questions (FAQ)
- Known issues
- What is Enterprise-Scale
- How it Works
- Deploying Enterprise-Scale
- Pre-requisites
- ALZ Resource Providers Guidance
- Configure Microsoft Entra permissions
- Configure Azure permissions
- Deploy landing zones
- Deploy reference implementations
- Telemetry Tracking Using Customer Usage Attribution (PID)
- Deploy without hybrid connectivity to on-premises
- Deploy with a hub and spoke based network topology
- Deploy with a hub and spoke based network topology with Zero Trust principles
- Deploy with an Azure Virtual WAN based network topology
- Deploy for Small Enterprises
- Operating the Azure platform using AzOps (Infrastructure as Code with GitHub Actions)
- Deploy workloads
- Create landing zones (subscriptions) via Subscription Vending
- Azure Landing Zones Deprecated Services
- Azure Landing Zone (ALZ) Policies
- Policies included in Azure landing zones reference implementations
- Policies included but not assigned by default and Workload Specific Compliance initiatives
- Policies FAQ & Tips
- Policies Testing Framework
- Migrate Azure landing zones custom policies to Azure built-in policies
- Updating Azure landing zones custom policies to latest
- MMA Deprecation Guidance
- Contributing