Kubeconfig File Explained With Practical Examples

The following describes how to use Kubeconfig files to connect to a kubernetes cluster using different methods . Additionally, you will learn to generate custom Kubeconfig files.

What is a Kubeconfig file?

Kubeconfig is a YAML file that contains all Kubernetes cluster details, certificates, and secret tokens used to authenticate to the cluster. If you are using a managed Kubernetes cluster, you may obtain this configuration file directly from the cluster administrator or the cloud platform.

When you use it kubectl, 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

Additionally, kubernetes cluster components such as controller managers, schedulers, and kubelets use kubeconfig files to interact with the API server.

Example Kubeconfig File

This is an example of Kubeconfig. It requires the following key information to connect to the Kubernetes cluster.

1. certificate-authority-data : cluster CA
2. server : cluster endpoint (IP/DNS of master node)
3. name : cluster name
4. user : The name of the user/service account.
5. token : The secret token of the user/service account.

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <ca-data-here>
    server: https://your-k8s-cluster.com
  name: <cluster-name>
contexts:
- context:
    cluster:  <cluster-name>
    user:  <cluster-name-user>
  name:  <cluster-name>
current-context:  <cluster-name>
kind: Config
preferences: {}
users:
- name:  <cluster-name-user>
  user:
    token: <secret-token-here>

Different ways to connect to a Kubernetes cluster using Kubeconfig files

You can use Kubeconfig in different ways, each with its own priorities. Here they are in order.

1. **Kubectl Context:** Kubeconfig using kubectl overrides all other configurations. It has the highest priority.
2. Environment Variable: KUBECONFIG environment variable overrides the current context.
3. **Command-Line Reference:** The current context has the lowest priority over inline configuration references and environment variables.

Now let’s look at all three ways of using Kubeconfig files.

Method 1: Use Kubeconfig Kubectl Context to connect to the Kubernetes cluster

To connect to a Kubernetes cluster, the basic prerequisite is the Kubectl CLI plugin. If you don’t have the CLI installed, follow the instructions given here .

Now follow the steps given below to interact with the cluster using kubeconfig file.

Step 1: Move kubeconfig to the .kube directory.

Kubectl interacts with the kubernetes cluster using the details available in the Kubeconfig file. By default, kubectl looks for configuration files in this location /.kube.

Let’s move the kubeconfig file to the .kube directory. Replace /path/to/kubeconfigwith the current path of your kubeconfig.

mv /path/to/kubeconfig ~/.kube

Step 2: List all cluster contexts

There can be any number of kubeconfigs in the directory .kube. Each configuration has a unique context name (that is, the name of the cluster). You can verify the Kubeconfig file by listing the context. You can use the following command to list all contexts. It lists the context name as the name of the cluster.

kubectl config get-contexts

Step 3: Set the current context

Now you need to set the current context to your kubeconfig file. You can use the following commands to set it up. Replace <cluster-name>with the context name you listed.

kubectl config use-context <cluster-name>  

For example,

kubectl config use-context my-dev-cluster

Step 4: Verify Kubernetes cluster connection

To verify cluster connectivity, you can execute the following kubectl command to list cluster nodes.

kubectl get nodes

Method 2: Connect through KUBECONFIG environment variable

You can set environment variables KUBECONFIGusing kubeconfigfile paths to connect to the cluster. Therefore, KUBECONFIGthe env variable should be available wherever you use the kubectl command from the terminal . If you set this variable, it overrides the current cluster context.

You can set variables using the following commands. dev_cluster_configwhere is the file name kubeconfig.

KUBECONFIG=$HOME/.kube/dev_cluster_config

Method 3: Use Kubeconfig file through Kubectl

You can use the Kubectl command to pass a Kubeconfig file to override the current context and KUBECONFIG env variables.

Here is an example of getting a node.

kubectl get nodes --kubeconfig=$HOME/.kube/dev_cluster_config

You can also use,

KUBECONFIG=$HOME/.kube/dev_cluster_config kubectl get nodes

Merge multiple Kubeconfig files

Typically, when you use a Kubernetes service such as GKE, all cluster context is added as a file. However, in some cases you will get a Kubeconfig file with limited access to connect to production or non-production servers. To effectively manage all clusters with a single configuration, you can $HOME/.kube/configmerge other Kubeconfig files into the default file using the supported kubectl command.

Let’s say you $HOME/.kube/have three Kubeconfig files in the directory.

1. Configuration (default kubeconfig)
2. development configuration
3. Test configuration

You can use the following command to merge all three configurations into one file. $HOME/.kubMake sure you run the command from the e directory

KUBECONFIG=config:dev_config:test_config kubectl config view --merge --flatten > config.new

The above command creates a file named config.new.

Now rename the old **$HOME.kube/config**file.

mv $HOME/.kube/config $HOME/.kube/config.old

Renamed config.newto configuration.

mv $HOME/.kube/config.new $HOME/.kube/config

To verify the configuration, try listing the context in the configuration.

kubectl config get-contexts

If you want to view the kubeconfig file in compressed format to analyze all configurations, you can use the following minify command.

kubectl config view --minify

How to generate Kubeconfig file?

Now we will look at creating Kubeconfig file using serviceaccount method. serviceaccount is the default user type managed by the Kubernetes API.

kubeconfig requires the following important details.

1. Cluster endpoint (IP or DNS name of the cluster)
2. Cluster CA certificate
3. Cluster name
4. Service account username
5. Service account token

