Skip to main content
In this lesson we examine kubeconfig files — the configuration kubectl uses to find clusters and present credentials to the Kubernetes API. You’ve already seen how to create a client certificate and use it with curl to authenticate directly against the API server. Kubeconfig files store that same information so you don’t have to type it on the command line every time. For example, if your cluster API server is reachable at my-kube-playground:6443, you can use curl with the client certificate/key pair (and the CA certificate) to query the API:
kubectl can send the same credentials to the API server. You can pass the server and certificate options directly to kubectl:
Typing all of those flags every time is tedious. Instead, place the server, CA, and client credentials in a kubeconfig file and point kubectl at it. By default, kubectl looks for the kubeconfig at ~/.kube/config. If you create the file there, you do not need to pass --kubeconfig on the command line.
By default, kubectl uses the file at ~/.kube/config. You can override this with --kubeconfig=<path> or by setting the KUBECONFIG environment variable.

​
What is in a kubeconfig?

A kubeconfig is a YAML file with three primary sections:
  • clusters: Definitions of Kubernetes API servers (endpoints + CA information).
  • users: Credentials (client identities) used to authenticate to clusters.
  • contexts: Mappings that tie a user to a cluster and optionally a namespace.
Important: creating entries in a kubeconfig does not create objects inside a cluster — it only tells kubectl which credentials to present to which API server. Quick overview table How the earlier curl/kubectl example maps to kubeconfig:
  • The API server address and CA certificate belong in a clusters entry.
  • The admin user’s key and certificate belong in a users entry.
  • A context maps the my-kube-admin user to the my-kube-playground cluster so kubectl can pick them together.

​
Example kubeconfig (simplified)

A real kubeconfig might look like this:

​
Which context does kubectl use?

Set a default context with current-context at the top level of the kubeconfig:
If current-context is set to dev-user@google, kubectl will use the dev-user credentials against the google cluster by default — unless you override this on the command line.

​
Viewing and switching contexts

Use kubectl subcommands to view and modify kubeconfig files.
  • Print the kubeconfig kubectl is currently using:
  • Ask kubectl to read a different file:
  • Change the current context:
After switching, kubectl config view will show current-context: prod-user@production. You can also add, delete, and update kubeconfig entries with other kubectl config subcommands — see kubectl config --help for details.

​
Namespaces in contexts

Each context can include a namespace field so kubectl commands default to that namespace when the context is active:
With the admin@production context active, kubectl commands run without -n will operate in the finance namespace by default.

​
File paths vs. inline data for certificates

Kubeconfig supports two ways to provide certificate credentials:
  1. File paths
    • Fields: certificate-authority, client-certificate, client-key
    • Example: certificate-authority: /etc/kubernetes/pki/ca.crt
  2. Inline base64-encoded contents
    • Fields: certificate-authority-data, client-certificate-data, client-key-data
    • The value must be the base64 encoding of the file contents (no newlines).
Using the inline *-data fields is convenient for a single portable kubeconfig that contains all credentials, but embedding secrets in a file increases risk if the file is exposed.
Embedding client keys or certificates directly in a kubeconfig (*-data fields) makes the file self-contained but also increases the risk of credential leakage. Protect files containing credentials using OS-level file permissions and secure storage.
Example cluster entry using inline CA data:
Convert a certificate file to base64:
Decode base64 data back to a certificate:
(Ensure you use straight single quotes or double quotes rather than “smart quotes”.)

​
Summary

  • Kubeconfig centralizes cluster endpoints and user credentials for kubectl.
  • The file contains clusters, users, and contexts sections; current-context selects the default.
  • Contexts map a user to a cluster and can set a default namespace.
  • Certificates can be referenced by file path or embedded as base64 data via *-data fields.
  • kubectl provides kubectl config subcommands to view and modify kubeconfig files.

​
Practice

Create multiple contexts for different clusters/users, switch between them with kubectl config use-context, and experiment with both file-based and inline credentials to learn the trade-offs. Example of decoding a certificate (corrected):

Watch Video

Practice Lab