How to onboard Azure Monitor for containers

Note

This article has been updated to use the new Azure PowerShell Az module. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For installation instructions, see Install Azure PowerShell.

This article describes how to set up Azure Monitor for containers to monitor the performance of workloads that are deployed to Kubernetes environments and hosted on Azure Kubernetes Service.

Azure Monitor for containers can be enabled for new, or one or more existing deployments of AKS using the following supported methods:

Prerequisites

Before you start, make sure that you have the following:

  • A Log Analytics workspace. You can create it when you enable monitoring of your new AKS cluster or let the onboarding experience create a default workspace in the default resource group of the AKS cluster subscription. If you chose to create it yourself, you can create it through Azure Resource Manager, through PowerShell, or in the Azure portal.
  • You are a member of the Log Analytics contributor role to enable container monitoring. For more information about how to control access to a Log Analytics workspace, see Manage workspaces.

Note

As part of the ongoing transition from Microsoft Operations Management Suite (OMS) to Azure Monitor, the OMS Agent for Windows or Linux will be referred to as the Log Analytics agent for Windows and Log Analytics agent for Linux.

Components

Your ability to monitor performance relies on a containerized Log Analytics agent for Linux specifically developed for Azure Monitor for containers. This specialized agent collects performance and event data from all nodes in the cluster, and the agent is automatically deployed and registered with the specified Log Analytics workspace during deployment. The agent version is microsoft/oms:ciprod04202018 or later, and is represented by a date in the following format: mmddyyyy.

When a new version of the agent is released, it is automatically upgraded on your managed Kubernetes clusters hosted on Azure Kubernetes Service (AKS). To follow the versions released, see agent release announcements.

Note

If you have already deployed an AKS cluster, you enable monitoring by using either Azure CLI or a provided Azure Resource Manager template, as demonstrated later in this article. You cannot use kubectl to upgrade, delete, re-deploy, or deploy the agent. The template needs to be deployed in the same resource group as the cluster.”

Sign in to the Azure portal

Sign in to the Azure portal.

Enable monitoring for a new cluster

During deployment, you can enable monitoring of a new AKS cluster in the Azure portal, with Azure CLI, or with Terraform. Follow the steps in the quickstart article Deploy an Azure Kubernetes Service (AKS) cluster if you want to enable from the portal. On the Monitoring page, for the Enable Monitoring option, select Yes, and then select an existing Log Analytics workspace or create a new one.

Enable using Azure CLI

To enable monitoring of a new AKS cluster created with Azure CLI, follow the step in the quickstart article under the section Create AKS cluster.

Note

If you choose to use the Azure CLI, you first need to install and use the CLI locally. You must be running the Azure CLI version 2.0.43 or later. To identify your version, run az --version. If you need to install or upgrade the Azure CLI, see Install the Azure CLI.

Enable using Terraform

If you are deploying a new AKS cluster using Terraform, you specify the arguments required in the profile to create a Log Analytics workspace if you do not chose to specify an existing one.

Note

If you choose to use Terraform, you must be running the Terraform Azure RM Provider version 1.17.0 or above.

To add Azure Monitor for containers to the workspace, see azurerm_log_analytics_solution and complete the profile by including the addon_profile and specify oms_agent.

After you've enabled monitoring and all configuration tasks are completed successfully, you can monitor the performance of your cluster in either of two ways:

  • Directly in the AKS cluster by selecting Health in the left pane.

  • By selecting the Monitor Container insights tile in the AKS cluster page for the selected cluster. In Azure Monitor, in the left pane, select Health.

    Options for selecting Azure Monitor for containers in AKS

After you've enabled monitoring, it might take about 15 minutes before you can view health metrics for the cluster.

Enable monitoring for existing managed clusters

You can enable monitoring of an AKS cluster that's already deployed either using Azure CLI, from the portal, or with the provided Azure Resource Manager template by using the PowerShell cmdlet New-AzResourceGroupDeployment.

Enable monitoring using Azure CLI

The following step enables monitoring of your AKS cluster using Azure CLI. In this example, you are not required to per-create or specify an existing workspace. This command simplifies the process for you by creating a default workspace in the default resource group of the AKS cluster subscription if one does not already exist in the region. The default workspace created resembles the format of DefaultWorkspace-<GUID>-<Region>.

az aks enable-addons -a monitoring -n MyExistingManagedCluster -g MyExistingManagedClusterRG  

The output will resemble the following:

provisioningState       : Succeeded

If you would rather integrate with an existing workspace, use the following command to specify that workspace.

az aks enable-addons -a monitoring -n MyExistingManagedCluster -g MyExistingManagedClusterRG --workspace-resource-id <ExistingWorkspaceResourceID> 

The output will resemble the following:

provisioningState       : Succeeded

Enable monitoring using Terraform

  1. Add the oms_agent add-on profile to the existing azurerm_kubernetes_cluster resource

    addon_profile {
     oms_agent {
       enabled                    = true
       log_analytics_workspace_id = "${azurerm_log_analytics_workspace.test.id}"
      }
    }
    
  2. Add the azurerm_log_analytics_solution following the steps in the Terraform documentation.

