- Establishing private connectivity — setting up a network path between the Controller and the private cluster.
- 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.
- 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.
- CoPilot UI
- Terraform
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.
Option 2: Build a Dedicated Private Network Path (Recommended for GA Environments)
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: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 theterraform-aws-modules/eks/aws module:
<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.Using CSP Credentials (Recommended)
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.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:Step 2: Create a Kubeconfig
Build a kubeconfig file for the private cluster. Replace the placeholder values with your cluster-specific details.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 ofRUNNING within approximately 30 seconds. See
Verifying Onboarding Status
for the status definitions.
Next Steps
- Create Kubernetes SmartGroups to reference workloads in the private cluster.
- Create DCF policy rules to control traffic to and from those workloads.