What is a Kubeconfig file?<\/h2>\n
A Kubeconfig is a YAML file<\/strong> with all the Kubernetes cluster<\/a> details, certificates, and secret tokens to authenticate the cluster. You might get this config file directly from the cluster administrator or from a cloud platform if you are using a managed Kubernetes cluster.<\/p>\n When you use Not just users, any cluster component that need to authenticate to the kubernetes API server need the kubeconfig file.<\/p>\n For example, kubernetes cluster components<\/a> like controller manager, scheduler and kubelet use the kubeconfig files to interact with the API server.<\/p>\n All the cluster Kubeconfig files are present in the control plane Check out our CKA course and practice test bundle<\/a> (Use code DCUBE25<\/strong><\/b> to get 25% OFF today).<\/p>\n We explain concepts using illustrations, hands-on exercises, real-world examples, and provide dedicated discord based user support.<\/p><\/div>\n<\/div>\n Here is an example of a Kubeconfig. It needs the following key information to connect to the Kubernetes clusters.<\/p>\n You can use the k Here is the precedence in order.<\/p>\n Now let’s take a look at all three ways to use the Kubeconfig file.<\/strong><\/p>\n To connect to the Kubernetes cluster, the basic prerequisite is the Kubectl CLI plugin. If you don’t have the CLI installed, follow the instructions given here<\/a>.<\/p>\n Now follow the steps given below to use the kubeconfig file to interact with the cluster.<\/p>\n Kubectl interacts with the kubernetes cluster using the details available in the Kubeconfig file. By default, kubectl looks for the config file in the Let’s move the kubeconfig file to the .kube directory. Replace You can have any number of kubeconfig in the Now you need to set the current context<\/a> to your kubeconfig file. You can set that using the following command. replace For example,<\/p>\n To validate the cluster connectivity, you can execute the following kubectl command to list the cluster nodes.<\/p>\n You can set the You can set the variable using the following command. Where You can pass the Kubeconfig file with the Kubectl command to override the current context and KUBECONFIG env variable.<\/p>\n Here is an example to get nodes.<\/p>\n Also, you can use,<\/p>\n Usually, when you work with multiple Kubernetes clusters, all the cluster contexts get added as a single file. <\/p>\n However, there are situations where you will be given a To manage all clusters effectively using a single config, you can merge the other Kubeconfig files to the default Let’s assume you have three Kubeconfig files in the You can merge all three configs into a single file using the following command. Ensure you are running the command from the The above command creates a merged config named Now rename the old Rename the To verify the configuration, try listing the contexts from the config.<\/p>\n If you want to view the kubeconfig file in a condensed format to analyze all the configurations, you can use the following minify command.<\/p>\n There are scenarios where you might have context added to the kubeconfig file and the cluster gets deleted.<\/p>\n In this scenario, you might want to remove the context from the Kubeconfig file. Here is how you can do it.<\/p>\n First, list the contexts.<\/p>\n Get the context name and delete it using the following command. Replace <context-name><\/strong> with your context name.<\/p>\n You can set a new context of existing clusters using,<\/p>\n There are scenarios in real time project environments where you need to provide Kubeconfig files to developers or other teams to connect to clusters for specific use cases. It could be user access or for apps.<\/p>\n Now we will look at creating Kubeconfig files using the serviceaccount method. serviceaccount is the default user type managed by Kubernetes API.<\/p>\n A kubeconfig needs the following important details.<\/p>\n For this demo, I am creating a service account with The service account name will be the user name in Kubeconfig. Here I am creating the service account in the From Kubernetes Version 1.24, the secret for the service account has to be created separately with an annotation Let’s create a secret named devops-cluster-admin-secret<\/strong> with the annotation and type.<\/p>\n Let’s create a If you want to create a namespace-scoped role, refer to creating service account with role<\/a>.<\/p>\n Execute the following command to create the clusterRole.<\/p>\n The following YAML is a ClusterRoleBinding that binds the We will retrieve all the required kubeconfig details and save them in variables. Then, finally, we will substitute it directly with the Kubeconfig YAML.<\/p>\n If you have used a different secret name, replace If you execute the following YAML, all the variables get substituted and a config named To validate the Kubeconfig, execute it with the kubectl command to see if the cluster is getting authenticated.<\/p>\n Additionally, other services, such as OIDC<\/a> (OpenID Connect), can be used to manage users and create kubeconfig files that limit access to the cluster based on specific security requirements.<\/div>\n<\/div>\n Always ensure you follow the following security best practices for Kubeconfig files.<\/p>\n Your kubeconfig file holds sensitive details like tokens and certificates, so it should only be accessible to you. Make sure you’re the only one who can read or modify it.<\/p>\n If your Kubeconfig file is not secure, you will get the following error while using kubectl.<\/p>\n Using the following commands, you can set and verify restrictive permissions.<\/p>\n You can also lock down the entire If you\u2019re working in a Git repo, avoid committing sensitive kubeconfig files by adding it to the Let’s look at some of the frequently asked Kubeconfig file questions.<\/p>\n The default Kubeconfig file location is All the kubeconfig files are located in the .kube directory in the user home directory. That is You can store all the kubeconfig files in To create a Kubeconfig file, you need to have the cluster endpoint details, cluster CA certificate, and authentication token. Then you need to create a Kubernetes YAML object of type config with all the cluster details.<\/p>\n If you are behind a corporate proxy, you can use In this blog, we learned different ways to connect to the Kubernetes cluster using a custom Kubeconfig file.<\/p>\n If you are learning Kubernetes, check out the comprehensive list of kubernetes tutorials for beginners<\/a><\/p>\n If you are interested in Kubernetes certification check out the best kubernetes certifications<\/a> guide that helps you choose the right Kubernetes certification based on your domain competencies.<\/p>\nkubectl<\/code>, it uses the information in the kubeconfig file to connect to the kubernetes cluster API. The default location of the Kubeconfig file is $HOME\/.kube\/config<\/code><\/p>\n![\"\"](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/05\/image-55.png\")
\/etc\/kubernetes<\/strong><\/code> folder (.conf<\/code> files).<\/p>\nExample Kubeconfig File<\/h2>\n
\n
apiVersion: v1\nclusters:\n- cluster:\n certificate-authority-data: <ca-data-here>\n server: https:\/\/your-k8s-cluster.com\n name: <cluster-name>\ncontexts:\n- context:\n cluster: <cluster-name>\n user: <cluster-name-user>\n name: <cluster-name>\ncurrent-context: <cluster-name>\nkind: Config\npreferences: {}\nusers:\n- name: <cluster-name-user>\n user:\n token: <secret-token-here>\n<\/code><\/pre>\nKubeconfig File Usage<\/h2>\n
ubeconfig<\/code> in different ways and each way has its own precedence. <\/p>\n\n
Method 1: Using Kubeconfig with Kubectl Context<\/h3>\n
Step 1: Move kubeconfig to .kube directory.<\/h4>\n
\/.kube<\/code> location.<\/p>\n\/path\/to\/kubeconfig<\/code> with your kubeconfig current path.<\/p>\nmv \/path\/to\/kubeconfig ~\/.kube<\/code><\/pre>\nStep 2: List all cluster contexts<\/h4>\n
.kube<\/code> directory. Each config will have a unique context name (ie, the name of the cluster). You can validate the Kubeconfig file by listing the contexts. You can list all the contexts using the following command. It will list the context name as the name of the cluster.<\/p>\nkubectl config get-contexts -o=name<\/code><\/pre>\nStep 3: Switch Kubernetes contex<\/h4>\n
<cluster-name><\/code> with your listed context name.<\/p>\nkubectl config use-context <cluster-name> <\/code><\/pre>\nkubectl config use-context my-dev-cluster<\/code><\/pre>\nStep 4: Validate the Kubernetes cluster connectivity<\/h4>\n
kubectl get nodes<\/code><\/pre>\nMethod 2: Using KUBECONFIG environment variable<\/h3>\n
KUBECONFIG<\/code> environment variable with the kubeconfig<\/code> file path to connect to the cluster. So wherever you are using the kubectl command from the terminal, the KUBECONFIG<\/code> env variable should be available. If you set this variable, it overrides the current cluster context.<\/p>\ndev_cluster_config <\/code>is the kubeconfig<\/code> file name.<\/p>\nexport KUBECONFIG=$HOME\/.kube\/dev_cluster_config<\/code><\/pre>\nMethod 3: Using Kubeconfig File With Kubectl<\/h3>\n
kubectl get nodes --kubeconfig=$HOME\/.kube\/dev_cluster_config<\/code><\/pre>\nKUBECONFIG=$HOME\/.kube\/dev_cluster_config kubectl get nodes<\/code><\/pre>\nMerge Multiple Kubeconfig Files<\/h2>\n
Kubeconfig<\/code> file with limited access to connect to prod or non-prod servers.<\/p>\n$HOME\/.kube\/config<\/code> file using the supported kubectl command.<\/p>\n$HOME\/.kube\/<\/code> directory.<\/p>\n\n
HOME\/ .kube<\/code> directory.<\/p>\nKUBECONFIG=config:dev_config:test_config kubectl config view --merge --flatten > config.new<\/code><\/pre>\nconfig.new<\/code>.<\/p>\n$HOME.kube\/config<\/code><\/strong> file.<\/p>\n mv $HOME\/.kube\/config $HOME\/.kube\/config.old<\/code><\/pre>\nconfig.new<\/code> to config.<\/p>\nmv $HOME\/.kube\/config.new $HOME\/.kube\/config<\/code><\/pre>\nkubectl config get-contexts -o name<\/code><\/pre>\nkubectl config view --minify<\/code><\/pre>\nDelete Cluster Context From Kubeconfig<\/h2>\n
kubectl config get-contexts -o=name<\/code><\/pre>\nkubectl config delete-context <context-name><\/code><\/pre>\nkubectl config use-context <context-name><\/code><\/pre>\nCreating a Kubeconfig File<\/h2>\n
\n
clusterRole<\/code> that has limited access to cluster-wide resources. You can also create a normal role and Rolebinding that limits the user’s access to a specific namespace.<\/p>\nStep 1: Create a Service Account<\/h3>\n
kube-system<\/code> as I am creating a clusterRole. If you want to create a config to give namespace level limited access, create the service account in the required namespace.<\/p>\nkubectl -n kube-system create serviceaccount devops-cluster-admin<\/code><\/pre>\nStep 2: Create a Secret Object for the Service Account<\/h3>\n
kubernetes.io\/service-account.name<\/code> and type kubernetes.io\/service-account-token<\/code><\/p>\ncat << EOF | kubectl apply -f -\napiVersion: v1\nkind: Secret\nmetadata:\n name: devops-cluster-admin-secret\n namespace: kube-system\n annotations:\n kubernetes.io\/service-account.name: devops-cluster-admin\ntype: kubernetes.io\/service-account-token\nEOF<\/code><\/pre>\nStep 3: Create a ClusterRole<\/h3>\n
clusterRole<\/code> with limited privileges to cluster objects. You can add the required object access as per your requirements. Refer to the service account with clusterRole access<\/a> blog for more information.<\/p>\ncat << EOF | kubectl apply -f -\napiVersion: rbac.authorization.k8s.io\/v1\nkind: ClusterRole\nmetadata:\n name: devops-cluster-admin\nrules:\n- apiGroups: [\"\"]\n resources:\n - nodes\n - nodes\/proxy\n - services\n - endpoints\n - pods\n verbs: [\"get\", \"list\", \"watch\"]\n- apiGroups:\n - extensions\n resources:\n - ingresses\n verbs: [\"get\", \"list\", \"watch\"]\nEOF<\/code><\/pre>\nStep 4: Create ClusterRoleBinding<\/h3>\n
devops-cluster-admin<\/code> service account with the devops-cluster-admin<\/code> clusterRole.<\/p>\ncat << EOF | kubectl apply -f -\napiVersion: rbac.authorization.k8s.io\/v1\nkind: ClusterRoleBinding\nmetadata:\n name: devops-cluster-admin\nroleRef:\n apiGroup: rbac.authorization.k8s.io\n kind: ClusterRole\n name: devops-cluster-admin\nsubjects:\n- kind: ServiceAccount\n name: devops-cluster-admin\n namespace: kube-system\nEOF<\/code><\/pre>\nStep 5: Get all Cluster Details & Secrets<\/h3>\n
devops-cluster-admin-secret<\/code><\/strong> with your secret name,<\/p>\nexport SA_SECRET_TOKEN=$(kubectl -n kube-system get secret\/devops-cluster-admin-secret -o=go-template='{{.data.token}}' | base64 --decode)\n\nexport CLUSTER_NAME=$(kubectl config current-context)\n\nexport CURRENT_CLUSTER=$(kubectl config view --raw -o=go-template='{{range .contexts}}{{if eq .name \"'''${CLUSTER_NAME}'''\"}}{{ index .context \"cluster\" }}{{end}}{{end}}')\n\nexport CLUSTER_CA_CERT=$(kubectl config view --raw -o=go-template='{{range .clusters}}{{if eq .name \"'''${CURRENT_CLUSTER}'''\"}}\"{{with index .cluster \"certificate-authority-data\" }}{{.}}{{end}}\"{{ end }}{{ end }}')\n\nexport CLUSTER_ENDPOINT=$(kubectl config view --raw -o=go-template='{{range .clusters}}{{if eq .name \"'''${CURRENT_CLUSTER}'''\"}}{{ .cluster.server }}{{end}}{{ end }}')<\/code><\/pre>\nStep 6: Generate the Kubeconfig With the variables.<\/h3>\n
devops-cluster-admin-config<\/code> gets generated.<\/p>\ncat << EOF > devops-cluster-admin-config\napiVersion: v1\nkind: Config\ncurrent-context: ${CLUSTER_NAME}\ncontexts:\n- name: ${CLUSTER_NAME}\n context:\n cluster: ${CLUSTER_NAME}\n user: devops-cluster-admin\nclusters:\n- name: ${CLUSTER_NAME}\n cluster:\n certificate-authority-data: ${CLUSTER_CA_CERT}\n server: ${CLUSTER_ENDPOINT}\nusers:\n- name: devops-cluster-admin\n user:\n token: ${SA_SECRET_TOKEN}\nEOF<\/code><\/pre>\nStep 7: Validate the generated Kubeconfig<\/h3>\n
kubectl get nodes --kubeconfig=devops-cluster-admin-config <\/code><\/pre>\nSecurity Best Practices<\/h2>\n
Securing Kubeconfig Files<\/h3>\n
WARNING: Kubernetes configuration file is group-readable. This is insecure. Location: \/Users\/bibinwilson\/.kube\/config<\/code><\/pre>\n# Set restrictive permissions (owner read\/write only)\nchmod 600 ~\/.kube\/config\n\n# Verify permissions\nls -la ~\/.kube\/config\n# Should show: -rw------- 1 user user\n\n# For multiple configs\nfind ~\/.kube -name \"*.config\" -exec chmod 600 {} \\;<\/code><\/pre>\n.kube<\/code> directory to make sure no one else can read from or write to it.<\/p>\nchmod 700 ~\/.kube\nchown -R $USER ~\/.kube<\/code><\/pre>\nPrevent accidental exposure<\/h3>\n
.gitignore<\/code> file.<\/p>\necho \"\/.kube\/\" >> ~\/.gitignore\necho \"kubeconfig*\" >> ~\/.gitignore<\/code><\/pre>\nKubeconfig File FAQs<\/h2>\n
Where do I put the Kubeconfig file?<\/h3>\n
$HOME\/.kube\/<\/strong><\/code> folder in the home directory. Kubectl looks for the kubeconfig file using the context name from the .kube<\/code> folder. However, if you are using the KUBECONFIG<\/code> environment variable, you can place the kubeconfig file in a preferred folder and refer to the path in the KUBECONFIG<\/code> environment variable.<\/p>\nWhere is the Kubeconfig file located?<\/h3>\n
$HOME\/.kube\/config<\/code><\/strong><\/p>\nHow to manage multiple Kubeconfig files?<\/h3>\n
$HOME\/.kube<\/code> directory. You need to change the cluster context to connect to a specific cluster.<\/p>\nHow to create a Kubeconfig file?<\/h3>\n
How to use Proxy with Kubeconfig?<\/h3>\n
proxy-url<\/strong>: https:\/\/proxy.host:port<\/code> in your Kubeconfig file to connect to the cluster.<\/p>\nConclusion<\/h2>\n
\n