Skip to content

ALZ AMA Migration Guidance

Jump to bottom
github-actions edited this page Jun 21, 2024 · 1 revision

Introduction

The ALZ Portal Accelerator has recently been enhanced, and starting with the 2024-01-31 release, has removed the legacy MMA agent and now deploys Azure Monitor Agent (AMA) to new environments. With the 2024-06-03 release, there are also updates for User Assigned Managed Identities. Azure Landing Zones has transitioned to using one centralized User Assigned Managed Identity. This consolidation of User Assigned Managed Identity for AMA represents an important improvement in managing deployments at scale more effectively. Please refer to What’s new for more information.

This guide explains the topics and configurations that Azure Landing Zones use, and we discuss many of the common scenarios in the section on assessing the current state. However, this guide does not provide detailed instructions for custom implementations or extra features that are not part of Azure Landing Zones. For those scenarios, we refer to the documentation from the Product teams.

If you are looking for Terraform guidance please refer to [User Guide] Upgrade from v5.2.1 to v6.0.0

And for Bicep guidance refer to: v0.18.0 Release Notes

Parity gaps

Please check the most recent information on parity gaps before you begin:

MDfC Defender for Servers

All Defender for Servers features and capabilities will be provided through a single agent Microsoft Defender for Endpoint (MDE) integration, complemented by agentless capabilities, without dependency on either Log Analytics Agent (MMA) or Azure Monitoring Agent (AMA). Please refer to the following blog post containing the latest information Microsoft Defender for Cloud - strategy and plan towards Log Analytics Agent (MMA) deprecation - Microsoft Community Hub

This guide covers the following topics

  • Assess current state: Identify and determine the steps required to migrate to AMA.
  • Update Azure Landing Zones: Guidance and automation to update your Azure Landing Zones components. Automation helps configure the following tasks:
    • Deploy User Assigned Managed Identity
    • Deploy Data Collection Rules
    • Update Policy and Initiative definitions
    • Remove Legacy Policy Assignments
    • Remove Legacy Solutions
    • Assigning new Policies and Initiatives
    • Assign permissions to Landing Zones managed identity
    • Policy remediation
  • Removing MMA and additional steps: Depending on the discoveries during the initial assessment you may need to run additional steps before you can remove MMA. Please refer to the tooling and guidance provided by the product team:
    • Configure additional Data collection Rules (DCR Config Generator)
    • AMA Migration for Microsoft Sentinel. Configuring connectors to send events via AMA
    • Installing AMA on Non-Azure VMs with Azure Arc
    • Update your Hybrid Workers (V1) to Extension based Hybrid Workers (V2)
    • Custom settings for Change Tracking data types
    • Migrating schedules to Azure Update Manager
    • Removing MMA Agent

Migration paths

  1. Migrate from MMA to AMA. Applies to releases: a. 2024-01-07 and earlier
  2. Update to latest AMA release. Applies to releases: a. 2024-04-24 a. 2024-03-08 a. 2024-03-04 a. 2024-02-14 a. 2024-02-12 a. 2024-02-07 a. 2024-02-05 a. 2024-01-31

Migrate from MMA to AMA

Assess current state

Although this guidance is concentrated on managing resources within Azure Landing Zones, it is crucial to be aware of other settings in your environment that may necessitate further considerations and steps when planning to migrate.

It's advisable to evaluate and record the information listed below, each of these points will be covered in more detail:

  • Identify which computers are linked to the Log Analytics Workspace.
  • Identify which Agents have VM Insights enabled.
  • Identify what Windows event logs the legacy agent’s collects.
  • Identify what Windows performance counters are collected via legacy agents.
  • Identify what Linux performance counters are collected via legacy agents.
  • Identify which Linux Syslog are collected by legacy agents.
  • Review if Windows IIS Logs are being collected through legacy agents.
  • Review whether any custom logs are collected using legacy agents.
  • Document Legacy Workspace Solutions that are implemented within the Workspace.
  • Document which legacy agents are set up as Hybrid Workers within Automation Accounts.

AMA Migration Helper

