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:

Example
$
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.

Example
$
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.

Example
$
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:

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:

Example
$
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:

Example
$
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
{13} showLineNumbers
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
{13} showLineNumbers
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:

Example
$
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.

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

$
kubectl config view --flatten > ~/.kube/config-merged

The result:

Click to expand - config-merged
{17,22} showLineNumbers
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:

Example
$
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
{7,10} showLineNumbers
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
{7,10} showLineNumbers
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:

Last updated on