Comment on page
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
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.
This location is used unless overridden by another option.
Operating System | Default path |
|---|---|
Linux | ~/.kube/config |
macOS | /Users/<username>/.kube/config |
Windows | %USERPROFILE%\.kube\config |
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:Linux or macOS
Windows cmd
Windows PowerShell
$ export KUBECONFIG=~/.kube/config-prod
Add this to the shell profile to make it persistent.
For the current session:
> $env:KUBECONFIG = "$env:USERPROFILE\.kube\config-prod"
To persist it in future sessions, run this in an administrative PowerShell:
> [Environment]::SetEnvironmentVariable("KUBECONFIG", $env:USERPROFILE + "\.kube\config-prod", "Machine")
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.Linux or macOS
Windows cmd or PowerShell
$ kubectl get secret --kubeconfig ~/Downloads/cw-kubeconfig
> kubectl get secret --kubeconfig %USERPROFILE%\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.
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.
Linux or macOS
Windows cmd
Windows PowerShell
$ export KUBECONFIG=~/.kube/config-prod:~/.kube/config-staging
Add this to the shell profile to make it persistent.
For the current session:
> $env:KUBECONFIG = "$env:USERPROFILE\.kube\config-prod;$env:USERPROFILE\.kube\config-staging"
To persist it in future sessions, run this in an administrative PowerShell:
> [Environment]::SetEnvironmentVariable("KUBECONFIG", $env:USERPROFILE + "\.kube\config-prod;" + $env:USERPROFILE + "\.kube\config-staging", "Machine")
Warning
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:
Linux or macOS
Windows cmd
Windows PowerShell
1
$ export KUBECONFIG=~/.kube/config-prod:~/.kube/config-staging
2
$ kubectl config view --flatten > ~/.kube/config-merged
3
$ export KUBECONFIG=~/.kube/config-merged
1
> set KUBECONFIG=%USERPROFILE%\.kube\config-prod;%USERPROFILE%\.kube\config-staging
2
> kubectl config view --flatten > %USERPROFILE%\.kube\config-merged
3
> set KUBECONFIG=%USERPROFILE%\.kube\config-merged
1
> $env:KUBECONFIG = "$env:USERPROFILE\.kube\config-prod;$env:USERPROFILE\.kube\config-staging"
2
> kubectl config view --flatten > %USERPROFILE%\.kube\config-merged
3
> $env:KUBECONFIG = "$env:USERPROFILE\.kube\config-merged"
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".
Context name conflicts must be resolved before merging Kubeconfigs. To illustrate the issue, here are two files with conflicting context names.
1
apiVersion: v1
2
kind: Config
3
clusters:
4
- cluster:
5
certificate-authority-data: DATA+OMITTED
6
server: https://prod.example.com
7
name: prod-cluster
8
contexts:
9
- context:
10
cluster: prod-cluster
11
namespace: prod-namespace
12
user: prod-user
13
name: my-context
14
current-context: my-context
15
users:
16
- name: prod-user
17
user:
18
token: REDACTED
1
apiVersion: v1
2
kind: Config
3
clusters:
4
- cluster:
5
certificate-authority-data: DATA+OMITTED
6
server: https://staging.example.com
7
name: staging-cluster
8
contexts:
9
- context:
10
cluster: staging-cluster
11
namespace: staging-namespace
12
user: staging-user
13
name: my-context
14
current-context: my-context
15
users:
16
- name: staging-user
17
user:
18
token: REDACTED
19
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:Linux or macOS
Windows
$ 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".
> kubectl config rename-context my-context prod-context --kubeconfig %USERPROFILE%\.kube\config-prod
Context "my-context" renamed to "prod-context".
> kubectl config rename-context my-context staging-context --kubeconfig %USERPROFILE%\.kube\config-staging
Context "my-context" renamed to "staging-context".
Next, merge the files.
Linux or macOS
Windows cmd
Windows PowerShell
$ export KUBECONFIG=~/.kube/config-prod:~/.kube/config-staging
$ kubectl config view --flatten > ~/.kube/config-merged
> set KUBECONFIG=%USERPROFILE%\.kube\config-prod;%USERPROFILE%\.kube\config-staging
> kubectl config view --flatten > %USERPROFILE%\.kube\config-merged
> $env:KUBECONFIG = "$env:USERPROFILE\.kube\config-prod;$env:USERPROFILE\.kube\config-staging"
> kubectl config view --flatten > %USERPROFILE%\.kube\config-merged
The result:
1
apiVersion: v1
2
kind: Config
3
clusters:
4
- cluster:
5
certificate-authority-data: DATA+OMITTED
6
server: https://prod.example.com
7
name: prod-cluster
8
- cluster:
9
certificate-authority-data: DATA+OMITTED
10
server: https://staging.example.com
11
name: staging-cluster
12
contexts:
13
- context:
14
cluster: prod-cluster
15
namespace: prod-namespace
16
user: prod-user
17
name: prod-context
18
- context:
19
cluster: staging-cluster
20
namespace: staging-namespace
21
user: staging-user
22
name: staging-context
23
current-context: prod-context
24
users:
25
- name: prod-user
26
user:
27
token: REDACTED
28
- name: staging-user
29
user:
30
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".
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.
1
apiVersion: v1
2
kind: Config
3
clusters:
4
- cluster:
5
certificate-authority-data: DATA+OMITTED
6
server: https://prod.example.com
7
name: my-cluster
8
contexts:
9
- context:
10
cluster: my-cluster
11
namespace: prod-namespace
12
user: prod-user
13
name: prod-context
14
current-context: prod-context
15
users:
16
- name: prod-user
17
user:
18
token: REDACTED
1
apiVersion: v1
2
kind: Config
3
clusters:
4
- cluster:
5
certificate-authority-data: DATA+OMITTED
6
server: https://staging.example.com
7
name: my-cluster
8
contexts:
9
- context:
10
cluster: my-cluster
11
namespace: staging-namespace
12
user: staging-user
13
name: my-context
14
current-context: my-context
15
users:
16
- name: staging-user
17
user:
18
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.
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 600to 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.
For more information about Kubeconfig files, see the resources at kubernetes.io:
Last modified 1mo ago