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

# Onboard GKE Clusters

> Step-by-step GKE onboarding for the Aviatrix Distributed Cloud Firewall. Terraform-only registration; two authentication paths.

Onboard a publicly accessible GKE cluster.

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

## Before you start

Read

<a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-prerequisites"}>Kubernetes Onboarding Prerequisites</a>
. 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

<a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-prerequisites#cloud-account-discovery-permissions"}>GKE discovery permissions</a>
.

## 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`:

```yaml theme={null}
role:
  name: avx-controller
  subject:
    kind: User
    name: <NAME>@<PROJECT>.iam.gserviceaccount.com
```

Install the chart with the override:

```bash theme={null}
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
```

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

### Step 3: Register the cluster

```hcl theme={null}
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

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

### Step 1: Create the ServiceAccount and ClusterRoleBinding

Apply the

<a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-custom#step-1-create-a-service-account-and-clusterrolebinding"}>Step 1 manifest</a>
and extract the token.

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

```bash theme={null}
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

<a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-custom#step-2-assemble-a-kubeconfig"}>Step 2</a>
and
<a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-custom#step-3-register-the-cluster"}>Step 3</a>
on the custom-clusters page. GKE Terraform:

```hcl theme={null}
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:

```bash theme={null}
kubectl exec -ti deploy/cloudxd -- asset-cli status k8s
```

The cluster should reach `RUNNING` within roughly 30 seconds.

## Related Topics

* <a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/kubernetes-prerequisites"}>Kubernetes Onboarding Prerequisites</a>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard"}>Onboarding Kubernetes Clusters</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>
* <a href={"/docs/enterprise/" + "10.1" + "/guides/security/dcf/kubernetes-onboard-custom"}>Onboard Self-Managed or Custom Clusters</a>