Skip to main content

GKE Kubeconfig Authentication: Native kubectl and Helm Access Without gcloud

· 3 min read
Mikhail Shirkov
Mikhail Shirkov
Senior Engineer @ NXT:FWD

Using an Atmos-managed GCP identity with GKE used to stop one step short of the cluster. The identity could authenticate Terraform and other GCP clients, but operators still needed gcloud or gke-gcloud-auth-plugin to discover the cluster, write kubeconfig, and refresh Kubernetes credentials. Atmos now handles that complete path itself.

The Problem​

Atmos Auth already supports Application Default Credentials, Workload Identity Federation, and service account impersonation. GKE access still required a separate authentication flow outside Atmos, though. That created two sources of truth for identity selection and added external tools to local and CI environments solely to prepare kubeconfig.

The gap was especially visible with native Helm components: Atmos could resolve the intended GCP identity, but an ambient kubeconfig could still point Helm at a different cluster.

The Fix​

The new gcp/gke Auth integration links a GKE cluster to an existing GCP identity. When Atmos selects that identity, it uses the GKE API to discover the cluster endpoint and CA certificate, writes an Atmos-managed kubeconfig, and injects its path into child commands:

auth:
  providers:
    example-gcp:
      kind: gcp/adc
      spec:
        project_id: example-project

  identities:
    example-deployer:
      kind: gcp/project
      via:
        provider: example-gcp
      principal:
        project_id: example-project

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

Run Kubernetes tools through the selected identity without a preparatory gcloud command:

atmos auth exec --identity example-deployer -- kubectl get nodes

The generated kubeconfig uses atmos gcp gke token as a Kubernetes exec credential plugin. Kubernetes requests a fresh short-lived token when needed; the token and its expiration are returned as ExecCredential JSON and are never stored in kubeconfig.

Guard Native Helm Targets​

Native Helm keeps its existing ambient-kubeconfig behavior by default. Components that must use an Atmos-provisioned GKE identity can opt into a fail-closed endpoint check:

components:
  helm:
    example-release:
      auth:
        require_identity: true
        identities:
          example-deployer:
            default: true

For live plan, apply, and delete operations, Atmos provisions the linked integration and verifies that Helm's effective Kubernetes API endpoint matches the endpoint returned by GKE before any cluster request. Offline template and manifest-baseline operations remain credential-free.

Security Boundaries​

  • The kubeconfig stores the HTTPS endpoint, CA certificate, context, and exec-plugin command—not a bearer token.
  • The GCP identity needs permission to describe the cluster, normally container.clusters.get.
  • Kubernetes RBAC remains separate and determines what the authenticated principal may do inside the cluster.
  • Explicit plaintext GKE API endpoints are rejected rather than written to kubeconfig.

See the GKE kubeconfig authentication command documentation for configuration, update modes, permissions, and troubleshooting details.

Get Involved​

Try the integration with your GCP identity chain and GKE clusters. Share feedback in the Cloud Posse community or open an issue on GitHub.