Kubernetes Onboarding Prerequisites

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 Distributed Cloud Firewall feature is enabled.
• Discovery of Kubernetes Resources 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 Onboarding Private Kubernetes Clusters .
• SNAT is disabled on worker nodes. See Disable SNAT for Kubernetes Workloads 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 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.

​

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

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 Onboard Self-Managed or Custom Clusters page. CRD-based policy requires the k8s_dcf_policies feature flag to be enabled by Aviatrix. See Distributed Cloud Firewall for Kubernetes .

​

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 Onboard Self-Managed or Custom Clusters .

​

Limitations

• Automatic onboarding via the Kubernetes Clusters tab supports only publicly available clusters. Private clusters are onboarded after establishing connectivity. See Onboarding Private Kubernetes Clusters .
• A cluster that does not meet the prerequisites above appears greyed out in the SmartGroup creation dialog.

​

Next Steps

• Onboard EKS Clusters
• Onboard AKS Clusters
• Onboard GKE Clusters
• Onboard Self-Managed or Custom Clusters

​

Related Topics

• Aviatrix Kubernetes Firewall
• Distributed Cloud Firewall for Kubernetes
• Disable SNAT for Kubernetes Workloads