Guide to Managing Multiple Kubernetes Clusters with kubectl config

Managing multiple Kubernetes clusters is normal once you have development, staging, production, or clusters in more than one cloud. The risk is simple: one command can hit the wrong cluster if your context is not clear.

This guide shows you how to use kubectl config to inspect contexts, switch clusters, set namespaces, and organize multiple kubeconfig files.

Understanding the Kubeconfig File

Before diving into kubectl config commands, it's essential to understand the kubeconfig file. This file stores information about your clusters, users, and the contexts that bind them together. kubectl uses this file to authenticate with and specify which cluster to interact with. By default, kubectl looks for the kubeconfig file at $HOME/.kube/config.

Within this file, you'll find three main sections:

• clusters: Defines the Kubernetes clusters, including their API server endpoints and certificate authorities.
• users: Stores authentication credentials, such as client certificates and tokens.
• contexts: Associates a cluster, a user, and optionally a namespace. A context provides a convenient way to group these configurations, allowing kubectl to switch between different cluster/user combinations easily.

Managing Contexts with kubectl config

Contexts are the primary way kubectl manages your connection to different Kubernetes clusters. They act as shortcuts, allowing you to switch between them with a single command.

Viewing Available Contexts

To see all the contexts available in your current kubeconfig file, use the following command:

kubectl config get-contexts

This command will output a list of contexts, along with the cluster, user, and namespace associated with each. The currently active context will be marked with an asterisk (*).

Example Output:

CURRENT   NAME                 CLUSTER              AUTHINFO       NAMESPACE
*         my-dev-context       my-dev-cluster       dev-user       default
          my-prod-context      my-prod-cluster      prod-user      production
          staging-context      staging-cluster      staging-user   staging

Getting the Current Context

To quickly check which context you are currently using, run:

kubectl config current-context

This will output the name of the active context.

Switching Contexts

Switching to a different context is straightforward. Use the use-context subcommand followed by the name of the context you wish to activate:

kubectl config use-context <context-name>

For instance, to switch to the my-prod-context from the example above:

kubectl config use-context my-prod-context

After executing this command, subsequent kubectl commands will be directed to the cluster specified in my-prod-context.

Setting a Context

You can also set a specific context for a cluster and user without necessarily making it the default for future use. This is useful for temporary operations.

kubectl config set-context <context-name> --cluster=<cluster-name> --user=<user-name> --namespace=<namespace-name>

If you omit --namespace, the default namespace of the cluster will be used.

Managing Clusters and Users

While contexts are used for switching, you can also directly manage the cluster and user configurations that contexts refer to.

Viewing Cluster Information

To list all configured clusters:

kubectl config get-clusters

To view details of a specific cluster:

kubectl config view --minify -o jsonpath='{.clusters[?(@.name=="<cluster-name>")].cluster}'

Replace <cluster-name> with the actual name of your cluster.

Viewing User Information

To list all configured users:

kubectl config get-users

Adding and Modifying Configurations

You can add new clusters, users, and contexts, or modify existing ones:

• Add a new cluster:

  kubectl config set-cluster <cluster-name> --server=<api-server-url> --certificate-authority=<path-to-ca-file> --embed-certs=true
  

• Add a new user:

  kubectl config set-credentials <user-name> --client-certificate=<path-to-cert-file> --client-key=<path-to-key-file> --embed-certs=true
  

• Add a new context:

  kubectl config set-context <context-name> --cluster=<cluster-name> --user=<user-name> --namespace=<namespace-name>
  

Managing Multiple Kubeconfig Files

For enhanced security and organization, especially when dealing with many clusters or sensitive credentials, it's a good practice to keep your kubeconfig files separate. kubectl can manage multiple kubeconfig files using the KUBECONFIG environment variable or the --kubeconfig flag.

Using the KUBECONFIG Environment Variable

You can specify a list of kubeconfig files to load. kubectl merges these files. If the same named cluster, user, or context appears in more than one file, merge precedence depends on the order of files in KUBECONFIG, so use unique names to avoid surprises.

To set this variable for your current shell session:

export KUBECONFIG=~/.kube/config:~/.kube/config-dev:~/.kube/config-prod

To make this persistent, add the export line to your shell's profile file (e.g., ~/.bashrc, ~/.zshrc).

Using the --kubeconfig Flag

Alternatively, you can specify a particular kubeconfig file for a single kubectl command:

kubectl --kubeconfig=~/.kube/config-dev get pods

This is useful for one-off commands or when you want to be absolutely sure which file is being used.

Best Practices for Multi-Cluster Management

• Use Separate Files: Store configurations for different environments (dev, staging, prod) or cloud providers in distinct kubeconfig files (e.g., config-dev, config-staging, config-prod).
• Leverage KUBECONFIG: Set the KUBECONFIG environment variable in your shell profile to easily merge and manage multiple files without manual merging.
• Descriptive Context Names: Use clear and descriptive names for your contexts (e.g., aws-prod-us-east-1, gke-dev-eu-west-2) to avoid confusion.
• Namespace Awareness: Always be mindful of the namespace you are operating in. Use --namespace flag or set it in your context to target the correct namespace.
• Regularly Audit: Periodically review your contexts and cluster configurations to ensure they are up-to-date and secure.
• Secure Your Kubeconfig: Treat your kubeconfig files as sensitive credentials. Restrict file permissions and avoid committing them to version control.

Final Takeaway

Make context checks part of your workflow. Run kubectl config current-context before risky commands, use descriptive context names, set namespaces intentionally, and keep production credentials out of casual shell sessions when you do not need them.