Skip to main content

GKE kubeconfig authentication

Configure a GKE kubeconfig whose short-lived access tokens are supplied dynamically by Atmos Auth. No gcloud, Application Default Credentials bootstrap, or external GKE authentication plugin is required.

Usage​

atmos gcp gke <subcommand> [flags]

Examples​

atmos gcp gke token --identity example-deployer

Configuration​

auth:
  integrations:
    example-gke:
      kind: gcp/gke
      via:
        identity: example-deployer
      spec:
        cluster:
          name: example-cluster
          project_id: example-project
          location: us-central1
          alias: example
          kubeconfig:
            update: merge

The cluster name, project_id, and regional or zonal location are required. With no custom path, Atmos writes its own kubeconfig under the XDG config directory. kubeconfig.update supports merge (the default), replace, and error. Configuring a shared kubeconfig path is explicit opt-in and may update that file's current-context.

Use the integration​

Selecting the linked identity provisions the kubeconfig and contributes KUBECONFIG and KUBE_CONFIG_PATH to the child environment:

atmos auth exec --identity example-deployer -- kubectl get namespaces
atmos helm plan example-release --stack example-stack --identity example-deployer

The same composed identity environment is available to native Helm, Kubernetes, Helmfile, kubectl subprocesses, and workflows.

For an opt-in Helm safety guard, set require_identity: true and select a default identity in the GKE component's auth block:

components:
  helm:
    example-release:
      auth:
        require_identity: true
        identities:
          example-deployer:
            default: true
        integrations:
          example-gke:
            kind: gcp/gke
            via:
              identity: example-deployer
            spec:
              cluster:
                name: example-cluster
                project_id: example-project
                location: us-central1

With the guard enabled, Atmos resolves the component default even when --identity is omitted, refuses the mutation if no GKE endpoint was provisioned, and verifies that the effective Kubernetes REST endpoint matches the endpoint returned by GKE. The flag is off by default and does not change existing EKS or AKS behavior.

If you use a custom blocking Helm hook instead, set on_failure: fail; command hooks otherwise warn and allow execution to continue. Hooks run from the component directory, so resolve repository scripts to an absolute path rather than assuming the repository root is the working directory.

How it works​

Atmos calls the GKE API for projects/{project}/locations/{location}/clusters/{name} using the resolved identity's access token. It writes only the Kubernetes API endpoint, cluster CA, context, and this exec plugin to kubeconfig:

atmos gcp gke token --identity example-deployer

Kubernetes invokes the command whenever it needs a fresh credential. The access token and expiration are returned as Kubernetes ExecCredential JSON and are never persisted in kubeconfig.

Cluster discovery is deduplicated per process using the cluster and all kubeconfig output settings. Bulk commands that target the same integration therefore make one describe request, while distinct paths, aliases, update modes, or identities are provisioned separately.

GKE is an Auth integration rather than a Kubernetes identity because the GCP identity remains the source credential and the kubeconfig is derived client configuration. Kubernetes RBAC remains independently required after Google authenticates the caller.

This integration and its endpoint guard cover GKE only. Other cluster types continue to use their existing effective kubeconfig behavior.

Permissions​

The identity must be able to describe the cluster, normally with container.clusters.get, and its provider must be able to obtain or refresh a GCP OAuth2 access token. Kubernetes roles and role bindings still determine what that identity may do inside the cluster.

See also​