How to fix AKS policy addon error in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 85 views

The AKS policy addon error occurs when Azure Policy fails to install, initialize, or enforce policies on your Kubernetes cluster. Common causes include missing prerequisites, Azure Policy addon not enabled, gatekeeper pod failures, or policy constraint violations.

Quick fix

Fixes AKS policy addon error

az aks show -g <resource-group> -n <cluster-name> --query "addonProfiles.azurePolicy"
  1. Verify Azure Policy addon is enabled
  2. Verify gatekeeper pods are running
  3. Check webhook certificate and connectivity
  4. Verify RBAC permissions for Azure Policy addon
kubernetes — error
az aks show -g <resource-group> -n <cluster-name> --query "addonProfiles.azurePolicy"
AKS policy addon error

What this error means

The Azure Policy Add-on extends Gatekeeper v3 (an admission controller webhook for Open Policy Agent) to enforce organizational policies across AKS clusters. When this addon encounters an error, it means the policy enforcement layer failed to initialize or is unable to process policy definitions. This can manifest as installation failures during addon enablement, gatekeeper pods refusing to start, policy constraint violations blocking resource creation, or policy assignments not syncing to the cluster. The addon serves as a control plane for compliance, so failures directly impact your ability to enforce security policies, governance rules, and organizational standards across containerized workloads.

Typical symptoms

  • Azure Policy addon installation fails with an error during cluster creation or addon enablement
  • Gatekeeper pods in kube-system or gatekeeper-system namespace are not running (CrashLoopBackOff)
  • Policy constraints block legitimate workload deployments with "constraint violation" errors
  • Policy assignments from Azure Portal do not sync to the cluster (20+ minute delay expected)
  • Auditing shows "policy not enforced" or "policy unenforced" status in Azure Policy compliance dashboard
  • kubectl get pods -n gatekeeper-system shows pods in Pending, Error, or NotReady state
  • kubectl logs on azure-policy or gatekeeper pods reveal RBAC permission errors or configuration issues

Common causes

  1. Azure Policy addon not enabled on the cluster during creation or via cluster update
  2. Insufficient Azure RBAC permissions to enable the addon (missing "Microsoft.ContainerService/managedClusters/write")
  3. Gatekeeper webhook service unable to bind to port 8888 (port conflict or network policy blocking)
  4. Missing or misconfigured CustomResourceDefinition (CRD) for constraint templates
  5. Pod security standards (PSS) or network policies blocking gatekeeper pod communication
  6. Azure Policy extension version incompatibility with Kubernetes version (policy addon requires K8s 1.14+)
  7. Insufficient cluster resources (CPU/memory) for policy pods to initialize
  8. Azure Policy attempting to enforce constraint on disabled or incompatible resource types

How to fix "AKS policy addon error"

1Verify Azure Policy addon is enabled

Check if the addon is installed on your cluster:

bash
az aks show -g <resource-group> -n <cluster-name> --query "addonProfiles.azurePolicy"

Expected output should show "enabled": true. If not enabled, install it:

bash
az aks enable-addons -g <resource-group> -n <cluster-name> --addons azure-policy

Wait 5-10 minutes for the addon to initialize:

bash
kubectl get pods -n kube-system | grep azure-policy
kubectl get pods -n gatekeeper-system
2Verify gatekeeper pods are running

Check if gatekeeper components are healthy:

bash
kubectl get pods -n gatekeeper-system
kubectl describe pod -n gatekeeper-system  # Shows pod events
kubectl logs -n gatekeeper-system --all-containers=true  # View logs

Expected pods: gatekeeper-audit-*, gatekeeper-controller-manager-*. If pods show CrashLoopBackOff or Error status:

bash
kubectl logs -n gatekeeper-system -l control-plane=controller-manager --tail=50

Look for RBAC, webhook binding, or resource contention errors.

3Check webhook certificate and connectivity

Azure Policy uses a webhook to intercept API requests. Verify it's configured:

bash
kubectl get ValidatingWebhookConfiguration -n gatekeeper-system
kubectl describe ValidatingWebhookConfiguration gatekeeper-validating-webhook-configuration

Verify the webhook service is accessible:

bash
kubectl get service -n gatekeeper-system
kubectl port-forward -n gatekeeper-system svc/gatekeeper-webhook-service 8888:8888

If webhook certificate is expired (common after long cluster idle periods), redeploy the addon:

bash
az aks disable-addons -g <resource-group> -n <cluster-name> --addons azure-policy
sleep 60
az aks enable-addons -g <resource-group> -n <cluster-name> --addons azure-policy
4Verify RBAC permissions for Azure Policy addon

The addon service principal needs cluster role bindings. Check:

bash
kubectl get clusterrolebinding | grep azure-policy
kubectl get clusterrole | grep azure-policy

If missing, the addon cannot function. Verify you have Azure RBAC to enable addons:

bash
az aks check-acl --resource-group <resource-group> --name <cluster-name>

You need "Microsoft.ContainerService/managedClusters/write" permission. If permission denied:
- Contact subscription owner to grant "AKS Cluster Admin" or "Contributor" role
- Or use az aks update after role assignment:

