Understand Azure Policy for Azure Kubernetes Service

Azure Policy integrates with the Azure Kubernetes Service (AKS) to apply at-scale enforcements and safeguards on your clusters in a centralized, consistent manner. By extending use of Gatekeeper v2, an admission controller webhook for Open Policy Agent (OPA), Azure Policy makes it possible to manage and report on the compliance state of your Azure resources and AKS clusters from one place.

Note

Azure Policy for AKS is in Limited Preview and only supports built-in policy definitions.

Overview

To enable and use Azure Policy for AKS with your AKS cluster, take the following actions:

Opt-in for preview

Before installing the Azure Policy Add-on or enabling any of the service features, your subscription must enable the Microsoft.ContainerService resource provider and the Microsoft.PolicyInsights resource provider, then be approved to join the preview. To join the preview, follow these steps in either the Azure portal or with Azure CLI:

  • Azure portal:

    1. Register the Microsoft.ContainerService and Microsoft.PolicyInsights resource providers. For steps, see Resource providers and types.

    2. Launch the Azure Policy service in the Azure portal by clicking All services, then searching for and selecting Policy.

      Search for Policy in All Services

    3. Select Join Preview on the left side of the Azure Policy page.

      Join the Policy for AKS preview

    4. Select the row of the subscription you want added to the preview.

    5. Select the Opt-in button at the top of the list of subscriptions.

  • Azure CLI:

    # Log in first with az login if you're not using Cloud Shell
    
    # Provider register: Register the Azure Kubernetes Services provider
    az provider register --namespace Microsoft.ContainerService
    
    # Provider register: Register the Azure Policy provider
    az provider register --namespace Microsoft.PolicyInsights
    
    # Feature register: enables installing the add-on
    az feature register --namespace Microsoft.ContainerService --name AKS-AzurePolicyAutoApprove
    
    # Use the following to confirm the feature has registered
    az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/AKS-AzurePolicyAutoApprove')].{Name:name,State:properties.state}"
    
    # Once the above shows 'Registered' run the following to propagate the update
    az provider register -n Microsoft.ContainerService
    
    # Feature register: enables the add-on to call the Azure Policy resource provider
    az feature register --namespace Microsoft.PolicyInsights --name AKS-DataplaneAutoApprove
    
    # Use the following to confirm the feature has registered
    az feature list -o table --query "[?contains(name, 'Microsoft.PolicyInsights/AKS-DataPlaneAutoApprove')].{Name:name,State:properties.state}"
    
    # Once the above shows 'Registered' run the following to propagate the update
    az provider register -n Microsoft.PolicyInsights
    
    

Azure Policy Add-on

The Azure Policy Add-on for Kubernetes connects the Azure Policy service to the Gatekeeper admission controller. The add-on, which is installed into the azure-policy namespace, enacts the following functions:

  • Checks with Azure Policy for assignments to the AKS cluster
  • Downloads and caches policy details, including the rego policy definition, as configmaps
  • Runs a full scan compliance check on the AKS cluster
  • Reports auditing and compliance details back to Azure Policy

Installing the add-on

Prerequisites

Before you install the add-on in your AKS cluster, the preview extension must be installed. This step is done with Azure CLI:

  1. You need the Azure CLI version 2.0.62 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install the Azure CLI.

  2. The AKS cluster must be version 1.10 or higher. Use the following script to validate your AKS cluster version:

    # Log in first with az login if you're not using Cloud Shell
    
    # Look for the value in kubernetesVersion
    az aks list
    
  3. Install version 0.4.0 of the Azure CLI preview extension for AKS, aks-preview:

    # Log in first with az login if you're not using Cloud Shell
    
    # Install/update the preview extension
    az extension add --name aks-preview
    
    # Validate the version of the preview extension
    az extension show --name aks-preview --query [version]
    

    Note

    If you've previously installed the aks-preview extension, install any updates using the az extension update --name aks-preview command.

Installation steps

Once the prerequisites are completed, install the Azure Policy Add-on in the AKS cluster you want to manage.

  • Azure portal

    1. Launch the AKS service in the Azure portal by clicking All services, then searching for and selecting Kubernetes services.

    2. Select one of your AKS clusters.

    3. Select Policies (preview) on the left side of the Kubernetes service page.

      Policies from the AKS cluster

    4. In the main page, select the Enable add-on button.

      Enable the Azure Policy for AKS add-on

      Note

      If the Enable add-on button is grayed out, the subscription has not yet been added to the preview. See Opt-in for preview for the required steps.

  • Azure CLI

    # Log in first with az login if you're not using Cloud Shell
    
    az aks enable-addons --addons azure-policy --name MyAKSCluster --resource-group MyResourceGroup
    

