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 .

Starting in Controller 10.1, Path A supports Microsoft Entra ID authentication in addition to local accounts. See Choose how the Controller authenticates to pick the option that matches your cluster’s 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 authenticates directly against the cluster. Path A has two authentication options:
- Entra ID (recommended). The Controller requests a short-lived OAuth2 token scoped to read-only Kubernetes RBAC. This is Microsoft’s recommended posture for new AKS clusters and requires no local accounts or cluster-admin access.
- Local accounts. 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, which has cluster-admin access.
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 required permissions

See discovery permissions . The permissions required depend on which authentication option you choose in Step 3 — Entra ID or local accounts.

Step 2: Install the Aviatrix helm chart

Aviatrix recommends installing the helm chart on AKS clusters. 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. This is required for Entra ID authentication and recommended for local accounts.

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

If you plan to use Entra ID authentication, pass two additional values so the chart’s ClusterRoleBinding targets the Azure service principal as a Kubernetes user:

helm install k8s-firewall k8s-firewall/k8s-firewall \
  --set role.subject.kind=User \
  --set role.subject.name=<SERVICE_PRINCIPAL_OBJECT_ID>

role.subject.kind must be User so the ClusterRoleBinding targets a Kubernetes user.
role.subject.name must be the object ID of the Azure service principal configured on the cloud account. Get it from the application ID with:
az ad sp show --id <CLOUD_ACCOUNT_APPLICATION_ID> | jq .id

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().

The Controller discovers the cluster’s Entra ID configuration from Azure and automatically uses Entra ID authentication if the cluster has Entra ID configured, falling back to local accounts otherwise. entra_id_authn is a computed attribute for CSP-managed clusters such as AKS — it reflects what the Controller discovers from Azure and is not an input you set here. (The attribute is only settable as an input inside the cluster_details block when onboarding a custom, non-CSP-managed cluster.)When the Controller uses Entra ID, it requests a short-lived OAuth2 token scoped to read-only Kubernetes RBAC. Each token is valid for 60–90 minutes and refreshes automatically; the Controller does not persist long-lived credentials for the cluster.

Local accounts require Kubernetes RBAC with local accounts enabled on the AKS cluster itself. These are properties on the cluster’s azurerm_kubernetes_cluster resource, not on aviatrix_kubernetes_cluster:

resource "azurerm_kubernetes_cluster" "aks_cluster" {
  local_account_disabled            = false
  role_based_access_control_enabled = true
}

The Aviatrix Controller cannot execute external auth binaries, so a cluster with Entra ID as its only authentication method cannot use local accounts — the kubeconfig returned by listClusterUserCredential for an Entra ID-only cluster relies on exec plugins and is rejected. Use Path B — Service-account kubeconfig instead.

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 required permissions

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 required permissions

​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 required permissions

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