Enable monitoring from Azure Monitor in the portal

To enable monitoring of your AKS cluster in the Azure portal from Azure Monitor, do the following:

  1. In the Azure portal, select Monitor.

  2. Select Containers from the list.

  3. On the Monitor - containers page, select Non-monitored clusters.

  4. From the list of non-monitored clusters, find the container in the list and click Enable.

  5. On the Onboarding to Azure Monitor for containers page, if you have an existing Log Analytics workspace in the same subscription as the cluster, select it from the drop-down list.
    The list preselects the default workspace and location that the AKS container is deployed to in the subscription.

    Enable AKS Container insights monitoring

    Note

    If you want to create a new Log Analytics workspace for storing the monitoring data from the cluster, follow the instructions in Create a Log Analytics workspace. Be sure to create the workspace in the same subscription that the AKS container is deployed to.

After you've enabled monitoring, it might take about 15 minutes before you can view health metrics for the cluster.

Enable monitoring from AKS cluster in the portal

To enable monitoring of your AKS container in the Azure portal, do the following:

  1. In the Azure portal, select All services.

  2. In the list of resources, begin typing Containers.
    The list filters based on your input.

  3. Select Kubernetes services.

    The Kubernetes services link

  4. In the list of containers, select a container.

  5. On the container overview page, select Monitor Containers.

  6. On the Onboarding to Azure Monitor for containers page, if you have an existing Log Analytics workspace in the same subscription as the cluster, select it in the drop-down list.
    The list preselects the default workspace and location that the AKS container is deployed to in the subscription.

    Enable AKS container health monitoring

    Note

    If you want to create a new Log Analytics workspace for storing the monitoring data from the cluster, follow the instructions in Create a Log Analytics workspace. Be sure to create the workspace in the same subscription that the AKS container is deployed to.

After you've enabled monitoring, it might take about 15 minutes before you can view operational data for the cluster.

Enable monitoring by using an Azure Resource Manager template

This method includes two JSON templates. One template specifies the configuration to enable monitoring, and the other contains parameter values that you configure to specify the following:

  • The AKS container resource ID.
  • The resource group that the cluster is deployed in.
  • The Log Analytics workspace and region to create the workspace in.

Note

The template needs to be deployed in the same resource group as the cluster.

The Log Analytics workspace has to be created manually. To create the workspace, you can set it up through Azure Resource Manager, through PowerShell, or in the Azure portal.

If you are unfamiliar with the concept of deploying resources by using a template, see:

If you choose to use the Azure CLI, you first need to install and use the CLI locally. You must be running the Azure CLI version 2.0.27 or later. To identify your version, run az --version. If you need to install or upgrade the Azure CLI, see Install the Azure CLI.

