Installing kubectl on Linux: A Complete Beginner's Guide

Introduction / Why You Need This

kubectl is the command-line interface (CLI) for managing Kubernetes clusters. With it, you deploy applications, inspect the state of resources, manage configuration, and debug operations within the cluster. Without kubectl, interacting with Kubernetes reduces to direct API calls, which is extremely inconvenient.

After completing this guide, you will have kubectl installed and ready to use. You will be able to connect to any Kubernetes cluster (a managed service like GKE/EKS/AKS or self-managed) and perform basic operations.

Prerequisites / Preparation

Before you begin, ensure that:

1. You have access to a Linux terminal (Ubuntu, CentOS, Debian, Fedora, etc.) with sudo privileges.
2. curl (usually installed by default) or wget is installed on the machine.
3. You know the URL and have credentials to access the target Kubernetes cluster (this is needed for the kubeconfig setup step).

Step 1: Adding the Official Kubernetes Repository

The recommended installation method is through the official pkgs.k8s.io repository. This guarantees you get up-to-date and verified versions.

For Debian/Ubuntu-based distributions (apt):

# 1. Download and add the repository's GPG key
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# 2. Add the repository itself to sources.list.d
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# 3. Update the package cache
sudo apt-get update

💡 Tip: Replace v1.28 in the URL with the minor version of Kubernetes you need (e.g., v1.29). You can check the current version on the release page.

For RHEL/CentOS/Fedora-based distributions (yum/dnf):

# 1. Create a repository file
sudo tee /etc/yum.repos.d/kubernetes.repo <<EOF
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/repodata/repomd.xml.key
EOF

# 2. Update the repository cache (for CentOS/RHEL 7, you may need to enable a module)
sudo yum makecache

⚠️ Important: For CentOS/RHEL 7, you may need to explicitly enable the module: sudo yum module enable -n containerd or sudo yum install -y containerd.

Step 2: Installing the kubectl Package

Now that the repository is added, install the package itself.

For apt (Ubuntu/Debian):

sudo apt-get install -y kubectl

For yum/dnf (CentOS/RHEL/Fedora):

# On CentOS/RHEL 7, use yum
sudo yum install -y kubectl

# On Fedora and newer RHEL/CentOS, use dnf
sudo dnf install -y kubectl

The command will install the kubectl binary to a system directory (usually /usr/local/bin or /usr/bin).

Step 3: Verifying Installation and Setting Up Autocompletion

Verify the installation was successful:

kubectl version --client

The output should show the client version, for example:

Client Version: v1.28.4

If the command is not found (command not found), check if the installation directory is in your PATH:

echo $PATH | grep -q '/usr/local/bin' || echo "Add /usr/local/bin to your PATH"

Setting up Tab autocompletion (significantly speeds up work):

# For bash
source <(kubectl completion bash)
echo "source <(kubectl completion bash)" >> ~/.bashrc

# For zsh
source <(kubectl completion zsh)
echo "source <(kubectl completion zsh)" >> ~/.zshrc

Step 4: Configuring Cluster Connection (kubeconfig)

kubectl looks for cluster configuration in the file ~/.kube/config. You can obtain it in several ways:

1. From the cluster administrator: They will provide you with a config file or a command to retrieve it.
2. Cloud provider services:
   • GKE (Google): gcloud container clusters get-credentials CLUSTER_NAME --zone ZONE --project PROJECT_ID
   • EKS (AWS): aws eks update-kubeconfig --name CLUSTER_NAME --region REGION
   • AKS (Azure): az aks get-credentials --resource-group RG_NAME --name CLUSTER_NAME
3. Local cluster (Minikube): minikube start will automatically configure the config.

After configuration, verify access:

kubectl cluster-info

If you see the API server URL — the connection is established.

Step 5: Basic Commands to Verify Functionality

Run a few simple commands to ensure everything works:

# Show cluster information
kubectl get nodes

# Show namespaces
kubectl get namespaces

# Get help for any command
kubectl get --help

If kubectl get nodes outputs a list of your cluster's nodes (or for Minikube, one node named minikube), installation and configuration are complete.

Verifying the Result

Readiness is confirmed by:

1. The kubectl version --client command returns the version without errors.
2. The kubectl cluster-info command shows data about the connected cluster (or an authentication error if the config is incorrect, but the client itself works).
3. Tab autocompletion suggests resources and names.

Potential Issues

Error: The connection to the server localhost:8080 was refused

Cause: The ~/.kube/config file is missing or does not contain valid cluster data. Solution: Configure kubeconfig as per Step 4. Ensure you ran the command from the cloud provider or obtained the configuration file.

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

Cause: The config contains invalid credentials (certificate, token, login/password). Solution: Recreate the configuration by obtaining new credentials from the cluster administrator or via the cloud provider CLI (gcloud, aws, az).

Error: kubectl: command not found after installation

Cause: The directory where the binary is installed (e.g., /usr/local/bin) is not in the current session's PATH. Solution: Add the path to PATH in ~/.bashrc or ~/.zshrc and restart the terminal. Alternatively, create a symlink: sudo ln -s /usr/local/bin/kubectl /usr/bin/kubectl.

Package installation error: Unable to read /etc/apt/sources.list.d/...

Cause: The repository file was created incorrectly or the GPG key is missing. Solution: Check Step 1. Ensure you used sudo to write to system directories. Recreate the repository file and key.

kubectl version is incompatible with the cluster

Cause: The version difference is more than one minor version. Solution: Install a different version of kubectl by specifying the desired repository tag (e.g., v1.27 instead of v1.28). Alternatively, upgrade or downgrade the cluster itself.

# Example of installing a specific version on Ubuntu
sudo apt-get install kubectl=1.27.5-00

# Example on CentOS/RHEL
sudo yum install kubectl-1.27.5