kubectl config Explained: How to Configure Cluster Access

What Is the kubectl config Command? 

The kubectl config command is a powerful tool that helps in managing Kubernetes configurations, primarily through the manipulation of the kubeconfig file. Through the kubectl config command, you can create, view, and modify clusters, contexts, and users. For example, here are some commands you can use with kubectl config:

• kubectl config view: Lists all clusters for which kubeconfig entries have been generated. This is helpful in verifying or troubleshooting your settings
• kubectl config get-context: to show your current cluster context
• kubectl config set-context: creates or modifies contexts in your kubeconfig file

The kubeconfig file is a YAML file that organizes information about clusters, users, namespaces, and authentication mechanisms. The default location of the kubeconfig file is ~/.kube/config. The file is divided into three main sections:

• The clusters section contains the details of your clusters, such as the server’s address and certificate authority data. 
• The users section stores the credentials for your users. 
• The contexts section ties everything together by mapping a user to a cluster.

This is part of a series of articles about kubectl Cheat Sheet.

kubectl config syntax and Examples

The kubectl config command is followed by various subcommands. Here are the main sub-commands:

• view: to view your kubeconfig file
• get-contexts: to list the contexts in your kubeconfig file
• current-context: display the current context
• use-context: to switch to a different context
• set-context: to create a context
• rename-context: to rename a context
• delete-context: to delete a context
• set-cluster: set a cluster entry in kubeconfig
• set-credentials: add a user
• unset: delete a user

Here are a few examples of how you can use the kubectl config command.

To view your current context:

$ kubectl config current-context

To list all your contexts:

$ kubectl config get-contexts

To create a new context:

$ kubectl config set-context fm-context --namespace=default 
--cluster=my-cluster --user=fm

The values my-context, my-namespace, my-cluster, and my-user should be replaced with your specific context, namespace, cluster, and user values.

To switch to a different context:

$ kubectl config use-context my-context

To set a proxy for a cluster in kubeconfig:

The kubectl command-line tool uses kubeconfig files to find information to choose a cluster and communicate with the cluster’s API server. Here is how to set a proxy for a cluster:

kubectl config set-cluster my-cluster-name 
--proxy-url=my-proxy-url

To add a new user with basic authentication:

kubectl config set-credentials kubeuser/foo.kubernetes.com 
--username=exampleuser --password=examplepassword

To delete a user:

kubectl config unset users.fm

To view user credentials:

Here is how to get a list of users

kubectl config view -o jsonpath='{.users[*].name}'   # get a list of users

Here is how to get the password for a specific user:

kubectl config view -o jsonpath='{.users[?(@.name == "example")].user.password}'

Tips from the expert

Itiel Shwartz

Co-Founder & CTO

Itiel is the CTO and co-founder of Komodor. He’s a big believer in dev empowerment and moving fast, has worked at eBay, Forter and Rookout (as the founding engineer). Itiel is a backend and infra developer turned “DevOps”, an avid public speaker that loves talking about things such as cloud infrastructure, Kubernetes, Python, observability, and R&D culture.

In my experience, here are tips that can help you better configure cluster access using kubectl config:

Centralize kubeconfig Files

Store and manage your kubeconfig files in a centralized repository, such as a version-controlled Git repository. This ensures all team members have access to the latest configurations and can avoid discrepancies.

Use Aliases for Context Switching

Create shell aliases for frequently used kubectl config use-context commands to quickly switch contexts without needing to remember the exact context names. This speeds up workflow and reduces errors.

Merge Multiple kubeconfig Files

Use the KUBECONFIG environment variable to merge multiple kubeconfig files. This is useful for managing access to multiple clusters without overwriting existing configurations. For example:
bash
Copy code
export KUBECONFIG=$HOME/.kube/config:$HOME/.kube/config-dev:$HOME/.kube/config-prod

Set Context Defaults

Set default contexts for specific clusters or namespaces using kubectl config set-context. This ensures that users automatically operate in the correct context, reducing the risk of accidental changes in the wrong cluster or namespace.

Automate Context Configuration

Use automation tools, such as scripts or Ansible, to set up and manage kubeconfig files and contexts. This ensures consistency across environments and simplifies onboarding for new team members.

Main Use Cases of kubectl config 

Viewing Kubernetes configurations with ‘kubectl config view’

