What is a Kubeconfig File & How to Create It [Tutorial]

What is a Kubeconfig File & How to Create It [Tutorial] [Virtual Event] IaCConf 2026: Real stories on how infra teams are keeping pace Register Now ➡️ Kubernetes What is a Kubeconfig File & How to Create It [Tutorial] James Walker Updated 24 Oct 2025 · 12 min read Reviewed by: Flavius Dinu Flavius Dinu Kubernetes is a container orchestration platform that enables you to manage and deploy applications across multiple clusters. However, interacting with these clusters requires authentication and configuration details, which is where kubeconfig files come into play. What we will cover: What is a Kubeconfig file? The benefits of using a Kubeconfig file Example Kubeconfig file How to create a Kubeconfig file? How to use a Kubeconfig file? Tip: Quickly switch contexts with kubectx How to manage Kubeconfig files? How to export and merge Kubeconfig files together Kubeconfig and security Tools to use with Kubeconfig files What is a Kubeconfig file? Kubeconfig are YAML files that configure Kubectl , the default Kubernetes client tool. These essential files define the cluster Kubectl commands will target and the user credentials they’ll authenticate with. Kubectl automatically loads the Kubeconfig file stored at ~/.kube/config . You can access multiple clusters with one Kubectl installation by specifying a different file, either by setting the KUBECONFIG environment variable or using Kubectl’s --kubeconfig flag: $ KUBECONFIG = /my/kubeconfig kubectl get pods $ kubectl get pods --kubeconfig /my/kubeconfig This approach is inconvenient when you have several different clusters, however. You need to remember the path to each Kubeconfig file and must specify it each time you run Kubectl . A better alternative is to merge your files into one, then use Kubectl’s built-in config management features to switch between clusters seamlessly. Let’s see how. The benefits of using a Kubeconfig file Switching to a single Kubeconfig file lets you more efficiently organize your Kubernetes cluster access. Here are some of the benefits you’ll gain: One file can contain all your clusters and users. No more duplication of Kubeconfig files each time you need to connect as a new user account, or register an additional cluster. You can quickly switch between configs by running Kubectl commands. Kubectl natively supports multiple config contexts within a single Kubeconfig file. The CLI includes commands for inspecting your active context and switching to another – we’ll see these below. You don’t have to remember to set KUBECONFIG or –kubeconfig every time you use Kubectl. Kubeconfig contexts you select within Kubectl are automatically persisted until you make another change. You don’t have to repeat the –kubeconfig flag with every command, or restore the value of KUBECONFIG after you reopen your terminal window. You can easily inspect the file to view the complete list of clusters you’ve used. Ever forgotten which clusters you have access to, or misplaced an important Kubeconfig file? This is a common problem for admins working with multiple clusters, where Kubeconfigs can become scattered across your storage drives. When you use a single file, you can view all your clusters in one location. These advantages mean a single Kubeconfig file is often the most effective option for Kubernetes developers and administrators. This doesn’t mean they’re always the best approach, though – in some situations, it can make sense to split up connections, such as when different files require unique security characteristics or are intended for specific situations. Example Kubeconfig file Below is an example of a Kubeconfig file. apiVersion : v1 clusters : - cluster : certificate-authority-data : LS0tL.. server : https : //127.0.0.1 : 64914 name : kind - kind - cluster : certificate-authority-data : LS0tLS1C.. server : https : //127.0.0.1 : 60963 name : kind - ope - cluster : certificate-authority : /Users/flaviuscdinu/.minikube/ca.crt extensions : - extension : last-update : Thu , 16 Feb 2023 14 : 50 : 26 EET provider : minikube.sigs.k8s.io version : v1.28.0 name : cluster_info server : https : //127.0.0.1 : 49731 name : minikube contexts : - context : cluster : kind - kind user : kind - kind name : kind - kind - context : cluster : kind - ope user : kind - ope name : kind - ope - context : cluster : minikube extensions : - extension : last-update : Thu , 16 Feb 2023 14 : 50 : 26 EET provider : minikube.sigs.k8s.io version : v1.28.0 name : context_info namespace : default user : minikube name : minikube current-context : minikube kind : Config preferences : { } users : - name : kind - kind user : client-certificate-data : LS0t… client-key-data : LS0t… - name : kind - ope user : client-certificate-data : LS0t.. client-key-data : LS0t… - name : minikube user : client-certificate : /Users/flaviuscdinu/.minikube/profiles/minikube/client.crt client-key : /Users/flaviuscdinu/.minikube/profiles/minikube/client.key In the Kubeconfig, you can define multiple cluster connections, including credentials and the default namespaces to use. Here are some of the attributes that can be configured: kind – specifies the object type, in this case: Config clusters – list of clusters that you can connect to (in our case, there are three clusters) contexts – different working environments for your cluster current-context – specifies the active context users – list of users that can access the clusters How to create a Kubeconfig file? Creating a Kubeconfig file involves defining the necessary parameters required for connecting to your cluster. Even though the majority of Kubernetes services have a mechanism for appending configuration data to your kubeconfig, you could still do it manually if you’d like. To do that, you need to: Identify cluster details (API Server URL, cluster name, user credentials, certificate authority data) Create a basic kubeconfig file in ~kube/config Include apiversion (v1) Include apiversion (v1): apiVersion : v1 Add the clusters attribute: apiVersion : v1 kind : Config Add the contexts attribute and the current context: apiVersion : v1 kind : Config clusters : - cluster : certificate-authority-data : my_ca_data server : my_server name : my_cluster contexts : - context : cluster : my_cluster user : user current-context : my_cluster Add the users: apiVersion : v1 kind : Config clusters : - cluster : certificate-authority-data : my_ca_data server : my_server name : my_cluster contexts : - context : cluster : my_cluster user : user current-context : my_cluster users : - name : my_cluster user : client-certificate-data : LS0t… client-key-data : LS0t… How to use a Kubeconfig file? Let’s go over the steps. 1. Add clusters to a Kubeconfig file Let’s get started adding some cluster connections to Kubeconfig. Use the config set-cluster command to register a new cluster. You must supply a name for the cluster, its API server URL, and the path to its TLS certificate authority file: $ kubectl config set-cluster production --server = https://1.1.1.1 --certificate-authority =~ /.kube/production.ca.crt Cluster "production" set. To add another cluster, simply repeat the command with different arguments: $ kubectl config set-cluster staging --server = https://2.2.2.2 --certificate-authority =~ /.kube/staging.ca.crt Cluster "staging" set. If you’re running a local cluster without TLS, you can disable TLS verification instead of supplying certificate authority data: $ kubectl config set-cluster staging --server = https://2.2.2.2 --insecure-skip-tls-verify Cluster "staging" set. View all the clusters present in your active Kubeconfig file with the config get-clusters command: $ kubectl config get-clusters NAME staging production 2. Add users to a Kubeconfig file Next you need to add user credentials for each of your clusters. The config set-credentials command registers credentials in several different formats. Specify the name of your new credentials entry as the command’s first argument. This name will be used to refer to the credentials when you link them to your cluster in the next step. Flags must also be set to supply the user’s authentication data. This example creates a user entry called production-admin that authenticates with a token: $ kubectl config set-credentials production-admin --token = cfrDHdb2 User "production-admin" set. Token-based auth is the correct method when your user is a service account created within Kubernetes. Use --username and --password instead if you’re using HTTP Basic Auth, or set --client-certificate and --client-key for certificate-based authentication . Repeat the command to add another user for your staging cluster: $ kubectl config set-credentials staging-admin --token = WLOBZKM7 User "staging-admin" set. After you’ve added your credentials, you can view them with the config get-credentials command: $ kubectl config get-users NAME production-admin staging-admin 3. Create Kubeconfig contexts Now you’re ready to link your clusters and credentials together as functioning configuration contexts. A context is a combination of cluster and credentials; Kubectl connects to the cluster specified by your selected context, using its configured credentials. Contexts are created by the config set-context command . Specify the name of your new context as the command’s argument, then set the --cluster and --user flags to reference the respective entries in your Kubeconfig file: $ kubectl config set-context production --cluster production --user production-admin Context "production" created. $ kubectl config set-context staging --cluster staging --user staging-admin Context "staging" created. You can view the contexts within your Kubeconfig file by running config get-contexts : $ kubectl config get-contexts CURRENT NAME CLUSTER AUTHINFO NAMESPACE production production production-admin staging staging staging-admin 💡 You might also like: 15 Kubernetes Best Practices to Follow How to Maintain Operations Around Kubernetes Cluster Common Infrastructure Challe