> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard AKS Clusters

> Step-by-step AKS onboarding for the Aviatrix Distributed Cloud Firewall. Two authentication paths: Azure Cloud Account (recommended) and service-account kubeconfig.

Onboard a publicly accessible AKS cluster. For private AKS clusters, also see

<a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/private-kubernetes-cluster-onboard"}>Onboarding Private Kubernetes Clusters</a>
.

## Before you start

Read

<a href={"/docs/enterprise/" + "8.2" + "/reference/dcf/kubernetes-prerequisites"}>Kubernetes Onboarding Prerequisites</a>
. 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

<a href={"/docs/enterprise/" + "8.2" + "/reference/dcf/kubernetes-prerequisites#cloud-account-discovery-permissions"}>AKS discovery and onboarding permissions</a>
.

<Warning>
  **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](#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.
</Warning>

## 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](https://learn.microsoft.com/en-us/azure/aks/outbound-rules-control-egress).
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

<a href={"/docs/enterprise/" + "8.2" + "/reference/dcf/kubernetes-prerequisites#cloud-account-discovery-permissions"}>discovery permissions</a>
— 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.

```bash theme={null}
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

<a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/dcf-kubernetes"}>Distributed Cloud Firewall for Kubernetes</a>
.

<Note>
  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.
</Note>

### Step 3: Register the cluster

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    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
    }
    ```

    <Warning>`cluster_id` must be lowercased — use `lower()`.</Warning>
  </Tab>

  <Tab title="CoPilot UI">
    1. Navigate to **Cloud Resources > Cloud Assets > Kubernetes Clusters**.
    2. Click **Onboard** next to the discovered AKS cluster.
    3. Select **Permissions on Cloud Account** to use the existing service
       principal.
    4. Click **Onboard**.
  </Tab>
</Tabs>

## 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

<a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/kubernetes-onboard-custom"}>Onboard Self-Managed or Custom Clusters</a>
. AKS-specific notes follow.

### Step 1: Create the ServiceAccount and ClusterRoleBinding

Apply the

<a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/kubernetes-onboard-custom#step-1-create-a-service-account-and-clusterrolebinding"}>Step 1 manifest</a>
and extract the token.

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

```bash theme={null}
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

<a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/kubernetes-onboard-custom#step-2-assemble-a-kubeconfig"}>Step 2</a>
and
<a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/kubernetes-onboard-custom#step-3-register-the-cluster"}>Step 3</a>
on the custom-clusters page. AKS Terraform:

```hcl theme={null}
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:

```bash theme={null}
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.

## Related Topics

* <a href={"/docs/enterprise/" + "8.2" + "/reference/dcf/kubernetes-prerequisites"}>Kubernetes Onboarding Prerequisites</a>
* <a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/kubernetes-onboard"}>Onboarding Kubernetes Clusters</a>
* <a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/dcf-kubernetes"}>Distributed Cloud Firewall for Kubernetes</a>
* <a href={"/docs/enterprise/" + "8.2" + "/reference/dcf/kubernetes-snat"}>Disable SNAT for Kubernetes Workloads</a>
* <a href={"/docs/enterprise/" + "8.2" + "/guides/security/dcf/kubernetes-onboard-custom"}>Onboard Self-Managed or Custom Clusters</a>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.