Skip to main content

Advanced Kubeconfig Environments

How to integrate multiple kubeconfig files and resolve conflicts

Kubeconfig is a YAML file that contains information about the cluster's API server, namespace, and user authentication.

Quickstart

To set up a system without an existing Kubeconfig, see Get Started with Kubernetes.

This guide explains the order of precedence when using multiple Kubeconfigs, how to integrate a new CoreWeave Kubeconfig with an existing Kubeconfig, the steps to resolve name conflicts, how to use multiple contexts and namespaces as a single environment, and best security practices.

Kubernetes tools like kubectl, Helm, and Argo Workflows follow an order of precedence to locate the active Kubeconfig.

Lowest priority: Default location​

This location is used unless overridden by another option.

Operating SystemDefault path
Linux~/.kube/config
macOS/Users/<username>/.kube/config
Windows%USERPROFILE%\.kube\config

Next priority: Environment variable​

The KUBECONFIG environment variable overrides the default location by pointing to one or more Kubeconfig files. For a single file named config-prod, the syntax is:

$ export KUBECONFIG=~/.kube/config-prod

Add this to the shell profile to make it persistent.

Highest priority: Command line​

The --kubeconfig command line option has the highest priority; all other Kubeconfigs are ignored. For example, to use a cw-kubeconfig file in the Downloads directory to request the secret objects.

$ kubectl get secret --kubeconfig ~/Downloads/cw-kubeconfig

Although this isn't convenient for normal use, it's a good way to test a new Kubeconfig without changing the existing configuration.

Merge multiple files with the environment variable​

To merge multiple files, list them in the environment variable separated with a colon on Linux and macOS, or a semicolon on Windows. The files are used in the specified order and the first file takes precedence.

$ export KUBECONFIG=~/.kube/config-prod:~/.kube/config-staging

Add this to the shell profile to make it persistent.

warning

Resolve any name conflicts before merging the files as explained below.

How to physically merge files​

To physically merge multiple Kubeconfigs into a single file, add them in the environment as before. Then, use the --flatten option, redirect the output to a new file, and use the merged file as the new Kubeconfig.

Example:

$ export KUBECONFIG=~/.kube/config-prod:~/.kube/config-staging
$ kubectl config view --flatten > ~/.kube/config-merged
$ export KUBECONFIG=~/.kube/config-merged

How to use multiple contexts​

A merged Kubeconfigs has multiple contexts, each defining a specific cluster, user, and namespace combination.

View the available contexts with kubectl:

$ kubectl config get-contexts
CURRENT   NAME      CLUSTER           AUTHINFO       NAMESPACE
-         prod      prod-cluster      prod-user      prod-namespace
          staging   staging-cluster   staging-user   staging-namespace

Use kubectl to switch contexts:

$ kubectl config use-context staging
Switched to context "staging".

Resolve context name conflicts​

Context name conflicts must be resolved before merging Kubeconfigs. To illustrate the issue, here are two files with conflicting context names.

Click to expand - config-prod
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://prod.example.com
  name: prod-cluster
contexts:
- context:
    cluster: prod-cluster
    namespace: prod-namespace
    user: prod-user
  name: my-context
current-context: my-context
users:
- name: prod-user
  user:
    token: REDACTED
Click to expand - config-staging
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://staging.example.com
  name: staging-cluster
contexts:
- context:
    cluster: staging-cluster
    namespace: staging-namespace
    user: staging-user
  name: my-context
current-context: my-context
users:
- name: staging-user
  user:
    token: REDACTED

Both files have the same context name on line 13. These will conflict when merged.

First, use kubectl to rename the context in each file:

$ kubectl config rename-context my-context prod-context --kubeconfig ~/.kube/config-prod
Context "my-context" renamed to "prod-context".

$ kubectl config rename-context my-context staging-context --kubeconfig ~/.kube/config-staging
Context "my-context" renamed to "staging-context".

Next, merge the files.

$ export KUBECONFIG=~/.kube/config-prod:~/.kube/config-staging
$ kubectl config view --flatten > ~/.kube/config-merged

The result:

Click to expand - config-merged
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://prod.example.com
  name: prod-cluster
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://staging.example.com
  name: staging-cluster
contexts:
- context:
    cluster: prod-cluster
    namespace: prod-namespace
    user: prod-user
  name: prod-context
- context:
    cluster: staging-cluster
    namespace: staging-namespace
    user: staging-user
  name: staging-context
current-context: prod-context
users:
- name: prod-user
  user:
    token: REDACTED
- name: staging-user
  user:
    token: REDACTED

The contexts on lines 17 and 22 no longer conflict.

Switching contexts is the same for all operating systems:

$ kubectl config use-context prod-context
Switched to context "prod-context".

$ kubectl config use-context staging-context
Switched to context "staging-context".

Resolve cluster name conflicts​

Cluster names can also occasionally conflict. A cluster name is arbitrary and can be anything unique and meaningful. However, unlike context names, there isn't a kubectl command available to rename clusters, so they must be edited manually.

Here are two files with conflicting cluster names for illustration.

Click to expand - my-cluster-prod
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://prod.example.com
  name: my-cluster
contexts:
- context:
    cluster: my-cluster
    namespace: prod-namespace
    user: prod-user
  name: prod-context
current-context: prod-context
users:
- name: prod-user
  user:
    token: REDACTED
Click to expand - my-cluster-staging
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://staging.example.com
  name: my-cluster
contexts:
- context:
    cluster: my-cluster
    namespace: staging-namespace
    user: staging-user
  name: my-context
current-context: my-context
users:
- name: staging-user
  user:
    token: REDACTED

The cluster name on line 7 is the same in both files. If merged, the first file's API server is used and the second file's context is broken.

To fix this, edit the cluster name in each file to make them unique. Make sure to edit the cluster reference in the context section so it matches also; it's line 10 in this example.

Best practices for security​

The Kubeconfig contains access tokens that should be treated with the same care as passwords or SSH keys.

  • Make sure only the file owner can read and write the Kubeconfig file. For example, on Linux or macOS, use chmod 600 to set the appropriate permissions.
  • Avoid storing the Kubeconfig in version control.
  • Use separate Kubeconfigs for different users and applications, instead of sharing a single kubeconfig among multiple users or apps.
  • Regularly rotate Kubeconfig files and revoke access for users or applications that no longer need it, to reduce the risk of credential leakage.

Other references​

For more information about Kubeconfig files, see the resources at kubernetes.io: