Use Azure Policy to install and manage the Azure Monitor agent

Using Azure Policy, you can have the Azure Monitor agent automatically installed on your existing and new virtual machines and have the appropriate DCRs automatically associated with them. This article describes the built-in policies and initiatives that you can leverage for this functionality and features of Azure Monitor to assist in managing them.

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 Azure Arc-enabled server.

Note

Azure Monitor has a preview data collection rule DCR experience that simplifies creating assignments for policies and initiatives that use DCRs. This includes initiatives that install the Azure Monitor agent. You may choose to use that experience to create assignments for the initiatives described in this article. See Manage data collection rules (DCRs) and associations in Azure Monitor for more information.

Prerequisites

Before you proceed, review prerequisites for agent installation.

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 option is the more scalable and resilient managed identity for these resources. For Azure Arc-enabled servers, policies rely on system-assigned managed identity as the only supported option today.

Built-in policies

You can choose to use the individual policies from the preceding policy initiative 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.

Partial screenshot from the Azure Policy Definitions page that shows policies contained within the initiative for configuring Azure Monitor Agent.

Built-in policy initiatives

There are built-in policy initiatives for Windows and Linux virtual machines, scale sets that provide at-scale onboarding using Azure Monitor agents end-to-end

Note

The policy definitions only include the list of Windows and Linux versions that Azure supports. To add a custom image, use the Additional Virtual Machine Images parameter.

These initiatives above comprise 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 to false, it creates the built-in user-assigned managed identity in the predefined resource group and assigns it to all the machines that the policy is applied to. Location of the resource group can be configured in the Built-In-Identity-RG Location parameter. If set to true, you can instead use an existing user-assigned identity that is automatically assigned to all the machines that the policy is applied to.
  • Install Azure Monitor Agent extension on the machine, and configure it to use user-assigned identity as specified by the following parameters.

    • 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 preceding policy. If set to true, it configures the agent to use an existing user-assigned identity.
    • User-Assigned Managed Identity Name: If you use your own identity (selected true), specify the name of the identity that's assigned to the machines.
    • User-Assigned Managed Identity Resource Group: If you use 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.
    • Built-In-Identity-RG Location: If you use built-in user-assigned managed identity, specify the location where the identity and the resource group should be created. This parameter is only used when Bring Your Own User-Assigned Managed Identity parameter is set to false.
  • Create and deploy the association to link the machine to specified data collection rule.

    • Data Collection Rule Resource Id: The Azure Resource Manager 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 that shows two built-in policy initiatives for configuring Azure Monitor Agent.

Known issues

  • Managed Identity default behavior. Learn more.
  • Possible race condition with using built-in user-assigned identity creation policy. 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 step will result in deployment failures.
  • Other Managed Identity limitations.

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 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. For information on the remediation, see Remediate non-compliant resources with Azure Policy.

Screenshot that shows initiative remediation for Azure Monitor Agent.

Next steps

Create a data collection rule to collect data from the agent and send it to Azure Monitor.