Configuring kubeconfig on Linux: Complete Connection Guide

Introduction / Why This Is Needed

Kubeconfig is the primary configuration file for kubectl, the CLI tool for managing Kubernetes. It stores information about clusters, users, contexts, and authentication methods. Without a properly configured kubeconfig, you won't be able to run commands like kubectl get pods, kubectl apply, and others.

After completing this guide, you will be able to:

• Connect kubectl to one or more Kubernetes clusters
• Switch between clusters and namespaces
• Manage cluster resources via the command line

Requirements / Preparation

Before you begin, ensure that:

1. kubectl version 1.20 or higher is installed. Verify with: kubectl version --client.
2. You have access to a Kubernetes cluster — you have received configuration data from an administrator or cloud provider (GKE, EKS, AKS, etc.):
   • API server URL
   • CA certificate or path to its file
   • Service account token or authentication data (e.g., client-certificate and client-key)
3. Write permissions in your home directory — your user must have permissions to create ~/.kube and write to ~/.kube/config.
4. Network access to the API server — port 6443 (default) must be open.

::in-article-ad: :

Step 1: Obtaining Cluster Configuration

Cluster configuration can be provided in several formats:

• A ready-made kubeconfig file (most often from cloud providers). Example contents:

  apiVersion: v1
  clusters:
  - cluster:
      certificate-authority-data: LS0tLS1CRUdJTiBD...
      server: https://<API-сервер>:6443
    name: my-cluster
  contexts:
  - context:
      cluster: my-cluster
      user: admin
    name: my-cluster-admin
  current-context: my-cluster-admin
  kind: Config
  users:
  - name: admin
    user:
      token: eyJhbGciOiJSUzI1NiIs...
  

• Individual parameters (URL, token, certificates) that need to be manually added to kubeconfig using kubectl config set-....

If you are working with a kubeadm cluster, you can copy the configuration from the master node:

scp user@master-node:/etc/kubernetes/admin.conf ~/.kube/config

If you are using a cloud provider, you can usually download the configuration via the web console or CLI (e.g., gcloud container clusters get-credentials for GKE).

Step 2: Placing and Merging Configurations

The standard path for kubeconfig is ~/.kube/config. If the ~/.kube directory does not exist, create it:

mkdir -p ~/.kube

Option A: You have one configuration file

Simply copy it to ~/.kube/config:

cp /путь/к/полученному/config ~/.kube/config

Option B: You have multiple configurations (multiple clusters)

If you already have a kubeconfig with other clusters, merge the configurations to avoid losing existing ones:

# Export the existing kubeconfig to a variable
export KUBECONFIG=~/.kube/config:/путь/к/новому/config

# Merge into a single file
kubectl config view --flatten > ~/.kube/config.tmp && mv ~/.kube/config.tmp ~/.kube/config

# Clear the variable
unset KUBECONFIG

What does the kubectl config view --flatten command do?
It merges all configurations from the specified files into a single YAML, resolving name conflicts (clusters, users, contexts).

Step 3: Setting Access Permissions

The ~/.kube/config file contains sensitive data (certificates, tokens). Restrict access to your user only:

chmod 600 ~/.kube/config

If you are using system accounts (e.g., root for automation), ensure the file is accessible to them as well, but do not leave it accessible to the group or everyone (chmod 644 is dangerous!).

Step 4: Verifying Connection and Contexts

Verify that kubectl sees the cluster:

kubectl cluster-info

Example successful output:

Kubernetes control plane is running at https://<API-сервер>:6443
CoreDNS is running at https://<API-сервер>:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

Ensure the correct context is active:

kubectl config current-context

The output should match the context name from kubeconfig (e.g., my-cluster-admin).

View all available contexts:

kubectl config get-contexts

Switch to the desired context (if there are multiple):

kubectl config use-context <имя_контекста>

Verify access to cluster resources:

kubectl get nodes

If the command returns a list of nodes (or an empty list if you don't have permission to view them), the connection is working.

Verification

1. kubectl cluster-info should display the API server URL without errors.
2. kubectl get namespaces should return a list of namespaces (e.g., default, kube-system).
3. kubectl config view should display valid YAML without syntax errors.

If all these commands execute successfully, the kubeconfig is configured correctly.

Potential Issues

Issue: kubectl outputs The connection to the server <server> was refused or Unable to connect to the server

Causes:

• Incorrect API server URL in kubeconfig.
• API server is not running or inaccessible from your network.
• Firewall is blocking port 6443.

Solution:

1. Check the URL: kubectl config view | grep server.
2. Ensure you can ping the API server (or use telnet <server> 6443).
3. If the cluster is in the cloud, check firewall and VPC settings.

Issue: error: You must be logged in to the server (Unauthorized)

Causes:

• Token has expired.
• Incorrect token or certificates in kubeconfig.
• The account does not have permissions on the cluster.

Solution:

1. Update the token (if temporary) or verify the correctness of client-certificate and client-key.
2. For cloud providers, run the command to re-obtain credentials (e.g., aws eks update-kubeconfig).
3. Verify that the correct user is specified in kubeconfig and that it exists in the cluster (kubectl get users requires RBAC permissions).

Issue: error: no context exists with name <context>

Cause: No context with that name exists in kubeconfig (possibly you misspelled the name or the configuration was not loaded).

Solution:

1. View the list of contexts: kubectl config get-contexts.
2. If the context does not exist, add it via kubectl config set-context or correct current-context:

   kubectl config set-current-context <существующий_контекст>
   

Issue: error: couldn't read client-certificate-file or client-key-file

Cause: The paths to certificates specified in kubeconfig are inaccessible or have incorrect permissions.

Solution:

1. Check the paths in kubeconfig (kubectl config view).
2. Ensure the files exist and are readable by your user:

   ls -l /путь/к/сертификату.crt
   

3. If certificates are embedded in kubeconfig (as certificate-authority-data), this error should not occur.

Issue: Kubeconfig works, but kubectl get pods returns Forbidden

Cause: The account specified in kubeconfig does not have permissions to view resources in the current namespace.

Solution:

1. Check which context you are working in: kubectl config current-context.
2. View what permissions the user has: kubectl auth can-i get pods --namespace=<namespace>.
3. Ask the cluster administrator to assign the necessary Role or ClusterRoleBinding.

Issue: Kubeconfig contains multiple clusters, but kubectl connects to the wrong one by default

Solution: Explicitly specify the context when running the command:

kubectl --context <имя_контекста> get pods

Or change the current context globally, as shown above.