MMA Discovery and Removal Utility
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. The Azure Tenant Security Solution (AzTS) MMA Discovery and Removal Utility can centrally remove the MMA extension from Azure virtual machines (VMs), Azure virtual machine scale sets, and Azure Arc servers from a tenant.
Note
This utility is used to discover and remove MMA extensions. This will not remove OMS extensions, OMS will need to be removed manually by running the purge script here: Purge the Linux Agent
The utility works in two steps:
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.
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.
Prerequisites
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.
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:
Go to the AzTS-docs GitHub repository. Download the deployment package file, AzTSMMARemovalUtilityDeploymentFiles.zip, to your local machine.
Extract the .zip file to your local folder location.
Unblock the files by using this script:
Get-ChildItem -Path "<Extracted folder path>" -Recurse | Unblock-File
Set up the utility
Go to the deployment folder and load the consolidated setup script. You must have Owner access on the subscription.
CD "<LocalExtractedFolderPath>\AzTSMMARemovalUtilityDeploymentFiles" . ".\MMARemovalUtilityConsolidatedSetup.ps1"
Sign in to the Azure account by using the following PowerShell command:
$TenantId = "<TenantId>" Connect-AzAccount -Tenant $TenantId
Run the setup script to perform the following operations:
- Install required Az 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. Default value is AzTS-MMARemovalUtility-Host-RG
.No Location
Location domain controller where the setup is created. Default value is EastUS2
.No AzureEnvironmentName
Azure environment where the solution is installed: AzureCloud
orAzureGovernmentCloud
. Default value isAzureCloud
.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 ) |
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for