MMA Discovery and Removal Utility


We have received many reports from customers that this tool is failing to remove MMA agents. At this time, we recommend that this tool not be used.

After you migrate your machines to the Azure Monitor Agent (AMA), remove the Log Analytics or Microsoft Management Agent (MMA) to avoid duplication of logs. The Azure Tenant Security Solution (AzTS) MMA Discovery and Removal Utility can remove the MMA extension from Azure Virtual Machines (VMs), Azure Virtual Machine Scale Sets (VMSSs), and Azure Arc servers from a tenant.


This utility is used to discover and remove MMA extensions. It doesn't remove OMS extensions. OMS must be removed manually by running the purge script. For mor information, see Purge the Linux Agent

The utility works in two steps:

  1. Discovery: The utility creates an inventory of all machines that have the MMA installed. We recommend that you don't create any new VMs, virtual machine scale sets, or Azure Arc servers with the MMA extension while the utility is running.

  2. Removal: The utility selects machines that have both the MMA and the AMA and removes the MMA extension. You can disable this step and run it after you validate the list of machines. There's an option to remove the extension from machines that have only the MMA, but we recommend that you first migrate all dependencies to the AMA and then remove the MMA.


Do all the setup steps in Visual Studio Code with the PowerShell extension. You need:

  • Windows 10 or later, or Windows Server 2019 or later.
  • PowerShell 5.0 or later. Check the version by running $PSVersionTable.
  • PowerShell. The language must be set to FullLanguage mode. Check the mode by running $ExecutionContext.SessionState.LanguageMode in PowerShell. For more information, see the PowerShell reference.
  • Bicep. The setup scripts use Bicep to automate the installation. Check the installation by running bicep --version. For more information, see Install Bicep tools.
  • A user-assigned managed identity that has Reader, Virtual Machine Contributor, and Azure Arc ScVmm VM Contributor access on target scopes.
  • A new resource group to contain all the Azure resources that the setup automation creates automatically.
  • Appropriate permission on the configured scopes. To grant the remediation user-assigned managed identity with the previously mentioned roles on the target scopes, you must have User Access Administrator or Owner permission. For example, if you're configuring the setup for a particular subscription, you must have the User Access Administrator role assignment on that subscription so that the script can provide the permissions for the remediation user-assigned managed identity.

Resources created

The removal tool creates a resource group and resources to manage the removal of agents. Some of these resources may have an Azure cost.

Download the deployment package

The deployment package contains:

  • Bicep templates, which contain resource configuration details that you create as part of setup.
  • Deployment setup scripts, which provide the cmdlet to run the installation.

To install the package:

  1. Go to the AzTS-docs GitHub repository. Download the deployment package file,, to your local machine.

  2. Extract the zip file to your local folder location.

  3. Unblock the files by using this script:

    Get-ChildItem -Path "<Extracted folder path>" -Recurse | Unblock-File 

Set up the utility

  1. Go to the deployment folder and load the consolidated setup script. You must have Owner access on the subscription.

    CD "<LocalExtractedFolderPath>\AzTSMMARemovalUtilityDeploymentFiles"
    . ".\MMARemovalUtilityConsolidatedSetup.ps1"
  2. Sign in to the Azure account by using the following PowerShell command:

    $TenantId = "<TenantId>"
    Connect-AzAccount -Tenant $TenantId
  3. Run the setup script to perform the following operations:

    • Install required Az PowerShell modules.
    • Set up the remediation user-assigned managed identity.
    • Prompt and collect onboarding details for usage telemetry collection based on user preference.
    • Create or update the resource group.
    • Create or update the resources with assigned managed identities.
    • Create or update the monitoring dashboard.
    • Configure target scopes.
    $SetupInstallation = Install-AzTSMMARemovalUtilitySolutionConsolidated `
             -RemediationIdentityHostSubId <MIHostingSubId> `
             -RemediationIdentityHostRGName <MIHostingRGName> `
             -RemediationIdentityName <MIName> `
             -TargetSubscriptionIds @("<SubId1>","<SubId2>","<SubId3>") `
             -TargetManagementGroupNames @("<MGName1>","<MGName2>","<MGName3>") `
             -TenantScope `
             -SubscriptionId <HostingSubId> `
             -HostRGName <HostingRGName> `
             -Location <Location> `
             -AzureEnvironmentName <AzureEnvironmentName>

    The script contains these parameters:

    Parameter name Description Required
    RemediationIdentityHostSubId Subscription ID to create remediation resources. Yes
    RemediationIdentityHostRGName New resource group name to create remediation. Defaults to AzTS-MMARemovalUtility-RG. No
    RemediationIdentityName Name of the remediation managed identity. Yes
    TargetSubscriptionIds List of target subscription IDs to run on. No
    TargetManagementGroupNames List of target management group names to run on. No
    TenantScope Tenant scope for assigning roles via your tenant ID. No
    SubscriptionId ID of the subscription where the setup is installed. Yes
    HostRGName Name of the new resource group where the remediation managed identity is created. Defaults to AzTS-MMARemovalUtility-Host-RG. No
    Location Location domain controller where the setup is created. Defaults to EastUS2. No
    AzureEnvironmentName Azure environment where the solution is installed: AzureCloud or AzureGovernmentCloud. Defaults to AzureCloud. No

Run the utility

Update-AzTSMMARemovalUtilityDiscoveryTrigger ` 
    -SubscriptionId <HostingSubId> `
    -ResourceGroupName <HostingRGName> `
    -StartScopeResolverAfterMinutes 60 `
    -StartExtensionDiscoveryAfterMinutes 30 

The script contains these parameters:

Parameter name Description Required
SubscriptionId ID of the subscription where you installed the utility. Yes
ResourceGroupName Name of the resource group where you installed the utility. Yes
StartScopeResolverAfterMinutes Time, in minutes, to wait before running the resolver. Yes (mutually exclusive with -StartScopeResolverImmediately)
StartScopeResolverImmediately Indicator to run the resolver immediately. Yes (mutually exclusive with -StartScopeResolverAfterMinutes)
StartExtensionDiscoveryAfterMinutes Time, in minutes, to wait to run discovery (should be after the resolver is done). Yes (mutually exclusive with -StartExtensionDiscoveryImmediatley)
StartExtensionDiscoveryImmediatley Indicator to run extension discovery immediately. Yes (mutually exclusive with -StartExtensionDiscoveryAfterMinutes)