CoreWeave
Search
⌃K

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.
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.
Quickstart
To set up a CoreWeave kubeconfig on a system without an existing kubeconfig, see Get Started with CoreWeave.
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 System
Default 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:
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, use set:
> set KUBECONFIG=%USERPROFILE%\.kube\config-prod
To persist it in future sessions, use setx:
> setx KUBECONFIG %USERPROFILE%\.kube\config-prod /m
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")

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

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.
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, use set:
> set KUBECONFIG=%USERPROFILE%\.kube\config-prod;%USERPROFILE%\.kube\config-staging
To persist the environment in future sessions, use setx:
> setx KUBECONFIG %USERPROFILE%\.kube\config-prod;%USERPROFILE%\.kube\config-staging /m
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
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:
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"

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
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
Click to expand - config-staging
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:
Click to expand - config-merged
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".

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
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
Click to expand - my-cluster-staging
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.

Best practices for security

The kubeconfig contains authentication information 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: