Skip to main content
Private Kubernetes clusters have an API server that is not exposed to the public internet. Because the Aviatrix Controller must reach the Kubernetes API server to discover resources, it needs a private network path to the cluster before you can onboard it. How you establish that connectivity is up to you — VPC peering, a VPN, AWS PrivateLink, an Aviatrix Transit architecture, or routing connectivity through a Spoke Gateway already deployed in the cluster’s VPC (Early Access) all work. The only requirement is that the Controller can reach the Kubernetes API server endpoint over a private path. This guide covers:
  1. Establishing private connectivity — setting up a network path between the Controller and the private cluster.
  2. Onboarding the private cluster — registering it with the Controller once connectivity is in place.
All prerequisites from the main onboarding guide apply to private clusters. Review them before proceeding.

Prerequisites

In addition to the standard prerequisites :
  • The Aviatrix Controller must have private network reachability to the Kubernetes API server.
  • The cluster’s API server security group (or equivalent firewall rules) must allow inbound HTTPS (port 443) from the Controller’s private IP address, or from the Spoke Gateway’s private IP address if you route cluster connectivity through a Spoke Gateway.
  • You must have kubectl access to the private cluster to apply RBAC configurations.
  • Terraform installed if you plan to use Infrastructure as Code for configuration.

Establishing Private Connectivity

The Controller needs a network path to the private Kubernetes API server. Choose one of the following options.
  • Option 1: Route Cluster Connectivity through Spoke Gateway (Early Access) — the fastest path if an Aviatrix Spoke Gateway is already deployed in the cluster’s VPC. Review the limitation noted below before using this option in a production environment.
  • Option 2: Build a Dedicated Private Network Path (Recommended for GA Environments) — Aviatrix Transit, VPC peering, AWS PrivateLink, VPN, or AWS Transit Gateway. Any of these gives the Controller a persistent private path to the API server that does not depend on Spoke Gateway tunnel connectivity.

Option 1: Route Cluster Connectivity through Spoke Gateway (Early Access)

Controller version 10.1 introduces the option to route cluster connectivity through a Spoke Gateway, as an Early Access alternative to building a dedicated network path to the private cluster. If an Aviatrix Spoke Gateway is already deployed in the cluster’s VPC, the Controller reaches the cluster’s API server through that Spoke Gateway. You do not need to attach the Spoke Gateway to an Aviatrix Transit, and you do not need to create a separate VPC peering, PrivateLink, VPN, or Transit Gateway connection.
Routing cluster connectivity through a Spoke Gateway is an Early Access feature in Controller 10.1. To request Early Access, contact your Aviatrix account team. Early Access features are in active development, receive best-effort support, and may change significantly before Preview or GA. See Aviatrix Feature Modes for details, and evaluate this capability in a non-production environment first.
Requirements to route cluster connectivity through a Spoke Gateway:
  • An Aviatrix Spoke Gateway already deployed in the cluster’s VPC. An Aviatrix Transit attachment is not required for this method.
  • A security group rule on the cluster’s API server that allows inbound HTTPS (port 443) from the Spoke Gateway’s private IP address. If this rule is missing, cluster discovery fails until you add it.
  • The Route Cluster Connectivity through Spoke Gateway toggle enabled on the cluster resource.
To enable this option:
When you onboard or edit the cluster, set the Route Cluster Connectivity through Spoke Gateway toggle to On.
Routing cluster connectivity through a Spoke Gateway supports EKS, AKS, and GKE clusters and requires Controller version 10.1 or later.
If the connection between the Spoke Gateway and the Kubernetes API server is interrupted, Kubernetes resources deleted during the interruption might still appear in CoPilot and remain eligible for DCF policy matching after connectivity is restored. If your environment requires resource inventory to stay accurate through network interruptions, use Option 2 instead until this is resolved.
This approach uses Aviatrix Transit, or another private connectivity method, to give the Controller a persistent private path to the cluster’s API server — independent of Spoke Gateway tunnel connectivity. This guide describes Aviatrix Transit in detail. See Other Connectivity Methods for alternatives.

Step 1: Create a Spoke Gateway in the Controller VPC

Deploy an Aviatrix Spoke Gateway in the VPC where the Aviatrix Controller runs. If a Spoke Gateway already exists in this VPC, skip this step. The Controller runs in a public subnet, but the Spoke Gateway enables private-address connectivity through the Aviatrix Transit backbone to other spokes — including the VPC that hosts the private Kubernetes cluster.

Step 2: Attach Both VPCs to an Aviatrix Transit

Attach the Controller VPC spoke and the cluster VPC spoke to the same Aviatrix Transit so they can communicate over the Aviatrix backbone.

Step 3: Create a DCF Policy for Controller-to-Cluster Traffic

Create a DCF policy that permits the Controller to connect to the Kubernetes control plane:
You can obtain the API server hostname from the cluster endpoint URL. For EKS:
The hostname is the portion after https://.

Other Connectivity Methods

Any method that provides private reachability from the Controller to the K8s API server works:
  • VPC Peering — Direct peering between the Controller VPC and the cluster VPC.
  • AWS PrivateLink — Create a VPC endpoint for the EKS API server.
  • VPN — Site-to-site VPN connecting the Controller’s network to the cluster’s network.
  • AWS Transit Gateway — Native AWS Transit Gateway connecting both VPCs.

Configuring Security Groups

By default, managed Kubernetes services (such as EKS) restrict API server access to worker nodes only. Even with private connectivity at the network layer, you must add an inbound rule that allows the Controller (or, if you route cluster connectivity through a Spoke Gateway, the Spoke Gateway) to reach the API server. For example, when using the terraform-aws-modules/eks/aws module:
Replace <CONTROLLER_PRIVATE_IP> with the private IP address of your Aviatrix Controller instance, or the Spoke Gateway’s private IP address if you route cluster connectivity through a Spoke Gateway.

Onboarding the Private Cluster

Once connectivity is established and security groups are configured, onboard the cluster. For Controller version 8.2 and later, private clusters can be onboarded using CSP credentials — the same method used for public clusters. The networking and security group prerequisites still apply, but you can skip the service account and kubeconfig steps.
You still need to grant Controller access (EKS Access Entry + RBAC) as described in the main onboarding guide.

Using a Kubeconfig (Pre-8.2 or Non-Managed Clusters)

For Controller versions before 8.2, or for clusters where CSP credentials are not available, create a service account and kubeconfig manually.

Step 1: Create a Service Account

Apply the following manifest to create a ServiceAccount with the required RBAC permissions:
After applying the manifest, extract the authentication token:

Step 2: Create a Kubeconfig

Build a kubeconfig file for the private cluster. Replace the placeholder values with your cluster-specific details.
Retrieve the placeholder values:

Step 3: Register the Cluster

Use a custom cluster_id that differs from the cluster’s ARN. If the Controller discovers the cluster via cloud APIs, both the discovered entry and the manually configured entry will appear in CoPilot. The manually configured cluster is the active one.
The cluster may display as PUBLIC in CoPilot even though it is a private cluster. This is expected behavior.

Verification

After onboarding, verify the connection status on the Cloud Resources > Cloud Assets > Kubernetes Clusters tab in CoPilot. The cluster should show a status of RUNNING within approximately 30 seconds. See Verifying Onboarding Status for the status definitions.

Next Steps