bash
az aks update -g <resource-group> -n <cluster-name>
5Check for network policy or pod security blocking gatekeeper

Network policies or Pod Security Standards (PSS) may block gatekeeper. Verify ingress to webhook:

bash
kubectl get networkpolicy -n gatekeeper-system
kubectl describe pod -n gatekeeper-system -l control-plane=controller-manager | grep -i "network\|security"

If PSS is enforcing restricted mode, it may block the webhook:

bash
kubectl describe namespace gatekeeper-system | grep pod-security

If restricted, temporarily relax for gatekeeper namespace:

bash
kubectl label namespace gatekeeper-system pod-security.kubernetes.io/enforce=baseline --overwrite

Then redeploy gatekeeper.

6Review constraint templates and policy assignments

Check if constraint templates are deployed:

bash
kubectl get constrainttemplates
kubectl describe constrainttemplate K8sRequiredLabels  # Example template

If templates missing, policy enforcement cannot start. For policy assignments in Azure:

bash
az policy assignment list --scope /subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.ContainerService/managedClusters/<cluster-name>

Assignments take up to 20 minutes to sync. If sync fails:

bash
kubectl logs -n kube-system -l app=azure-policy --tail=100

Look for "failed to apply" or "constraint not found" errors.

7Validate Kubernetes version compatibility

Azure Policy addon requires Kubernetes 1.14+. Check:

bash
kubectl version --short
az aks show -g <resource-group> -n <cluster-name> --query kubernetesVersion

If older than 1.14, upgrade cluster:

bash
az aks upgrade -g <resource-group> -n <cluster-name> --kubernetes-version 1.27

Note: Kubernetes 1.27+ has long-term support (LTS) and is recommended for production. After upgrade, re-enable the addon if needed.

8Redeploy Azure Policy addon completely

If addon still fails after checks, perform a clean redeploy:

bash
# 1. Disable addon
az aks disable-addons -g <resource-group> -n <cluster-name> --addons azure-policy

# 2. Wait for cleanup
sleep 120

# 3. Verify removed
kubectl get pods -n gatekeeper-system  # Should be empty
kubectl get pods -n kube-system | grep azure-policy  # Should be gone

# 4. Re-enable
az aks enable-addons -g <resource-group> -n <cluster-name> --addons azure-policy

# 5. Monitor initialization
watch kubectl get pods -n gatekeeper-system

Initialization can take 5-15 minutes. Watch for all pods to reach "Running" state.

9Enable diagnostic logging for troubleshooting

For persistent issues, enable Azure diagnostic logs:

bash
az monitor diagnostic-settings create \
  --name aks-policy-diags \
  --resource /subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.ContainerService/managedClusters/<cluster-name> \
  --logs '[{"category": "cluster-autoscaler", "enabled": true}]' \
  --workspace <log-analytics-workspace-id>

Then query logs in Log Analytics:

kusto
ContainerLog
| where TimeGenerated > ago(1h)
| where LogEntry contains "azure-policy" or LogEntry contains "gatekeeper"
| project TimeGenerated, Pod, LogEntry

This helps identify root causes in complex scenarios.

Advanced notes

In production, policy addon failures can block security-critical deployments. Always test policy changes in non-prod clusters first. Policy assignments syncing takes 20+ minutes; do not immediately retry if assignment appears not applied. For distros like AKS on Azure Stack HCI, ensure proper network routing to webhook endpoint. When combining with Pod Security Standards (PSS), note that gatekeeper operates at admission control level while PSS operates at pod security level—order of enforcement matters. For air-gapped clusters, ensure container images for azure-policy and gatekeeper are cached in your private registry. Azure Policy for Kubernetes uses OPA (Open Policy Agent) Rego language for policy logic; invalid Rego constraints will fail silently. For cost-sensitive deployments, note that audit-mode policies still consume gatekeeper resources even if not enforcing.

Frequently asked questions

What does "AKS policy addon error" mean?
The Azure Policy Add-on extends Gatekeeper v3 (an admission controller webhook for Open Policy Agent) to enforce organizational policies across AKS clusters. When this addon encounters an error, it means the policy enforcement layer failed to initialize or is unable to process policy definitions. This can manifest as installation failures during addon enablement, gatekeeper pods refusing to start, policy constraint violations blocking resource creation, or policy assignments not syncing to the cluster.
How do I fix "AKS policy addon error"?
The AKS policy addon error occurs when Azure Policy fails to install, initialize, or enforce policies on your Kubernetes cluster. Common causes include missing prerequisites, Azure Policy addon not enabled, gatekeeper pod failures, or policy constraint violations.
What causes "AKS policy addon error"?
Azure Policy addon not enabled on the cluster during creation or via cluster update Insufficient Azure RBAC permissions to enable the addon (missing "Microsoft.ContainerService/managedClusters/write") Gatekeeper webhook service unable to bind to port 8888 (port conflict or network policy blocking)
Is the "AKS policy addon error" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading