Onboard AKS Clusters

Onboard a publicly accessible AKS cluster. For private AKS clusters, also see Onboarding Private Kubernetes Clusters .

Before you start

Read Kubernetes Onboarding Prerequisites . Confirm DCF is enabled, Resource Discovery is on, the API server is reachable from the Controller, and SNAT is disabled. The Aviatrix cloud account for the Azure subscription hosting the cluster must include the AKS discovery and onboarding permissions .

Microsoft Entra ID / Azure AD authentication is not supported for Path A. Path A requires Kubernetes RBAC with local accounts:

local_account_disabled = false
role_based_access_control_enabled = true

The Aviatrix Controller cannot execute external auth binaries; the kubeconfig returned by listClusterUserCredential for Entra ID-integrated clusters relies on exec plugins and is rejected.If the cluster integrates with Microsoft Entra ID, onboard using Path B — Service-account kubeconfig instead. Path B authenticates with a Kubernetes ServiceAccount token, which does not depend on the cluster’s Entra ID configuration.

DCF policy requirements for cluster connectivity

When DCF is enabled, you are responsible for configuring DCF policies that allow the AKS cluster to reach the outbound endpoints it needs for normal operation. Without these policies, cluster components may fail to pull container images, authenticate to Microsoft Entra ID, or reach Azure management endpoints. For the full list of outbound destinations an AKS cluster requires, see Microsoft’s documentation on outbound network and FQDN rules for AKS clusters. Use that list to plan SmartGroups and DCF rules that permit the required egress while keeping the rest of your security posture intact.

Choose how the Controller authenticates

Two paths, both supported equally:

Path A — Azure Cloud Account (recommended for managed AKS). The Aviatrix service principal calls listClusterUserCredential to obtain a kubeconfig. The returned kubeconfig contains a static client certificate mapped to the AKS local-account masterclient user.
Path B — Service-account kubeconfig. A Kubernetes ServiceAccount in the cluster issues a bearer token; you assemble a kubeconfig and provide it to the Controller.

Path A — Cloud Account

Step 1: Confirm the service principal has the listClusterUserCredential permission

See discovery permissions — the action is listed under “For onboarding using the Cloud Account.”

Step 2: Install the Aviatrix helm chart

Aviatrix recommends installing the helm chart on AKS clusters. Although the kubeconfig returned by listClusterUserCredential provides cluster-admin access via the AKS local-account model, installing the chart makes the Controller’s RBAC explicit and auditable, prepares the cluster for CRD-based DCF policy, and gives a uniform setup across providers.

helm repo add k8s-firewall https://aviatrixsystems.github.io/k8s-firewall-charts
helm repo update
helm install k8s-firewall k8s-firewall/k8s-firewall

The chart installs the avx-controller ClusterRole and the Aviatrix CRDs needed by Distributed Cloud Firewall for Kubernetes .

CRD-based policy is gated by the k8s_dcf_policies feature flag (default off; enabled by Aviatrix). AKS support for CRD-based policy is implemented in the Controller but does not have end-to-end test coverage as of 9.0 — flag any issues to support.

Step 3: Register the cluster

Terraform
CoPilot UI

data "azurerm_kubernetes_cluster" "this" {
  name                = "<CLUSTER_NAME>"
  resource_group_name = "<RESOURCE_GROUP>"
}

resource "aviatrix_kubernetes_cluster" "this" {
  cluster_id          = lower(data.azurerm_kubernetes_cluster.this.id)
  use_csp_credentials = true
}

cluster_id must be lowercased — use lower().

Path B — Service-account kubeconfig

The Controller authenticates to the cluster with a bearer token from a Kubernetes ServiceAccount. The full canonical flow lives on Onboard Self-Managed or Custom Clusters . AKS-specific notes follow.

Step 1: Create the ServiceAccount and ClusterRoleBinding

Apply the Step 1 manifest and extract the token.

Step 2: Get the cluster’s CA cert and API endpoint

az aks get-credentials \
  --name <CLUSTER_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --file - | awk '/certificate-authority-data/ { print $2 }'

az aks get-credentials \
  --name <CLUSTER_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --file - | awk '/server/ { print $2 }'

Step 3: Assemble a kubeconfig and register

Follow Step 2 and Step 3 on the custom-clusters page. AKS Terraform:

data "azurerm_kubernetes_cluster" "this" {
  name                = "<CLUSTER_NAME>"
  resource_group_name = "<RESOURCE_GROUP>"
}

resource "aviatrix_kubernetes_cluster" "this" {
  cluster_id  = lower(data.azurerm_kubernetes_cluster.this.id)
  kube_config = file("avx-kubeconfig.yaml")
}

Verifying onboarding

On the Kubernetes Clusters tab, the cluster transitions through No → Onboarding → Yes. From the controller pod:

kubectl exec -ti deploy/cloudxd -- asset-cli status k8s

The cluster should reach RUNNING within roughly 30 seconds.

Notes on Load Balancers

Network Load Balancers can be used but only when restricted to private subnets. You are responsible for the authorization of NLBs and Application Load Balancers in public subnets.

Concepts & Architecture

Guides

Reference

Before you start

DCF policy requirements for cluster connectivity

Choose how the Controller authenticates

Path A — Cloud Account

Step 1: Confirm the service principal has the listClusterUserCredential permission

Step 2: Install the Aviatrix helm chart

Step 3: Register the cluster

Path B — Service-account kubeconfig

Step 1: Create the ServiceAccount and ClusterRoleBinding

Step 2: Get the cluster’s CA cert and API endpoint

Step 3: Assemble a kubeconfig and register

Verifying onboarding

Notes on Load Balancers

​Before you start

​DCF policy requirements for cluster connectivity

​Choose how the Controller authenticates

​Path A — Cloud Account

​Step 1: Confirm the service principal has the listClusterUserCredential permission

​Step 2: Install the Aviatrix helm chart

​Step 3: Register the cluster

​Path B — Service-account kubeconfig

​Step 1: Create the ServiceAccount and ClusterRoleBinding

​Step 2: Get the cluster’s CA cert and API endpoint

​Step 3: Assemble a kubeconfig and register

​Verifying onboarding

​Notes on Load Balancers

​Related Topics

Before you start

DCF policy requirements for cluster connectivity

Choose how the Controller authenticates

Path A — Cloud Account

Step 1: Confirm the service principal has the listClusterUserCredential permission

Step 2: Install the Aviatrix helm chart

Step 3: Register the cluster

Path B — Service-account kubeconfig

Step 1: Create the ServiceAccount and ClusterRoleBinding

Step 2: Get the cluster’s CA cert and API endpoint

Step 3: Assemble a kubeconfig and register

Verifying onboarding

Notes on Load Balancers

Related Topics