AMA Migration Helper is a workbook-based Azure Monitor solution that helps you discover what to migrate and track progress as you move from Log Analytics Agent to Azure Monitor Agent. AMA Migration Helper

Non-Azure VMs

Should you encounter Non-Azure Virtual Machines utilizing the MMA agent, it is required to on-board them to Azure Arc prior to setting up AMA. Follow the Azure Arc documentation for guidance Plan and deploy Azure Arc-enabled servers - Azure Arc

Microsoft Sentinel

If Microsoft Sentinel is used in your environment, please refer to the recommended migration plan for additional steps and guidance. AMA migration for Microsoft Sentinel

Change Tracking

This guide assumes the default configuration, if you have changed the settings for Change Tracking data types, see migration options here: Migration guidance from Change Tracking and inventory using Log Analytics to Change Tracking and inventory using Azure Monitoring Agent version

Azure Update Manager

Azure Landing Zones assigns policies that enable periodic assessments in Azure Update Manager. If you require to migrate additional configurated like schedules please consult Move from Automation Update Management to Azure Update Manager

Migrate additional services and features

Azure Monitor Agent is GA for data collection. Most services that used Log Analytics agent for data collection have migrated to Azure Monitor Agent. Refer to the table provided here Migrate additional services and features for more information.

Identify which computers are linked to the Log Analytics Workspace

Use the following KQL query on the Log Analytics Workspace to identify computers that are linked to the Log Analytics Workspace:

Heartbeat
| where TimeGenerated >= ago(7d)
| summarize make_set(Category) by Computer
| extend Legacy = iif(set_Category contains "Direct" or set_Category contains "SCOM", true, false)
| extend AMA = iif(set_Category contains "Monitor", true, false)
| extend Status = case(
  Legacy == true and AMA == false, "Not started",
  Legacy == true and AMA == true, "In progress",
  "Completed"
  )
| project-away set_Category
| order by Computer asc
| project
  Computer,
  ["Migration Status"] = Status,
  ["Legacy Installed"] = Legacy,
  ["AMA Installed"] = AMA

Identify which Agents have VM Insights enabled

Use the following KQL query on the Log Analytics Workspace to identify agents that VM Insights enabled:

Heartbeat
| where Category == 'Direct Agent' or Category contains 'SCOM'
| distinct Computer
| join kind=fullouter (
InsightsMetrics
| distinct Computer
| join kind = fullouter (VMConnection | distinct Computer) on Computer
| extend ['Guest performance'] = iif(Computer != '', true, false)
| extend ['Processes and dependencies (Map)'] = iif(Computer1 != '', true, false)
| extend Computer = iif(Computer == '',Computer1, Computer)
| project-away Computer1
) on Computer
| where Computer != ''
| project-away Computer1
| order by Computer desc

Identify what event logs and performance counters the legacy agent’s collects

To identify which Event logs, Syslog, Performance counters and IIS are being collected review the corresponding tabs in Log Analytics Workspace > Classic > Legacy agents management.

To find out more about the computers from which the IIS logs are gathered, run the following KQL query.

W3CIISLog
| distinct Computer

To identify whether custom logs are collected go to Log Analytics Workspace > Settings > Tables and document any entries of type Custom table (classic). To Identify from which computers custom logs are collected run the following KQL query for each Custom Table:

TableName_CL
| distinct Computer

To find out which computers have Change Tracking enabled, execute the following KQL query:

ConfigurationData
| distinct Computer

Document which legacy agents are set up as Hybrid Workers within Automation Accounts

Agent-based (V1) Hybrid Runbook Workers rely on the Log Analytics agent reporting to an Azure Monitor Log Analytics workspace. To discover the Hybrid Workers running the V1 configuration review the automation account information Automation Accounts > Process Automation > Hybrid worker groups.

Update Azure Landing Zones

Caution

This script intended for Azure Landing Zone Portal Accelerator deployments only. It is not for Terraform and Bicep deployments of ALZ.