Create and execute a template

  1. Copy and paste the following JSON syntax into your file:

    {
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "aksResourceId": {
        "type": "string",
        "metadata": {
           "description": "AKS Cluster Resource ID"
           }
    },
    "aksResourceLocation": {
    "type": "string",
     "metadata": {
        "description": "Location of the AKS resource e.g. \"East US\""
       }
    },
    "workspaceResourceId": {
      "type": "string",
      "metadata": {
         "description": "Azure Monitor Log Analytics Resource ID"
       }
    },
    "workspaceRegion": {
    "type": "string",
    "metadata": {
       "description": "Azure Monitor Log Analytics workspace region"
      }
     }
    },
    "resources": [
      {
    "name": "[split(parameters('aksResourceId'),'/')[8]]",
    "type": "Microsoft.ContainerService/managedClusters",
    "location": "[parameters('aksResourceLocation')]",
    "apiVersion": "2018-03-31",
    "properties": {
      "mode": "Incremental",
      "id": "[parameters('aksResourceId')]",
      "addonProfiles": {
        "omsagent": {
          "enabled": true,
          "config": {
            "logAnalyticsWorkspaceResourceID": "[parameters('workspaceResourceId')]"
          }
         }
       }
      }
     },
    {
        "type": "Microsoft.Resources/deployments",
        "name": "[Concat('ContainerInsights', '-',  uniqueString(parameters('workspaceResourceId')))]",	
        "apiVersion": "2017-05-10",
        "subscriptionId": "[split(parameters('workspaceResourceId'),'/')[2]]",
        "resourceGroup": "[split(parameters('workspaceResourceId'),'/')[4]]",
        "properties": {
            "mode": "Incremental",
            "template": {
                "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
                "contentVersion": "1.0.0.0",
                "parameters": {},
                "variables": {},
                "resources": [
                    {
                        "apiVersion": "2015-11-01-preview",
                        "type": "Microsoft.OperationsManagement/solutions",
                        "location": "[parameters('workspaceRegion')]",
                        "name": "[Concat('ContainerInsights', '(', split(parameters('workspaceResourceId'),'/')[8], ')')]",
                        "properties": {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]"
                        },
                        "plan": {
                            "name": "[Concat('ContainerInsights', '(', split(parameters('workspaceResourceId'),'/')[8], ')')]",
                            "product": "[Concat('OMSGallery/', 'ContainerInsights')]",
                            "promotionCode": "",
                            "publisher": "Microsoft"
                        }
                    }
                ]
            },
            "parameters": {}
        }
       }
     ]
    }
    
  2. Save this file as existingClusterOnboarding.json to a local folder.

  3. Paste the following JSON syntax into your file:

    {
       "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
       "contentVersion": "1.0.0.0",
       "parameters": {
         "aksResourceId": {
           "value": "/subscriptions/<SubscriptionId>/resourcegroups/<ResourceGroup>/providers/Microsoft.ContainerService/managedClusters/<ResourceName>"
       },
       "aksResourceLocation": {
         "value": "<aksClusterLocation>"
       },
       "workspaceResourceId": {
         "value": "/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>"
       },
       "workspaceRegion": {
         "value": "<workspaceLocation>"
       }
     }
    }
    
  4. Edit the values for aksResourceId and aksResourceLocation by using the values on the AKS Overview page for the AKS cluster. The value for workspaceResourceId is the full resource ID of your Log Analytics workspace, which includes the workspace name. Also specify the location of the workspace for workspaceRegion.

  5. Save this file as existingClusterParam.json to a local folder.

  6. You are ready to deploy this template.

    • Use the following PowerShell commands in the folder that contains the template:

      New-AzResourceGroupDeployment -Name OnboardCluster -ResourceGroupName <ResourceGroupName> -TemplateFile .\existingClusterOnboarding.json -TemplateParameterFile .\existingClusterParam.json
      

      The configuration change can take a few minutes to complete. When it's completed, a message is displayed that's similar to the following and includes the result:

      provisioningState       : Succeeded
      
    • To run the following command by using the Azure CLI:

      az login
      az account set --subscription "Subscription Name"
      az group deployment create --resource-group <ResourceGroupName> --template-file ./existingClusterOnboarding.json --parameters @./existingClusterParam.json
      

      The configuration change can take a few minutes to complete. When it's completed, a message is displayed that's similar to the following and includes the result:

      provisioningState       : Succeeded
      

      After you've enabled monitoring, it might take about 15 minutes before you can view health metrics for the cluster.

Verify agent and solution deployment

With agent version 06072018 or later, you can verify that both the agent and the solution were deployed successfully. With earlier versions of the agent, you can verify only agent deployment.

Agent version 06072018 or later

Run the following command to verify that the agent is deployed successfully.

kubectl get ds omsagent --namespace=kube-system

The output should resemble the following, which indicates that it was deployed properly:

User@aksuser:~$ kubectl get ds omsagent --namespace=kube-system 
NAME       DESIRED   CURRENT   READY     UP-TO-DATE   AVAILABLE   NODE SELECTOR                 AGE
omsagent   2         2         2         2            2           beta.kubernetes.io/os=linux   1d

To verify deployment of the solution, run the following command:

kubectl get deployment omsagent-rs -n=kube-system

The output should resemble the following, which indicates that it was deployed properly:

User@aksuser:~$ kubectl get deployment omsagent-rs -n=kube-system 
NAME       DESIRED   CURRENT   UP-TO-DATE   AVAILABLE    AGE
omsagent   1         1         1            1            3h

Agent version earlier than 06072018

To verify that the Log Analytics agent version released before 06072018 is deployed properly, run the following command:

kubectl get ds omsagent --namespace=kube-system

The output should resemble the following, which indicates that it was deployed properly:

User@aksuser:~$ kubectl get ds omsagent --namespace=kube-system 
NAME       DESIRED   CURRENT   READY     UP-TO-DATE   AVAILABLE   NODE SELECTOR                 AGE
omsagent   2         2         2         2            2           beta.kubernetes.io/os=linux   1d

View configuration with CLI

Use the aks show command to get details such as is the solution enabled or not, what is the Log Analytics workspace resourceID, and summary details about the cluster.

az aks show -g <resourceGroupofAKSCluster> -n <nameofAksCluster>

After a few minutes, the command completes and returns JSON-formatted information about solution. The results of the command should show the monitoring add-on profile and resembles the following example output:

"addonProfiles": {
    "omsagent": {
      "config": {
        "logAnalyticsWorkspaceResourceID": "/subscriptions/<WorkspaceSubscription>/resourceGroups/<DefaultWorkspaceRG>/providers/Microsoft.OperationalInsights/workspaces/<defaultWorkspaceName>"
      },
      "enabled": true
    }
  }

Next steps

  • If you experience issues while attempting to onboard the solution, review the troubleshooting guide

  • With monitoring enabled to capture health metrics for both the AKS cluster nodes and pods, these health metrics are available in the Azure portal. To learn how to use Azure Monitor for containers, see View Azure Kubernetes Service health.