Validation and reporting frequency

The add-on checks in with Azure Policy for changes in policy assignments every 5 minutes. During this refresh cycle, the add-on removes all configmaps in the azure-policy namespace then recreates the configmaps for Gatekeeper use.

Note

While a cluster admin may have permission to the azure-policy namespace, it's not recommended or supported to make changes to the namespace. Any manual changes made are lost during the refresh cycle.

Every 5 minutes, the add-on calls for a full scan of the cluster. After gathering details of the full scan and any real-time evaluations by Gatekeeper of attempted changes to the cluster, the add-on reports the results back to Azure Policy for inclusion in compliance details like any Azure Policy assignment. Only results for active policy assignments are returned during the audit cycle.

Policy language

The Azure Policy language structure for managing AKS follows that of existing policies. The effect EnforceRegoPolicy is used to manage your AKS clusters and takes details properties specific to working with OPA and Gatekeeper v2. For details and examples, see the EnforceRegoPolicy effect.

As part of the details.policy property in the policy definition, Azure Policy passes the URI of a rego policy to the add-on. Rego is the language that OPA and Gatekeeper support to validate or mutate a request to the Kubernetes cluster. By supporting an existing standard for Kubernetes management, Azure Policy makes it possible to reuse existing rules and pair them with Azure Policy for a unified cloud compliance reporting experience. For more information, see What is Rego?.

Built-in policies

To find the built-in policies for managing AKS using the Azure portal, follow these steps:

  1. Start the Azure Policy service in the Azure portal. Select All services in the left pane and then search for and select Policy.

  2. In the left pane of the Azure Policy page, select Definitions.

  3. From the Category drop-down list box, use Select all to clear the filter and then select Kubernetes service.

  4. Select the policy definition, then select the Assign button.

Note

When assigning the Azure Policy for AKS definition, the Scope must include the AKS cluster resource.

Alternately, use the Assign a policy - Portal quickstart to find and assign an AKS policy. Search for a Kubernetes policy definition instead of the sample 'audit vms'.

Important

Built-in policies in category Kubernetes service are only for use with AKS.

Logging

Azure Policy Add-on logs

As a Kubernetes controller/container, the Azure Policy Add-on keeps logs in the AKS cluster. The logs are exposed in the Insights page of the AKS cluster. For more information, see Understand AKS cluster performance with Azure Monitor for containers.

Gatekeeper logs

To enable Gatekeeper logs for new resource requests, follow the steps in Enable and review Kubernetes master node logs in AKS. Here is an example query to view denied events on new resource requests:

| where Category == "kube-audit"
| where log_s contains "admission webhook"
| limit 100

To view logs from Gatekeeper containers, follow the steps in Enable and review Kubernetes master node logs in AKS and check the kube-apiserver option in the Diagnostic settings pane.

Remove the add-on

To remove the Azure Policy Add-on from your AKS cluster, use either the Azure portal or Azure CLI:

  • Azure portal

    1. Launch the AKS service in the Azure portal by clicking All services, then searching for and selecting Kubernetes services.

    2. Select your AKS cluster where you want to disable the Azure Policy Add-on.

    3. Select Policies (preview) on the left side of the Kubernetes service page.

      Policies from the AKS cluster

    4. In the main page, select the Disable add-on button.

      Disable the Azure Policy for AKS add-on

  • Azure CLI

    # Log in first with az login if you're not using Cloud Shell
    
    az aks disable-addons --addons azure-policy --name MyAKSCluster --resource-group MyResourceGroup
    

Diagnostic data collected by Azure Policy Add-on

The Azure Policy Add-on for Kubernetes collects limited cluster diagnostic data. This diagnostic data is vital technical data related to software and performance. It's used in the following ways:

  • Keep Azure Policy Add-on up to date
  • Keep Azure Policy Add-on secure, reliable, performant
  • Improve Azure Policy Add-on - through the aggregate analysis of the use of the add-on

The information collected by the add-on isn't personal data. The following details are currently collected:

  • Azure Policy Add-on agent version
  • Cluster type
  • Cluster region
  • Cluster resource group
  • Cluster resource ID
  • Cluster subscription ID
  • Cluster OS (Example: Linux)
  • Cluster city (Example: Seattle)
  • Cluster state or province (Example: Washington)
  • Cluster country or region (Example: United States)
  • Exceptions/errors encountered by Azure Policy Add-on during agent installation on policy evaluation
  • Number of Gatekeeper policies not installed by Azure Policy Add-on

Next steps