IMPORTANT: THIS SCRIPT WILL DEPLOY, UNASSIGN AND REMOVE RESOURCES! We recommend that you have carefully assessed your current state and followed the guidance from both the Azure Landing Zones documentation and the public documentation that it references. Use the -WhatIf parameter to see what the changes will do before you apply them.

  1. Start PowerShell
  2. Clone the Enterprise-Scale repository

    git clone https://github.com/Azure/Enterprise-Scale.git

  3. Change directory

    cd .\Enterprise-Scale\

  4. Login to Azure:

    Login-AzAccount

  5. Select your management subscription

    Select-AzSubscription -Subscription {subscriptionId}

Tip

We highly recommend running the script with -WhatIf to see what the changes will do before you apply them.

To run the script with -WhatIf

Set the correct values for:

  • -location
  • -eslzRoot
  • -managementResourceGroupName
  • -workspaceResourceId
  • -workspaceRegion
.\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}" -workspaceRegion "northeurope" -migrationPath MMAToAMA -DeployUserAssignedManagedIdentity -DeployVMInsights -DeployChangeTracking -DeployMDfCDefenderSQL -DeployAzureUpdateManager -RemoveLegacyPolicyAssignments -RemoveLegacySolutions -UpdatePolicyDefinitions -WhatIf

Example result of running the ALZ MMA to AMA migration with -WhatIf

Animated image showing the result of running the AMA Migration script with -WhatIf parameter

Migrate to AMA

Set the correct values for:

  • -location
  • -eslzRoot
  • -managementResourceGroupName
  • -workspaceResourceId
  • -workspaceRegion

Tip

You don't have to update everything at once. Use the switches like -DeployVMInsights to update specific features.

.\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}" -workspaceRegion "northeurope" -migrationPath MMAToAMA -DeployUserAssignedManagedIdentity -DeployVMInsights -DeployChangeTracking -DeployMDfCDefenderSQL -DeployAzureUpdateManager -RemoveLegacyPolicyAssignments -RemoveLegacySolutions -UpdatePolicyDefinitions

Example result of running the ALZ MMA to AMA migration

Animated image showing the result of running the AMA Migration script

Remediate Policies

The script can be used to remediate the newly assigned policies. Before running the remediations please wait for the Policy Engine to process the compliance state for the new assignments (alternatively you can use Start-AzPolicyComplianceScan)

Set the correct values for:

  • -location
  • -eslzRoot
  • -managementResourceGroupName
  • -workspaceResourceId
  • -workspaceRegion
.\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}" -workspaceRegion "northeurope" -migrationPath MMAToAMA -RemediatePolicies

Removing MMA and additional steps

Depending on your situation and the outcome of your evaluation of the current state, you may require additional steps.

1. Configure additional Data collection Rules

To collect performance counters, IIS logs, syslog or custom logs, you can use DCR Config Generator. It creates data collection rules for different platforms by analyzing your workspace's Log Analytics agent configuration. Installing and using DCR Config Generator

2. Microsoft Sentinel

For additional steps to configure connectors to send events via AMA, please see: Migrate to the Azure Monitor agent (AMA) from the Log Analytics agent (MMA/OMS) for Microsoft Sentinel

3. Non-Azure VMs

To install AMA on Hybrid VMs, you need to add these VMs to Azure Arc first. Please follow this guide: Plan and deploy Azure Arc-enabled servers - Azure Arc

4. Hybrid Workers

Follow the link below to update your Hybrid Workers (V1) to Extension based Hybrid Workers (V2): Deploy an extension-based Windows or Linux User Hybrid Runbook Worker in Azure Automation

5. Change Tracking

If you have changed the settings for Change Tracking data types, review the following guide for migration options: Migration guidance from Change Tracking and inventory using Log Analytics to Change Tracking and inventory using Azure Monitoring Agent version

6. Azure Update Manager

If you require to migrate additional configurations like schedules, please review: Move from Automation Update Management to Azure Update Manager

7. Removing MMA Agent

After you migrate your machines to the Azure Monitor Agent (AMA), you need to remove the Log Analytics Agent (also called the Microsoft Management Agent or MMA) to avoid duplication of logs.

