• May 20, 2023
• in Kubernetes, CKS
• 3 min read

Understanding Kubeconfig in Kubernetes

What is Kubeconfig?

Kubeconfig is a configuration file used by kubectl and other Kubernetes tools to access and manage Kubernetes clusters. It contains information about clusters, users, contexts, and other settings needed to authenticate and communicate with Kubernetes clusters.

---

Location of Config File

By default, the kubeconfig file is located at:

• Linux/Mac: $HOME/.kube/config
• Windows: %USERPROFILE%\.kube\config

You can also specify a different location using the KUBECONFIG environment variable or the --kubeconfig flag with kubectl commands.

---

Clusters, Contexts, Users

A kubeconfig file typically contains several sections:

• Clusters: Defines the Kubernetes clusters you can connect to. Each cluster entry includes the cluster name, server URL, and certificate authority data.

• Contexts: Represents a combination of a cluster, a user, and a namespace. Contexts allow you to switch between different cluster-user combinations easily.

• Users: Specifies the credentials needed to authenticate to a cluster. This can include client certificates, tokens, or other authentication methods.

Example Kubeconfig File

apiVersion: v1
clusters:
- cluster:
    certificate-authority: /path/to/ca.crt
    server: https://your-kubernetes-cluster-server
  name: my-cluster

contexts:
- context:
    cluster: my-cluster
    namespace: default
    user: my-user
  name: my-context

current-context: my-context

kind: Config
preferences: {}
users:
- name: my-user
  user:
    client-certificate: /path/to/client.crt
    client-key: /path/to/client.key

---

Embedding Certificates in Kubeconfig

Instead of referring to certificate files, you can embed the certificate data directly in the kubeconfig file. This makes the configuration portable and easier to manage.

Example Kubeconfig File with Embedded Certificates

apiVersion: v1
kind: Config
clusters:
- name: my-cluster
  cluster:
    server: https://your-kubernetes-cluster-server
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURrVENDQWVrZ0F3SUJBZ0lKQU9XWFpXK0pqOTRmTUEwR0NTcUdTSWIzRFFFQkJRVUFNQTB4Q3pBSkJnTlYKQkFNTUdWUjBMbWgwZEhCekxtWnZiM1F1YzJWeU1TNW5jR0YwWVRBMU1TNHdPVEV6TVRJd1pEQXpNRm9YRFRNMwpNamM1T0RjeU1EWXhPRFl4TUZvWFRUUTVNamN4TkRreU1EWTBNelF3TkRFVk1CTUdBMVVFQXhNR2J6RXhN

contexts:
- name: my-context
  context:
    cluster: my-cluster
    user: my-user
    namespace: default

current-context: my-context

users:
- name: my-user
  user:
    client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURrVENDQWVrZ0F3SUJBZ0lKQU9XWFpXK0pqOTRmTUEwR0NTcUdTSWIzRFFFQkJRVUFNQTB4Q3pBSkJnTlYKQkFNTUdWUjBMbWgwZEhCekxtWnZiM1F1YzJWeU1TNW5jR0YwWVRBMU1TNHdPVEV6TVRJd1pEQXpNRm9YRFRNMwpNamM1T0RjeU1EWXhPRFl4TUZvWFRUUTVNamN4TkRreU1EWTBNelF3TkRFVk1CTUdBMVVFQXhNR2J6RXhN
    client-key-data: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQo...

---

How to Embed Certificates

1. Convert Certificate Files to Base64: Use the base64 command to encode your certificate and key files.

base64 -w 0 /path/to/ca.crt > ca.crt.base64
base64 -w 0 /path/to/client.crt > client.crt.base64
base64 -w 0 /path/to/client.key > client.key.base64

1. Embed the Encoded Data in the Kubeconfig: Replace the file paths in your kubeconfig with the Base64-encoded data.

2. For the certificate-authority-data key:

   certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
   

3. For the client-certificate-data key:

   client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
   

4. For the client-key-data key:

   client-key-data: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQo...
   

Example Commands

base64 -w 0 /path/to/ca.crt > ca.crt.base64
base64 -w 0 /path/to/client.crt > client.crt.base64
base64 -w 0 /path/to/client.key > client.key.base64

These commands will generate files containing the Base64-encoded data, which you can then copy and paste into your kubeconfig file under the appropriate keys.

By embedding the certificate data directly in the kubeconfig file, you make the configuration self-contained, which can be particularly useful for automation and sharing configurations across different environments

---

Current Context

The current context determines which cluster, user, and namespace are active when you run kubectl commands. It is specified in the current-context field of the kubeconfig file.

---

Viewing the Current Context

To view the current context:

kubectl config current-context

---

Setting the Current Context

To set the current context:

kubectl config use-context my-context

---

KubeConfig Management Commands

Here are some useful kubectl commands for working with kubeconfig:

• View Current Context:

kubectl config current-context

• Set Current Context:

kubectl config use-context <context-name>

• View All Contexts:

kubectl config get-contexts

• Switch to a Different Context:

kubectl config use-context <context-name>

• View Cluster Information:

kubectl config view

• Add a New Cluster:

kubectl config set-cluster <cluster-name> --server=<server-url> --certificate-authority=<path-to-ca.crt>

• Add a New User:

kubectl config set-credentials <user-name> --client-certificate=<path-to-client.crt> --client-key=<path-to-client.key>

• Add a New Context:

kubectl config set-context <context-name> --cluster=<cluster-name> --namespace=<namespace> --user=<user-name>

---

By understanding and managing the kubeconfig file, you can efficiently switch between different Kubernetes clusters and user configurations, making cluster management more streamlined and effective.