Povratne informacije Uredi

Manage the Azure Monitor agent

  • Članak
  • 11 min. za čitanje

This article provides the different options currently available to install, uninstall and update the Azure Monitor agent. This agent extension can be installed on Azure virtual machines, scale sets and Azure Arc-enabled servers. It also lists the options to create associations with data collection rules that define which data the agent should collect. Installing, upgrading, or uninstalling the Azure Monitor Agent will not require you to restart your server.

Virtual machine extension details

The Azure Monitor agent is implemented as an Azure VM extension with the details in the following table. It can be installed using any of the methods to install virtual machine extensions including those described in this article.

Property Windows Linux
Publisher Microsoft.Azure.Monitor Microsoft.Azure.Monitor
Type AzureMonitorWindowsAgent AzureMonitorLinuxAgent
TypeHandlerVersion See Azure Monitor Agent extension versions Azure Monitor Agent extension versions

Extension versions

View Azure Monitor Agent extension versions.

Prerequisites

The following prerequisites must be met prior to installing the Azure Monitor agent.

  • Permissions: For methods other than Azure portal, you must have the following role assignments to install the agent:

    Built-in Role Scope(s) Reason
    • Virtual machines, scale sets
    • Arc-enabled servers
    		 To deploy the agent
    Any role that includes the action Microsoft.Resources/deployments/*
    • Subscription and/or
    • Resource group and/or
    		To deploy ARM templates

  • Non-Azure: For installing the agent on physical servers and virtual machines hosted outside of Azure (i.e. on-premises) or in other clouds, you must install the Azure Arc Connected Machine agent first (at no added cost)

  • Authentication: Managed identity must be enabled on Azure virtual machines. Both system-assigned and user-assigned managed identities are supported.

    • User-assigned: This is recommended for large-scale deployments, configurable via built-in Azure policies. You can create a user-assigned managed identity once and share it across multiple VMs, and is thus more scalable than a system-assigned managed identity. If you use a user-assigned managed identity, you must pass the managed identity details to Azure Monitor Agent via extension settings: 
      {
  "authentication": {
    "managedIdentity": {
      "identifier-name": "mi_res_id" or "object_id" or "client_id",
      "identifier-value": "<resource-id-of-uai>" or "<guid-object-or-client-id>"
    }
  }
}
      We recommend using mi_res_id as the identifier-name. The sample commands below only show usage with mi_res_id for the sake of brevity. For more details on mi_res_id, object_id, and client_id, see the managed identity documentation.
    • System-assigned: This is suited for initial testing or small deployments. When used at scale (for example, for all VMs in a subscription) it results in substantial number of identities created (and deleted) in Azure AD (Azure Active Directory). To avoid this churn of identities, it is recommended to use user-assigned managed identities instead. For Arc-enabled servers, system-assigned managed identity is enabled automatically (as soon as you install the Arc agent) as it's the only supported type for Arc-enabled servers.
    • This is not required for Azure Arc-enabled servers. The system identity will be enabled automatically if the agent is installed via creating and assigning a data collection rule using the Azure portal.

  • Networking: If using network firewalls, the AzureResourceManager service tag must be enabled on the virtual network for the virtual machine. Additionally, the virtual machine must have access to the following HTTPS endpoints:

    • global.handler.control.monitor.azure.com
    • <virtual-machine-region-name>.handler.control.monitor.azure.com (example: westus.handler.control.azure.com)
    • <log-analytics-workspace-id>.ods.opinsights.azure.com (example: 12345a01-b1cd-1234-e1f2-1234567g8h99.ods.opsinsights.azure.com)
      (If using private links on the agent, you must also add the dce endpoints)

Note

This article only pertains to agent installation or management. After you install the agent, you must review the next article to configure data collection rules and associate them with the machines with agents installed.
The Azure Monitor agents cannot function without being associated with data collection rules.

Using the Azure portal

Install

To install the Azure Monitor agent using the Azure portal, follow the process to create a data collection rule in the Azure portal. This not only creates the rule, but it also associates it to the selected resources and installs the Azure Monitor agent on them if not already installed.

Uninstall

To uninstall the Azure Monitor agent using the Azure portal, navigate to your virtual machine, scale set or Arc-enabled server, select the Extensions tab and click on AzureMonitorWindowsAgent or AzureMonitorLinuxAgent. In the dialog that pops up, click Uninstall.

Update

To perform a one time update of the agent, you must first uninstall the existing agent version and then install the new version as described above.
The recommendation is to enable automatic update of the agent by enabling the Automatic Extension Upgrade feature. Navigate to your virtual machine or scale set, select the Extensions tab and click on AzureMonitorWindowsAgent or AzureMonitorLinuxAgent. In the dialog that pops up, click Enable automatic upgrade.

Using Resource Manager templates

Install

You can use Resource Manager templates to install the Azure Monitor agent on Azure virtual machines and on Azure Arc-enabled servers and to create an association with data collection rules. You must create any data collection rule prior to creating the association.

Get sample templates for installing the agent and creating the association from the following:

Install the templates using any deployment method for Resource Manager templates such as the following commands.

New-AzResourceGroupDeployment -ResourceGroupName "<resource-group-name>" -TemplateFile "<template-filename.json>" -TemplateParameterFile "<parameter-filename.json>"

Using PowerShell

You can install the Azure Monitor agent on Azure virtual machines and on Azure Arc-enabled servers using the PowerShell command for adding a virtual machine extension.

Install on Azure virtual machines

Use the following PowerShell commands to install the Azure Monitor agent on Azure virtual machines. Choose the appropriate command based on your chosen authentication method.

User-assigned managed identity

Set-AzVMExtension -Name AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion <version-number> -SettingString '{"authentication":{"managedIdentity":{"identifier-name":"mi_res_id","identifier-value":/subscriptions/<my-subscription-id>/resourceGroups/<my-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<my-user-assigned-identity>"}}}'

System-assigned managed identity

Set-AzVMExtension -Name AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion <version-number>

Uninstall on Azure virtual machines

Use the following PowerShell commands to install the Azure Monitor agent on Azure virtual machines.

Remove-AzVMExtension -Name AzureMonitorWindowsAgent -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name>

Update on Azure virtual machines

To perform a one time update of the agent, you must first uninstall the existing agent version and then install the new version as described above.
The recommendation is to enable automatic update of the agent by enabling the Automatic Extension Upgrade feature, using the following PowerShell commands.

Set-AzVMExtension -ExtensionName AzureMonitorWindowsAgent -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Publisher Microsoft.Azure.Monitor -ExtensionType AzureMonitorWindowsAgent -TypeHandlerVersion <version-number> -Location <location> -EnableAutomaticUpgrade $true

Install on Azure Arc-enabled servers

Use the following PowerShell commands to install the Azure Monitor agent on Azure Arc-enabled servers.

New-AzConnectedMachineExtension -Name AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -MachineName <arc-server-name> -Location <arc-server-location>

Uninstall on Azure Arc-enabled servers

Use the following PowerShell commands to install the Azure Monitor agent on Azure Arc-enabled servers.

Remove-AzConnectedMachineExtension -MachineName <arc-server-name> -ResourceGroupName <resource-group-name> -Name AzureMonitorWindowsAgent

Upgrade on Azure Arc-enabled servers

To perform a one time upgrade of the agent, use the following PowerShell commands:

$target = @{"Microsoft.Azure.Monitor.AzureMonitorWindowsAgent" = @{"targetVersion"=<target-version-number>}}
Update-AzConnectedExtension -ResourceGroupName $env.ResourceGroupName -MachineName <arc-server-name> -ExtensionTarget $target

The recommendation is to enable automatic update of the agent by enabling the Automatic Extension Upgrade (preview) feature, using the following PowerShell commands.

Update-AzConnectedMachineExtension -ResourceGroup <resource-group-name> -MachineName <arc-server-name> -Name AzureMonitorWindowsAgent -EnableAutomaticUpgrade

Using Azure CLI

You can install the Azure Monitor agent on Azure virtual machines and on Azure Arc-enabled servers using the Azure CLI command for adding a virtual machine extension.

Install on Azure virtual machines

Use the following CLI commands to install the Azure Monitor agent on Azure virtual machines. Choose the appropriate command based on your chosen authentication method.

User-assigned managed identity

az vm extension set --name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --ids <vm-resource-id> --settings '{"authentication":{"managedIdentity":{"identifier-name":"mi_res_id","identifier-value":/subscriptions/<my-subscription-id>/resourceGroups/<my-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<my-user-assigned-identity>"}}}'

System-assigned managed identity

az vm extension set --name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --ids <vm-resource-id>

Uninstall on Azure virtual machines

Use the following CLI commands to install the Azure Monitor agent on Azure virtual machines.

az vm extension delete --resource-group <resource-group-name> --vm-name <virtual-machine-name> -name AzureMonitorWindowsAgent

Update on Azure virtual machines

To perform a one time update of the agent, you must first uninstall the existing agent version and then install the new version as described above.
The recommendation is to enable automatic update of the agent by enabling the Automatic Extension Upgrade feature, using the following CLI commands.

az vm extension set -name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --vm-name <virtual-machine-name> --resource-group <resource-group-name> --enable-auto-upgrade true

Install on Azure Arc-enabled servers

Use the following CLI commands to install the Azure Monitor agent onAzure Azure Arc-enabled servers.

az connectedmachine extension create --name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --type AzureMonitorWindowsAgent --machine-name <arc-server-name> --resource-group <resource-group-name> --location <arc-server-location>

Uninstall on Azure Arc-enabled servers

Use the following CLI commands to install the Azure Monitor agent onAzure Azure Arc-enabled servers.

az connectedmachine extension delete --name AzureMonitorWindowsAgent --machine-name <arc-server-name> --resource-group <resource-group-name>

Upgrade on Azure Arc-enabled servers

To perform a one time upgrade of the agent, use the following CLI commands:

az connectedmachine upgrade-extension --extension-targets "{\"Microsoft.Azure.Monitor.AzureMonitorWindowsAgent\":{\"targetVersion\":\"<target-version-number>\"}}" --machine-name <arc-server-name> --resource-group <resource-group-name>

The recommendation is to enable automatic update of the agent by enabling the Automatic Extension Upgrade (preview) feature, using the following PowerShell commands.

az connectedmachine extension update --name AzureMonitorWindowsAgent --machine-name <arc-server-name> --resource-group <resource-group-name> --enable-auto-upgrade true

Using Azure Policy

Use the following policies and policy initiatives to automatically install the agent and associate it with a data collection rule, every time you create a virtual machine, scale set, or Arc-enabled server.

Note

As per Microsoft Identity best practices, policies for installing Azure Monitor agent on virtual machines and scale-sets rely on user-assigned managed identity. This is the more scalable and resilient managed identity options for these resources.
For Arc-enabled servers, policies rely on only system-assigned managed identity as the only supported option today.

Built-in policy initiatives

Before proceeding, review prerequisites for agent installation.

Policy initiatives for Windows and Linux virtual machines, scale-sets consist of individual policies that:

  • (Optional) Create and assign built-in user-assigned managed identity, per subscription, per region. Learn more.
    • Bring Your Own User-Assigned Identity: If set of true, it creates the built-in user-assigned managed identity in the predefined resource group, and assigns it to all machines that the policy is applied to. If set to false, you can instead use existing user-assigned identity that you must assign to the machines beforehand.
  • Install the Azure Monitor agent extension on the machine, and configure it to use user-assigned identity as specified by the parameters below
    • Bring Your Own User-Assigned Managed Identity: If set to false, it configures the agent to use the built-in user-assigned managed identity created by the policy above. If set to true, it configures the agent to use an existing user-assigned identity that you must assign to the machine(s) in scope beforehand.
    • User-Assigned Managed Identity Name: If using your own identity (selected true), specify the name of the identity that's assigned to the machine(s)
    • User-Assigned Managed Identity Resource Group: If using your own identity (selected true), specify the resource group where the identity exists
    • Additional Virtual Machine Images: Pass additional VM image names that you want to apply the policy to, if not already included
  • Create and deploy the association to link the machine to specified data collection rule.
    • Data Collection Rule Resource Id: The ARM resourceId of the rule you want to associate via this policy, to all machines the policy is applied to.

Partial screenshot from the Azure Policy Definitions page showing two built-in policy initiatives for configuring the Azure Monitor agent.

Known issues:

  • Managed Identity default behavior: Learn more
  • Possible race condition with using built-in user-assigned identity creation policy above. Learn more
  • Assigning policy to resource groups: If the assignment scope of the policy is a resource group and not a subscription, the identity used by policy assignment (different from the user-assigned identity used by agent) must be manually granted these roles prior to assignment/remediation. Failing to do this will result in deployment failures.
  • Other Managed Identity limitations

Built-in policies

You can choose to use the individual policies from the policy initiative above to perform a single action at scale. For example, if you only want to automatically install the agent, use the second agent installation policy from the initiative as shown below.

Partial screenshot from the Azure Policy Definitions page showing policies contained within the initiative for configuring the Azure Monitor agent.

Remediation

The initiatives or policies will apply to each virtual machine as it's created. A remediation task deploys the policy definitions in the initiative to existing resources, so you can configure the Azure Monitor agent for any resources that were already created.

When you create the assignment by using the Azure portal, you have the option of creating a remediation task at the same time. See Remediate non-compliant resources with Azure Policy for details on the remediation.

Screenshot that shows initiative remediation for the Azure Monitor agent.

Next steps