Important

For more information on running both agents on the same Machine please review the considerations provided here: Before you begin

The Azure Tenant Security Solution (AzTS) MMA Discovery and Removal Utility provided by the Azure Monitor team can centrally remove the MMA extension from Azure virtual machines (VMs), Azure virtual machine scale sets, and Azure Arc servers from a tenant. MMA Discovery and Removal Utility - Azure Monitor

Update to latest AMA release

Caution

This script intended for Azure Landing Zone Portal Accelerator deployments only. It is not for Terraform and Bicep deployments of ALZ.

IMPORTANT: THIS SCRIPT WILL DEPLOY, UNASSIGN AND REMOVE RESOURCES! We recommend that you have carefully assessed your current state and followed the guidance from both the Azure Landing Zones documentation and the public documentation that it references. Use the -WhatIf parameter to see what the changes will do before you apply them.

  1. Start PowerShell
  2. Clone the Enterprise-Scale repository

    git clone https://github.com/Azure/Enterprise-Scale.git

  3. Change directory

    cd .\Enterprise-Scale\

  4. Login to Azure:

    Login-AzAccount

  5. Select your management subscription

    Select-AzSubscription -Subscription {subscriptionId}

Tip

We highly recommend running the script with -WhatIf to see what the changes will do before you apply them.

To run the update with -WhatIf

Set the correct values for:

  • -location
  • -eslzRoot
  • -managementResourceGroupName
  • -workspaceResourceId
  • -workspaceRegion
.\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}" -workspaceRegion "northeurope" -migrationPath UpdateAMA -UpdatePolicyDefinitions -removeLegacyPolicyAssignments -deployUserAssignedManagedIdentity -deployVMInsights -deployChangeTracking -deployMDfCDefenderSQL -WhatIf

Example result of running the ALZ AMA update with -WhatIf

Animated image showing the result of running the AMA Update script with -WhatIf parameter

Update AMA

Set the correct values for:

  • -location
  • -eslzRoot
  • -managementResourceGroupName
  • -workspaceResourceId
  • -workspaceRegion

Tip

You don't have to update everything at once. Use the switches like -DeployVMInsights to update specific features.

.\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}" -workspaceRegion "northeurope" -migrationPath UpdateAMA -UpdatePolicyDefinitions -removeLegacyPolicyAssignments -deployUserAssignedManagedIdentity -deployVMInsights -deployChangeTracking -deployMDfCDefenderSQL

Example result of running the ALZ AMA update

Animated image showing the result of running the AMA Update script

Remediate modified policy assignments

The script can be used to remediate the newly/updated assigned policies. Before running the remediations please wait for the Policy Engine to process the compliance state for the new assignments (alternatively you can use Start-AzPolicyComplianceScan)

Set the correct values for:

  • -location
  • -eslzRoot
  • -managementResourceGroupName
  • -workspaceResourceId
  • -workspaceRegion
.\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}" -workspaceRegion "northeurope" -migrationPath UpdateAMA -RemediatePolicies

Remove obsolete User Assigned Managed Identities

The User Assigned Managed Identity has been centralized within the management resource group. It's no longer necessary to have a User Assigned Managed Identity deployed across individual subscriptions, and these should be removed. Executing the following command will remove the User Assigned Managed Identity from every subscription and, if the resource group is doesn’t contain other resources, it will be removed as well.

Set the correct values for:

  • -location
  • -eslzRoot
  • -managementResourceGroupName
  • -workspaceResourceId
  • -workspaceRegion
.\src\scripts\Update-AzureLandingZonesToAMA.ps1 -location "northeurope" -eslzRoot "contoso" -managementResourceGroupName "contoso-mgmt" -workspaceResourceId "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}" -workspaceRegion "northeurope" -migrationPath UpdateAMA -removeObsoleteUAMI

This wiki is being actively developed

If you discover any documentation bugs or would like to request new content, please raise them as an issue.

Contributions to this wiki are done through the main repo under docs/wiki.

Wiki content

Clone this wiki locally