KubeConfig

KubeConfig

In this tutorial, we are going to discuss about KubeConfig in Kubernetes.

So far we have discussed how to generate a certificate for a user. We have discussed how a client uses the certificate file and key to query the Kubernetes Rest API for a list of PODs using curl.

$ curl https://my-kube-playground:6443/api/v1/pods --key admin.key --cert admin.crt --cacert ca.crt

In this case my cluster is called my-kube-playground, so send a curl request to the address of the kube-api server while passing in the pair of files along with the ca certificate as options.

This is then validated by the API server to authenticate the user. Now how do you do that while using the kubectl command?

You can specify the same information using the options server, client-key, client-certificate and certificate authority with the kubectl utililty.

$ kubectl get pods --server my-kube-playground:6443 --client-key admin.key --client-certificate admin.crt --certificate-authority ca.crt

Obviously typing those in every time is a tedious task.

So you move these information to a configuration file called as KubeConfig. And then specify this file as the kubeconfig option in your command.

--server my-kube-playground:6443 
--client-key admin.key 
--client-certificate admin.crt 
--certificate-authority ca.crt

$ kubectl get pods --kubeconfig config

By default the kubectl tool looks for a file named config under a directory .kube under the users home directory.

So if you create the KubeConfig file there, you don’t have to specify the path to the file explicitly in the kubectl command. That’s the reason you haven’t been specifying any options for your kubectl commands so far.

KubeConfig File

The kubeconfig file is in a specific format. Let’s take a look at that. The config file has 3 sections.

1. Clusters
2. Users
3. Contexts

Clusters

Clusters are the various Kubernetes clusters that you need access to. Say you have multiple clusters for development environment or testing environment or prod or for different organizations or on different cloud providers etc. All those go their.

Users

Users are the user accounts with which you have access to these clusters. For example the admin user, a dev user, a prod user etc. These users may have different privileges on different clusters.

Contexts

Finally contexts marry these together context define which user account will be used to access which cluster.

For example you could create a context named admin at production that will use the admin account to access a production cluster. Or I may want to access the cluster I have setup on Google with the dev users credentials to test deploying the application I built.

Remember you’re not creating any new users or configuring any kind of user access or authorization in the cluster.

With this process you’re using existing users with their existing privileges and defining what user you’re going to use to access what cluster.

That way you don’t have to specify the user certificates and server address in each and every kubectl command you run. So how does it fit into our example?

The server specification in our command goes into the cluster section. The admin users keys and certificates goes into the users section.

You then create a context that specifies to use the MyKubeAdmin user to access the MyKubePlayground cluster.

Let’s look at a real KubeConfig file now. The KubeConfig is in a YAML format.

KubeConfig file

apiVersion: v1 
kind: Config 
clusters:
- name: my-kube-playground
  cluster:   
    name: development
    certificate-authority:
    server: https://my-kube-playground:6443
users: 
- name: my-kube-admin
  user: 
    client-certificate: admin.crt
    client-key: admin.key 
contexts: 
- name: my-kube-admin@my-kube-playground
  context:
    cluster: my-kube-playground
    user: my-kube-admin

Follow the same procedure to add all the clusters you daily access. The user credentials you use to access them as well as the contacts.

Once the file is ready, remember that you don’t have to create any object like you usually do for other Kubernetes objects.

The file is left as is and is read by the kubectl command and the required values are used. Now, how does kubectl know which context to chose from?

We have defined three contexts here which one should it start with. You can specify the default context to use by adding a field current-context to the KubeConfig file.

Now specify the name of the context you use. In this case kubectl will always use the context dev-user@google to access the google clusters using the dev-user’s credentials.

There are command line options available within kubectl to view and modify the kubeconfig files. To view the current file being used run the kubectl config view command.

$ kubectl config view 

Above command lists the clusters, contexts and users as well as the current-context set. As we discussed previously, if you do not specify which kubeconfig file to use, it ends up using the default file located in the folder .kube in users home directory.

Kubectl config

Alternatively you can specify a kubeconfig file by passing the kubeconfig option in the command line like below

$ kubectl config view --kubeconfig=my-custom-config

We will move our custom config to the home directory so this becomes our default config file. So how do you update your current context. Say you have been using my-kube-admin user to access my-kube-playground.

How do you change the context to use prod-user to access the production cluster? Run the kubectl config use-context command to change the current-context to the prod-user@production context.

$ kubectl config use-context prod-user@production 

You can be seen in the current context field in the file. So the changes made by kubectl config command actually reflects in the file. You can make other changes in the file update or delete items in it using other variations of the kubectl config command.

$ kubectl config -h
Available Commands:
   current-context Displays the current-context
   delete-cluster  Delete the specified cluster from the kubeconfig
   delete-context  Delete the specified context from the kubeconfig
   get-clusters    Display clusters defined in the kubeconfig
   get-contexts    Describe one or many contexts
   rename-context  Renames a context from the kubeconfig file.
   set             Sets an individual value in a kubeconfig file
   set-cluster     Sets a cluster entry in kubeconfig
   set-context     Sets a context entry in kubeconfig
   set-credentials Sets a user entry in kubeconfig
   unset           Unsets an individual value in a kubeconfig file
   use-context     Sets the current-context in a kubeconfig file
   view            Display merged kubeconfig settings or a specified kubeconfig file

Namespaces

Each cluster may be configured with multiple name spaces within it. Can you configure a context to switch to a particular namespace? Yes..!! The context section in the kubeconfig file can take additional field called namespace where you can specify a particular namespace.

This way when you switch to that context you will automatically be in a specific namespace. Finally a word on certificates. You have seen path to certificate files mentioned in kubeconfig like below.

Certificates in KubeConfig

Well, its better to use the full path like below.

But remember there is also another way to specify the certificate credentials. Let’s look at the first one for instance where we configure the path to the Certificate Authority.

We have the contents of the ca.crt file on the right. Instead of using the certificate-authority field and the path to the file you may optionally use the certificate-authority-data field and provide the contents of the certificate itself. But not the file as is, Convert the contents to a base64 encoded format and then pass that in.

Similarly if you see a file with the certificates data in the encoded format use the Base64 decode option to decode the certificate.