You can use the kubectl config command to view your current Kubernetes configurations. This can be done using the kubectl config view command.

This command will output the entire kubeconfig file, displaying all your clusters, contexts, and users. It’s a great way to quickly check your configurations and ensure everything is in order.

Configuring the Kubernetes context

The context is a critical aspect of the kubeconfig file. It determines which cluster and namespace you’re currently working on and which user’s credentials to use.

By using the kubectl config use-context command, you can switch between different contexts. This is especially useful when working with multiple clusters. 

You can create, rename, or delete contexts using these commands:

• kubectl config set-context
• kubectl config rename-context
• kubectl config delete-context

Related content: Read our guide to kubectl get context.

Common Issues with ‘kubectl config’ and How to Resolve Them 

The kubectl config command is used for modifying kubeconfig files. These files are usually located in the home directory and contain information about the clusters, contexts, users, and namespaces. Any issue with kubectl config command often means there’s something amiss in our kubeconfig files.

Context Not Found

One of the most common issues is the context not found error. This typically happens when we try to switch to a context that doesn’t exist in our kubeconfig file. The context refers to the cluster and namespace that kubectl should interact with. If we get the context not found error, it means that the context we’re trying to switch to is not included in our kubeconfig file.

To resolve this, first, we need to confirm whether the context indeed exists. We can do this by listing all contexts in our kubeconfig file using the kubectl config get-contexts command. If the required context is not listed, we need to create it using the kubectl config set-context command. This command will require cluster, namespace, and user details. Once we’ve set the context, we can switch to it using the kubectl config use-context command.

Wrong Cluster or Namespace

Another common issue is when kubectl interacts with the wrong cluster or namespace. This usually happens when the current context in our kubeconfig file points to a different cluster or namespace than we intended.

Resolving this issue involves changing the current context to the correct one. We can list all our contexts using the kubectl config get-contexts command, then identify the correct context, and switch to it using the kubectl config use-context command. If the correct context doesn’t exist, we should create it using the kubectl config set-context command.

Permission Issues

Permission issues are a frequent occurrence with the kubectl config command. These issues typically arise when our user doesn’t have the necessary permissions to interact with the cluster or namespace specified in the context. In Kubernetes, permissions are handled through Role-Based Access Control (RBAC), which associates users with roles that determine what actions they can take.

To resolve permission issues, we need to ensure that our user has the necessary roles associated with them. We can do this by creating or updating a RoleBinding or ClusterRoleBinding resource that associates our user with the required role. If you are unsure what roles the user has, you can use the kubectl auth can-i command to check what actions the user can perform.

Multiple Kubeconfig Files

Having multiple kubeconfig files can also lead to issues. kubectl uses the KUBECONFIG environment variable to determine which kubeconfig file to use. If this variable is not set, kubectl will default to using the kubeconfig file in the home directory. However, if you have multiple kubeconfig files, kubectl might use a different file than we intended, leading to unexpected results.

To resolve this issue, you can explicitly set the KUBECONFIG environment variable to point to the correct kubeconfig file. Alternatively, you can merge kubeconfig files into one using the kubectl config view command with the --flatten option and then save the output to our kubeconfig file.

Kubernetes Troubleshooting With Komodor

Kubernetes is a complex system, and often, something will go wrong, simply because it can. In situations like this, you’ll likely begin the troubleshooting process by reverting to some of the above kubectl commands to try and determine the root cause. This process, however, can often run out of hand and turn into a stressful, ineffective, and time-consuming task.

This is the reason why we created Komodor, a tool that helps dev and ops teams stop wasting their precious time looking for needles in (hay)stacks every time things go wrong.

Acting as a single source of truth (SSOT) for all of your k8s troubleshooting needs, Komodor offers:

• Change intelligence: Every issue is a result of a change. Within seconds we can help you understand exactly who did what and when.
• In-depth visibility: A complete activity timeline, showing all code and config changes, deployments, alerts, code diffs, pod logs and etc. All within one pane of glass with easy drill-down options.
• Insights into service dependencies: An easy way to understand cross-service changes and visualize their ripple effects across your entire system.
• Seamless notifications: Direct integration with your existing communication channels (e.g., Slack) so you’ll have all the information you need, when you need it.

If you are interested in checking out Komodor, use this link to sign up for a Free Trial.