Note: To generate the Kubeconfig file, you need administrator privileges in the cluster to create service accounts and roles.

For this demonstration, I am creating a service account clusterRolethat has limited access to cluster-wide resources. You can also create a common role and role bindings to restrict user access to specific namespaces.

Step 1: Create a service account

The service account name will be the username in Kubeconfig. kube-systemHere, I create the service account while creating the clusterRole. If you want to create a configuration to provide limited access at the namespace level, create a service account in the required namespace.

kubectl -n kube-system create serviceaccount devops-cluster-admin

Step 2: Create a secret object for the service account

kubernetes.io/service-account.name Starting with Kubernetes version 1.24, service account secrets must be created separately using annotations and types kubernetes.io/service-account-token

Let us create a secret called devops-cluster-admin-secret using annotations and types.

cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: devops-cluster-admin-secret
  namespace: kube-system
  annotations:
    kubernetes.io/service-account.name: devops-cluster-admin
type: kubernetes.io/service-account-token
EOF

Step 3: Create ClusterRole

Let’s create a clusterRole cluster object with limited permissions. You can add the required object access rights as needed.

Execute the following command to create clusterRole.

cat << EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: devops-cluster-admin
rules:
- apiGroups: [""]
  resources:
  - nodes
  - nodes/proxy
  - services
  - endpoints
  - pods
  verbs: ["get", "list", "watch"]
- apiGroups:
  - extensions
  resources:
  - ingresses
  verbs: ["get", "list", "watch"]
EOF

Step 4: Create ClusterRoleBinding

The following YAML is a ClusterRoleBinding that binds devops-cluster-adminthe service account to devops-cluster-adminthe clusterRole.

cat << EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: devops-cluster-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: devops-cluster-admin
subjects:
- kind: ServiceAccount
  name: devops-cluster-admin
  namespace: kube-system
EOF

Step 5: Get all cluster details and secrets

We will retrieve all required kubeconfig details and save them in variables. Then, finally, we’ll replace it directly with Kubeconfig YAML.

If you used a different secret name, replace ** devops-cluster-admin-secret** with your secret name,

export SA_SECRET_TOKEN=$(kubectl -n kube-system get secret/devops-cluster-admin-secret -o=go-template='{{.data.token}}' | base64 --decode)

export CLUSTER_NAME=$(kubectl config current-context)

export CURRENT_CLUSTER=$(kubectl config view --raw -o=go-template='{{range .contexts}}{{if eq .name "'''${CLUSTER_NAME}'''"}}{{ index .context "cluster" }}{{end}}{{end}}')

export 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 }}')

export CLUSTER_ENDPOINT=$(kubectl config view --raw -o=go-template='{{range .clusters}}{{if eq .name "'''${CURRENT_CLUSTER}'''"}}{{ .cluster.server }}{{end}}{{ end }}')

Step 6: Generate Kubeconfig using variables.

If you execute the following YAML, all variables will be replaced and devops-cluster-admin-configa configuration named will be generated.

cat << EOF > devops-cluster-admin-config
apiVersion: v1
kind: Config
current-context: ${CLUSTER_NAME}
contexts:
- name: ${CLUSTER_NAME}
  context:
    cluster: ${CLUSTER_NAME}
    user: devops-cluster-admin
clusters:
- name: ${CLUSTER_NAME}
  cluster:
    certificate-authority-data: ${CLUSTER_CA_CERT}
    server: ${CLUSTER_ENDPOINT}
users:
- name: devops-cluster-admin
  user:
    token: ${SA_SECRET_TOKEN}
EOF

Step 7: Verify the generated Kubeconfig

To verify Kubeconfig, execute it using the kubectl command to see if the cluster is authenticating.

kubectl get nodes --kubeconfig=devops-cluster-admin-config 

Note: In cloud environments, cluster RBAC (Role-Based Access Control) can be mapped to normal IAM (Identity and Access Management) users. This allows organizations to control access to the cluster based on IAM policies, which can be used to create restrictive kubeconfig files. Additionally, other services, such as OIDC (OpenID Connect), can be used to manage users and create kubeconfig files to restrict access to the cluster based on specific security requirements.

Kubeconfig File FAQ

Let’s look at some common Kubeconfig file issues.

Where to place Kubeconfig files?

The default Kubeconfig file location is `**$HOME/.kube/**`a folder in your home directory. Kubectl uses the from. kubefolder. However, if you are using KUBECONFIGenvironment variables, you can place the kubeconfig file in your preferred folder and reference KUBECONFIGthe path in the environment variables.

Where are the Kubeconfig files located?

All kubeconfig files are located in the .kube directory of the user’s home directory. That is**$HOME/.kube/config**

How to manage multiple Kubeconfig files?

You can store all kubeconfig files in $HOME/.kubea directory. You need to change the cluster context to connect to a specific cluster.

How to create Kubeconfig file?

To create the Kubeconfig file, you need to have the cluster endpoint details, cluster CA certificate, and authentication token. You then need to create a Kubernetes YAML object of type config that contains all the cluster details.

How to use proxy via Kubeconfig

If you are behind a corporate proxy, you can use proxy-url: https://proxy.host:port in your Kubeconfig file to connect to the cluster.

Conclusion

This blog explored methods for connecting to a Kubernetes cluster with a custom Kubeconfig file.

If you’re considering Kubernetes certification, a guide to choosing the right certification based on your expertise can be found here.