Onboard GKE Clusters

Onboard a publicly accessible GKE cluster.

GKE clusters can only be onboarded via Terraform in 9.0. The CoPilot UI does not currently support GCP onboarding.

Before you start

Read Kubernetes Onboarding Prerequisites . 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 GCP project hosting the cluster must include the GKE discovery permissions .

Choose how the Controller authenticates

Two paths, both supported equally:

Path A — GCP Cloud Account (recommended for managed GKE). The Aviatrix GCP service-account JSON obtains a cloud-platform-scoped OAuth2 token. GKE’s API server validates the token and maps the GCP identity to Kubernetes RBAC.
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: Identify the Aviatrix GCP service account

Find the service-account email under Cloud Resources > Cloud Account in CoPilot. Format: <NAME>@<PROJECT>.iam.gserviceaccount.com.

Step 2: Install the Aviatrix helm chart with the GCP service-account bound

Aviatrix recommends installing the helm chart on GKE clusters. The chart’s avx-controller ClusterRole is bound by default to the Kubernetes group avx-controller. For GKE, you instead bind it directly to the GCP service-account user identity, because GCP IAM-to-Kubernetes-RBAC mapping does not place service accounts into a Kubernetes group. Although GCP IAM roles such as roles/container.viewer provide enough access for basic discovery on their own, installing the chart makes the Controller’s RBAC explicit, prepares the cluster for CRD-based DCF policy (which requires write permissions on networking.aviatrix.com/* that GCP IAM-to-RBAC mapping does not cover), and gives a uniform setup across providers. Create values.yaml:

role:
  name: avx-controller
  subject:
    kind: User
    name: <NAME>@<PROJECT>.iam.gserviceaccount.com

Install the chart with the override:

helm repo add k8s-firewall https://aviatrixsystems.github.io/k8s-firewall-charts
helm repo update
helm install k8s-firewall k8s-firewall/k8s-firewall -f values.yaml

CRD-based policy is gated by the k8s_dcf_policies feature flag (default off; enabled by Aviatrix). GKE 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.

Step 3: Register the cluster

data "google_container_cluster" "this" {
  name     = "<CLUSTER_NAME>"
  location = "<REGION_OR_ZONE>"
}

resource "aviatrix_kubernetes_cluster" "this" {
  cluster_id          = data.google_container_cluster.this.self_link
  use_csp_credentials = true
}

cluster_id is the GCP self-link, which looks like:

https://container.googleapis.com/v1/projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER_NAME>

Path B — Service-account kubeconfig

The Controller authenticates with a bearer token from a Kubernetes ServiceAccount. The full canonical flow lives on Onboard Self-Managed or Custom Clusters . GKE-specific notes follow.

Step 1: Create the ServiceAccount and ClusterRoleBinding

Apply the Step 1 manifest and extract the token.

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

gcloud container clusters describe <CLUSTER_NAME> \
  --location <REGION_OR_ZONE> --format json \
  | jq -r .masterAuth.clusterCaCertificate

gcloud container clusters describe <CLUSTER_NAME> \
  --location <REGION_OR_ZONE> --format json \
  | jq -r .controlPlaneEndpointsConfig.ipEndpointsConfig.publicEndpoint

# For private clusters, use the private endpoint:
gcloud container clusters describe <CLUSTER_NAME> \
  --location <REGION_OR_ZONE> --format json \
  | jq -r .controlPlaneEndpointsConfig.ipEndpointsConfig.privateEndpoint

Step 3: Assemble a kubeconfig and register

Follow Step 2 and Step 3 on the custom-clusters page. GKE Terraform:

data "google_container_cluster" "this" {
  name     = "<CLUSTER_NAME>"
  location = "<REGION_OR_ZONE>"
}

resource "aviatrix_kubernetes_cluster" "this" {
  cluster_id  = data.google_container_cluster.this.self_link
  kube_config = file("avx-kubeconfig.yaml")
}

Verifying onboarding

On the Kubernetes Clusters tab, the cluster transitions through No → Onboarding → Yes. From the controller pod:

kubectl exec -ti deploy/cloudxd -- asset-cli status k8s

The cluster should reach RUNNING within roughly 30 seconds.

Concepts & Architecture

Guides

Reference

Before you start

Choose how the Controller authenticates

Path A — Cloud Account

Step 1: Identify the Aviatrix GCP service account

Step 2: Install the Aviatrix helm chart with the GCP service-account bound

Step 3: Register the cluster

Path B — Service-account kubeconfig

Step 1: Create the ServiceAccount and ClusterRoleBinding

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

Step 3: Assemble a kubeconfig and register

Verifying onboarding

​Before you start

​Choose how the Controller authenticates

​Path A — Cloud Account

​Step 1: Identify the Aviatrix GCP service account

​Step 2: Install the Aviatrix helm chart with the GCP service-account bound

​Step 3: Register the cluster

​Path B — Service-account kubeconfig

​Step 1: Create the ServiceAccount and ClusterRoleBinding

​Step 2: Get the cluster’s CA cert and API endpoint

​Step 3: Assemble a kubeconfig and register

​Verifying onboarding

​Related Topics

Before you start

Choose how the Controller authenticates

Path A — Cloud Account

Step 1: Identify the Aviatrix GCP service account

Step 2: Install the Aviatrix helm chart with the GCP service-account bound

Step 3: Register the cluster

Path B — Service-account kubeconfig

Step 1: Create the ServiceAccount and ClusterRoleBinding

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

Step 3: Assemble a kubeconfig and register

Verifying onboarding

Related Topics