What is Kubeconfig File in a Kubernetes Cluster?

What is kubeconfig file in a Kubernetes Cluster? If you are just starting out your journey in Kubernetes, it is crucial to understand what a Kubernetes kubeconfig file is. If you have deployed a Kubernetes cluster, you must have used a command line tool called kubectl, which allows communication with Kubernetes control plane through the Kubernetes API server. It doesn’t matter the method you use to deploy the cluster, kubeconfig file will always be there.

Demystifying the Kubernetes Kubeconfig File

What is Kubeconfig File?

As stated above, kubectl is a command line tool that facilitates communication with the cluster. So, what makes it possible for the kubectl to interact with Kubernetes cluster? You guessed it right, kubeconfig! Kubeconfig is a YAML file in a Kubernetes cluster which stores information that allows kubectl to connect and interact with Kubernetes cluster.

What Information does Kubeconfig Store?

So, what is this information that kubeconfig file stores that allows kubectl or other K8S utilities to connect and interact with Kubernetes cluster?

Kubeconfig file stores three types of information:

1. Cluster Configuration: This includes information such as cluster’s API server address, certificate authority (CA) data for authenticating the API server, and other cluster-specific settings.
2. User Authentication: This may include client certificates, client private keys, or authentication tokens for accessing the Kubernetes cluster.
3. Contexts: Contexts define which cluster, user, and namespace kubectl should use when executing commands. Multiple contexts can be defined in a single kubeconfig file, allowing users to switch between different Kubernetes clusters easily.

Where is Kubeconfig Located?

Default Location

Depending on how you have configured your cluster, the default location on Linux and MacOS systems is $HOME/.kube/config and %USERPROFILE%\.kube\config on windows.

ls ~/.kube/

Sample output;

cache  config

If you are executing kubectl command from a different working directory within the user’s home directory, kubectl will search for the kubeconfig in the default location. kubectl doesn’t perform any additional searches beyond this default location. If the file isn’t found there, it won’t look in any other directories or subdirectories unless you explicitly instruct it to using either the --kubeconfig flag or the KUBECONFIG environment variable.

Specify Kubeconfig Location using KUBECONFIG environment variable

If you are using a different location other than the default location mentioned above, you can, while running the kubectl command, define the path to your kubeconfig file location using KUBECONFIG environment variable.

For example, before you can execute kubectl commands, run the following sample command to define the path your custom kubeconfig file location.

export KUBECONFIG=/home/kifarunix/kube-cluster/.kube/config

Then execute your kubectl command, for example;

kubectl get nodes

Alternatively, you can prefix your kubectl commands with the environment variable as follows;

KUBECONFIG=home/kifarunix/kube-cluster/.kube/config kubectl commands

Specify Kubeconfig Location using –kubeconfig flag

kubectl command has a command line option, –kubeconfig, that let’s you to define the path to your custom kubeconfig location.

For example;

kubectl --kubeconfig=$HOME/.kube/config [command]

Sample Kubeconfig File

You can view the current settings of a Kubeconfig file using the command below;

kubectl config view

Sample output;

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://192.168.122.60:6443
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: kubernetes-admin
  name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: {}
users:
- name: kubernetes-admin
  user:
    client-certificate-data: DATA+OMITTED
    client-key-data: DATA+OMITTED

Where:

• apiVersion: This defines the version of the Kubernetes API currently being used.
• kind: This specifies the type of Kubernetes object. In this case, it’s a Config object, indicating it’s a kubeconfig file.
• clusters: This defines the clusters that you can connect to using kubectl command. In this file, there’s only one cluster defined:
  • cluster: Contains information about the Kubernetes cluster, including the server’s URL and the certificate authority data used for secure communication.
  • name: Defines the name of the cluster. This can be referenced in other parts of the kubeconfig file.
• contexts: This defines the cluster and user that kubectl should use when executing the kubectl commands.
  • context: Specifies the cluster and user to be used.
    • cluster: The name of the cluster from the clusters section.
    • user: The name of the user from the users section.
  • name: A name assigned to this context, which can be used to reference it later.
• current-context: Specifies which context is currently selected for use by default. Here, it’s set to kubernetes-admin@kubernetes, which matches the name of the context defined earlier.
• preferences: {} : This section (currently empty) can be used to define user preferences for kubectl commands, such as output formatting.
• users: Defines the users that kubectl can authenticate as. In this file, there’s only one user defined:
  • name: A name assigned to this user, which can be referenced in other parts of the kubeconfig file.
  • user: Contains authentication information for the user, including client certificate data and client key data.

Managing Kubernetes Kubeconfig File

You can view, modify, and create entries for clusters, users, and contexts within your kubeconfig files using kubectl config command.

The kubectl config commands modify your kubeconfig files directly. Be cautious and make backups if needed.

For example;

To view current Kubeconfig configuration;

kubectl config view

Display clusters defined in the kubeconfig;

kubectl config get-clusters

Display the current Kubernetes context;

kubectl config get-contexts

Display users defined in the kubeconfig;

kubectl config get-users

Create a new cluster entry in your kubeconfig file with the specified name, server address, and path to the certificate authority (CA) file.

kubectl config set-cluster <name> --server=<server> --certificate-authority=<path/to/ca>

Create a new user entry with the specified name, username, and paths to the client certificate and key files.

kubectl config set-credentials <name> --username=<username> --client-certificate=<path/to/cert> --client-key=<path/to/key>

Create a new context and links a specific cluster with a specific user.

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

Set the currently active context, which determines the cluster and user kubectl will use by default.

kubectl config set-current-context <context-name>

Switch to a specific namespace;

kubectl config set-context --current --namespace <name-space>

Read more on;

kubectl config --help

Merging Multiple Kubeconfig Files

It is also possible to merge together multiple kubeconfig files into a single kubeconfig file. This can be useful if you have configurations for different Kubernetes clusters or contexts and you want to consolidate them into one file for easier management.

Precautions While Merging Kubeconfig Files

When merging kubeconfig files manually, be mindful of the following:

1. Ensure that the context names in the merged kubeconfig file are unique to avoid conflicts.
2. Make sure you don’t overwrite existing cluster, user, or context sections when merging files. If there are conflicts, you may need to rename them to maintain uniqueness.
3. Verify that the current context is correctly set after merging the files.

Using the kubectl config view Command:

This method leverages the kubectl config view command to display the contents of your existing kubeconfig files and then capture the output into a new merged file.

kubectl config view --flatten > merged_config.yaml

If the rest of the kubeconfig files are not in the default path, you can use KUBECONFIG variable;

KUBECONFIG=config:another_config:another_config2 kubectl config view --flatten > merged_config.yaml

You can choose whether to make the resulting file into a default file or use KUBECONFIG or –kubeconfig options to define their paths.

Manually Merging Files

Alternatively, you can manually merge the contents of multiple kubeconfig files into a single file. Each kubeconfig file is in YAML format, so you can copy the contents of one file and paste them into another, ensuring that you maintain proper YAML syntax.

Conclusion

And the concludes our guide on what Kubeconfig is in Kubernetes.

Read more on Organizing Cluster Access Using kubeconfig Files.