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

# Kubernetes Onboarding Prerequisites

> Single canonical prerequisites for onboarding any Kubernetes cluster (EKS, AKS, GKE, or self-managed) to the Aviatrix Controller for Distributed Cloud Firewall.

Read this page once before onboarding any Kubernetes cluster. The cloud-specific
onboarding pages link back to anchors here rather than restating the
requirements.

## Platform requirements

Confirm the following before onboarding any cluster:

* The
  <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/dcf-enable-feature"}>Distributed Cloud Firewall feature</a>
  is enabled.
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-resource-discovery"}>Discovery of Kubernetes Resources</a>
  is enabled under **Groups > Settings**.
* The Kubernetes API server is reachable from the Aviatrix Controller. The most
  common case is a public API endpoint with the Controller's IP allowlisted;
  private clusters require a private network path. See
  <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/private-kubernetes-cluster-onboard"}>Onboarding Private Kubernetes Clusters</a>
  .
* SNAT is disabled on worker nodes. See
  <a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-snat"}>Disable SNAT for Kubernetes Workloads</a>
  for EKS / AKS / GKE instructions.
* The cluster uses flat networking (the default for EKS, AKS, and GKE). Overlay
  networks are supported but only for Service-typed SmartGroups used as the
  destination of DCF rules. See
  [Services, Load Balancing, and Networking](https://kubernetes.io/docs/concepts/services-networking/)
  for background.

## Cloud account discovery permissions

The Aviatrix Controller's cloud account must include the permissions below for
the relevant provider so the controller can discover clusters in the cloud
account.

<Tabs>
  <Tab title="AWS (EKS)">
    * `eks:ListClusters`
    * `eks:DescribeCluster`
    * `elasticloadbalancing:DescribeLoadBalancers` (already present in the base set)
    * `elasticloadbalancing:DescribeTags` (already present in the base set)

    For step-by-step IAM setup, see

    <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-eks"}>Onboard EKS Clusters</a>
    .
  </Tab>

  <Tab title="Azure (AKS)">
    **For cluster discovery**

    * `Microsoft.ResourceGraph/resources/read`
    * `Microsoft.ContainerService/managedClusters/read`

    **For onboarding using the Cloud Account (CSP credentials) with Entra ID**

    No additional permissions beyond cluster discovery — the Controller requests its
    own short-lived OAuth2 token instead of retrieving a kubeconfig.

    **For onboarding using the Cloud Account (CSP credentials) with local accounts**

    * `Microsoft.ContainerService/managedClusters/listClusterUserCredential/action`

    <Note>
      Starting in Controller 10.1, onboarding via the Cloud Account (Path A)
      supports Microsoft Entra ID authentication in addition to local accounts. A
      cluster with Entra ID as its only authentication method cannot use the local
      accounts option — the Aviatrix Controller does not execute external auth
      binaries, and the kubeconfig returned by `listClusterUserCredential` for an
      Entra ID-only cluster relies on `exec` plugins. Use the Entra ID option
      instead. See{" "}
      <a href={"/docs/enterprise/" + "10.1" + "/guides/platform-administration/account-azure"}>Apply Azure RBAC</a>
      .
    </Note>
  </Tab>

  <Tab title="Google Cloud (GKE)">
    * `container.clusters.get`
    * `container.clusters.list`

    In-cluster access (namespaces, services, pods, nodes, endpointslices) is granted
    via GCP IAM-to-Kubernetes-RBAC mapping plus the Aviatrix helm chart. See

    <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-gke"}>Onboard GKE Clusters</a>
    .
  </Tab>
</Tabs>

## Kubernetes RBAC

The Aviatrix Controller authenticates to your cluster's Kubernetes API and reads
namespaces, services, pods, nodes, and endpoint slices. Permissions are granted
by a single ClusterRole, `avx-controller`, installed by the
[Aviatrix k8s-firewall helm chart](https://github.com/AviatrixSystems/k8s-firewall-charts).

Aviatrix recommends installing the helm chart on every onboarded cluster. It is
the canonical packaging of the Aviatrix CRDs and the `avx-controller`
ClusterRole and ClusterRoleBinding, and it stays aligned with the controller
version. If Helm is not available in your environment, you can render the same
objects with
`helm template k8s-firewall k8s-firewall/k8s-firewall | kubectl apply -f -` and
apply them yourself.

### What the ClusterRole grants

| Permission   | Resources                                                   | Used for                                            |
| ------------ | ----------------------------------------------------------- | --------------------------------------------------- |
| Read         | `namespaces`, `services`, `pods`, `nodes`, `endpointslices` | SmartGroup discovery (always required)              |
| Read/write   | `networking.aviatrix.com/*`                                 | In-cluster `FirewallPolicy` / `WebgroupPolicy` CRDs |
| Create/patch | `events`                                                    | Controller status events                            |

The helm chart installs this ClusterRole regardless of whether you use CRD-based
DCF policy — there is no separate discovery-only manifest. If you cannot use the
helm chart (for example, a custom self-managed cluster without helm), see the
equivalent manifest on the

<a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-custom"}>Onboard Self-Managed or Custom Clusters</a>
page.

CRD-based policy requires the `k8s_dcf_policies` feature flag to be enabled by
Aviatrix. See

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

## Kubeconfig requirements

When onboarding via the kubeconfig path (an alternative to CSP credentials,
supported on every provider), the kubeconfig must:

* Use inline credential data — `certificate-authority-data`, `token`, or
  `client-certificate-data` (base64-encoded). The Controller does not read files
  from the local filesystem.
* Use static credentials. `exec` plugins (such as `aws eks get-token` or AAD
  auth) are not supported.
* Contain a single cluster, user, and context.
* Be sufficient to read namespaces, services, pods, nodes, and endpointslices.
  For CRD-based DCF policy, also read/write `networking.aviatrix.com/*`.

For a worked example see

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

## Limitations

* Automatic onboarding via the **Kubernetes Clusters** tab supports only
  publicly available clusters. Private clusters are onboarded after establishing
  connectivity. See
  <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/private-kubernetes-cluster-onboard"}>Onboarding Private Kubernetes Clusters</a>
  .
* A cluster that does not meet the prerequisites above appears greyed out in the
  SmartGroup creation dialog.

## Next Steps

* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-eks"}>Onboard EKS Clusters</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-aks"}>Onboard AKS Clusters</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-gke"}>Onboard GKE Clusters</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-custom"}>Onboard Self-Managed or Custom Clusters</a>

## Related Topics

* <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/kubernetes-overview"}>Aviatrix Kubernetes Firewall</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/dcf-kubernetes"}>Distributed Cloud Firewall for Kubernetes</a>
* <a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-snat"}>Disable SNAT for Kubernetes Workloads</a>