Skip to content

Kubeconfig Authentication

First PublishedLast UpdatedByAtif Alam

Use this page when kubectl fails due to identity or trust issues and you need to validate kubeconfig authentication material quickly.

When This Applies

Section titled “When This Applies”

This page applies to kubeconfigs that use certificate-based client authentication fields such as:

  • certificate-authority-data
  • client-certificate-data
  • client-key-data

Some managed clusters use exec plugins (for example cloud IAM/OIDC token flows) instead of client certs. In those cases, these fields may be absent or secondary.

Kubeconfig TLS Identity Fields

Section titled “Kubeconfig TLS Identity Fields”

certificate-authority-data

Section titled “certificate-authority-data”

Base64-encoded PEM for the CA trusted by your client when connecting to the Kubernetes API server.

Purpose: lets kubectl verify it is talking to the real API server endpoint.

client-certificate-data

Section titled “client-certificate-data”

Base64-encoded PEM for your client certificate.

Purpose: identifies your client identity to the API server during mutual TLS authentication.

client-key-data

Section titled “client-key-data”

Base64-encoded private key for your client certificate.

Purpose: proves your client possesses the private key that matches the client certificate.

How They Work Together

Section titled “How They Work Together”
  1. Client verifies server identity using certificate-authority-data.
  2. Server validates the client certificate chain from client-certificate-data.
  3. Client proves private key possession using client-key-data.
  4. Authentication succeeds, then Kubernetes authorization (RBAC) decides what actions are allowed.

Operational rules:

  • client-certificate-data and client-key-data must be a matching pair.
  • certificate-authority-data must trust the cert chain presented by the configured server endpoint.
  • Treat all kubeconfig auth material as sensitive, especially client-key-data.

Minimal Kubeconfig Anatomy (Redacted)

Section titled “Minimal Kubeconfig Anatomy (Redacted)”
apiVersion: v1
kind: Config
clusters:
  - name: k3s-home
    cluster:
      server: https://10.0.0.60:6443
      certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
users:
  - name: k3s-home-user
    user:
      client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
      client-key-data: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQ...
contexts:
  - name: k3s-home
    context:
      cluster: k3s-home
      user: k3s-home-user
current-context: k3s-home

The active context decides which cluster and user entries are used. Editing the wrong block is a common source of auth failures.

Common Errors and What They Usually Mean

Section titled “Common Errors and What They Usually Mean”
ErrorLikely cause
the server has asked for the client to provide credentialsMissing, stale, or incorrect client auth material for active context
You must be logged in to the serverAuthentication failed for current context/user
tls: private key does not match public keyclient-certificate-data and client-key-data are not a matching pair
x509 / unknown authority errorsCA trust does not match API server cert chain

Fast Triage Commands

Section titled “Fast Triage Commands”
Terminal window
kubectl config get-contexts
kubectl config current-context
kubectl config view --minify
echo $KUBECONFIG
kubectl auth whoami

Also confirm the server endpoint in the active cluster block is reachable from where you run kubectl.

Safe Recovery Workflow

Section titled “Safe Recovery Workflow”
  1. Back up local config before changes.
  2. Pull authoritative kubeconfig from the control-plane source for this cluster.
  3. If required, adjust a loopback API endpoint (for example 127.0.0.1) to a reachable remote endpoint.
  4. Replace cluster + user auth blocks as a unit for the target context.
  5. Re-test using context, auth, and API checks.

Avoid partial edits like changing only client-certificate-data or only client-key-data.

Backup and Rollback Commands

Section titled “Backup and Rollback Commands”
Terminal window
ts=$(date +%Y%m%d-%H%M%S)
cp ~/.kube/config ~/.kube/config.bak.$ts


# If needed, rollback:
cp ~/.kube/config.bak.$ts ~/.kube/config

If your kubeconfig includes secrets, keep permissions strict:

Terminal window
chmod 600 ~/.kube/config

Post-Fix Validation Checklist

Section titled “Post-Fix Validation Checklist”
Terminal window
kubectl config use-context <context>
kubectl auth whoami
kubectl get --raw /version
kubectl get nodes
kubectl auth can-i get pods -A

Interpretation:

  • whoami confirms authentication identity.
  • can-i confirms authorization (RBAC) for the action.
  • API and node queries validate endpoint reachability plus practical access.

Common Follow-Up Questions

Section titled “Common Follow-Up Questions”

Why Can Auth Still Fail if CA Data Is Correct?

Section titled “Why Can Auth Still Fail if CA Data Is Correct?”

CA trust validates server identity only. You can still fail if client cert/key data is stale, mismatched, or mapped to the wrong context user.

How Do I Confirm Which User and Cluster My Context Uses?

Section titled “How Do I Confirm Which User and Cluster My Context Uses?”

Run kubectl config view --minify and check the context.cluster and context.user references, then inspect those exact entries in kubeconfig.

What if My Cluster Uses Exec or Token Auth Instead of Client Certs?

Section titled “What if My Cluster Uses Exec or Token Auth Instead of Client Certs?”

Look for user.exec or token-oriented configuration. Troubleshooting then focuses on plugin credentials, token freshness, and cloud identity bindings rather than cert/key pairs.

Exec auth: OIDC (generic)

Section titled “Exec auth: OIDC (generic)”

Many clusters authenticate humans via OIDC. The kubeconfig user.exec block calls a helper (for example kubectl oidc-login) that returns a short-lived bearer token.

Typical exec shape:

users:
  - name: oidc-user
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubectl-oidc-login
        args:
          - get-token
          - --oidc-issuer-url=https://idp.example.com
          - --oidc-client-id=kubernetes
          - --oidc-client-secret=<from env or file>

Groups claim — map IdP groups to Kubernetes groups so ClusterRoleBindings can target group:platform-admins. Mis-mapped claims are a common “I can log in but can-i says no” failure.

Validate end-to-end:

Terminal window
kubectl auth whoami
kubectl auth can-i list secrets -n team-a

For RBAC objects and blast-radius patterns, see RBAC.

Exec auth: Amazon EKS (aws eks get-token)

Section titled “Exec auth: Amazon EKS (aws eks get-token)”

EKS commonly uses the AWS CLI exec plugin:

users:
  - name: eks-prod
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: aws
        args:
          - eks
          - get-token
          - --cluster-name
          - my-cluster
          - --region
          - us-east-1

Failures usually mean expired AWS credentials, wrong region/cluster, or IAM lacking eks:DescribeCluster. Confirm with aws sts get-caller-identity and aws eks update-kubeconfig.

What Should I Do if client-key-data Is Exposed?

Section titled “What Should I Do if client-key-data Is Exposed?”

Treat it as credential compromise: rotate the affected client credential material, update kubeconfigs from the new source of truth, and invalidate old access paths as your platform policy requires.

Section titled “Related Pages”