KubeCTL

Command-line tool for communicating with the Kubernetes API server to manage cluster resources.

Table of Contents#

Overview
Installation and Configuration
Basic Commands
Common Resource Short Names
Output Formatting
Troubleshooting
See Also
Sources

1. Overview#

kubectl is the official command-line interface for Kubernetes. It communicates with the Kubernetes API server to deploy applications, inspect and manage cluster resources, and view logs. Almost every Kubernetes operation can be performed through kubectl.

The tool reads cluster connection details from a kubeconfig file (default: ~/.kube/config), which defines clusters, users, and contexts.

2. Installation and Configuration#

2.1 Prerequisites#

Network access and appropriate RBAC permissions to a Kubernetes cluster
A valid kubeconfig file with cluster credentials

2.2 Installation via Package Managers#

On Windows#

Using Chocolatey:

choco install kubernetes-cli

Using winget:

winget install Kubernetes.kubectl

On macOS#

Using Homebrew:

brew install kubectl

On Linux#

Using apt (Debian/Ubuntu):

# Add the Kubernetes apt repository
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list

sudo apt-get update && sudo apt-get install -y kubectl

Using dnf (Fedora/RHEL/CentOS):

sudo dnf install -y kubectl

Using pacman (Arch Linux):

sudo pacman -S kubectl

2.3 Configuring kubectl#

Set the KUBECONFIG environment variable or place the config file at the default path:

# Use default location
cp <kubeconfig-file> ~/.kube/config

# Or set the environment variable to use a custom path
export KUBECONFIG=/path/to/kubeconfig.yaml

# Merge multiple kubeconfig files
export KUBECONFIG=~/.kube/config:/path/to/other-config

# Verify connectivity
kubectl cluster-info

3. Basic Commands#

3.1 Viewing Cluster and Resource Information#

Action	Command
View cluster info	`kubectl cluster-info`
List nodes	`kubectl get nodes`
List all namespaces	`kubectl get namespaces`
List all API resources	`kubectl api-resources`
View cluster component status	`kubectl get componentstatuses`

3.2 Resource Management Commands#

Action	Command
Create a deployment	`kubectl create deployment <name> --image=<image>`
List pods	`kubectl get pods`
List pods (all namespaces)	`kubectl get pods -A`
List services	`kubectl get svc`
Expose a deployment	`kubectl expose deployment <name> --type=LoadBalancer --port=<port>`
Edit a deployment	`kubectl edit deployment <name>`
Scale a deployment	`kubectl scale deployment <name> --replicas=<count>`
Delete a deployment	`kubectl delete deployment <name>`
Apply a manifest	`kubectl apply -f <file.yaml>`
Delete from a manifest	`kubectl delete -f <file.yaml>`

3.3 Cluster Management Commands#

Action	Command
Apply configuration from file	`kubectl apply -f <file.yaml>`
Drain a node for maintenance	`kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data`
Uncordon a node after maintenance	`kubectl uncordon <node-name>`
Cordon a node (mark unschedulable)	`kubectl cordon <node-name>`
Taint a node	`kubectl taint nodes <node-name> <key>=<value>:<effect>`

3.4 Debugging Commands#

Action	Command
View pod logs	`kubectl logs <pod-name>`
View previous container logs	`kubectl logs <pod-name> --previous`
Follow logs in real time	`kubectl logs -f <pod-name>`
Exec into a pod	`kubectl exec -it <pod-name> -- /bin/bash`
Describe a resource	`kubectl describe <resource-type> <name>`
Port-forward to a pod	`kubectl port-forward <pod-name> <local-port>:<pod-port>`
Run a temporary debug pod	`kubectl run debug --rm -it --image=busybox -- sh`

4. Common Resource Short Names#

Resource Type	Short Name
Certificate Signing Requests	`csr`
Config Maps	`cm`
DaemonSets	`ds`
Deployments	`deploy`
Endpoints	`ep`
Events	`ev`
Horizontal Pod Autoscalers	`hpa`
Ingresses	`ing`
Limit Ranges	`limits`
Namespaces	`ns`
Nodes	`no`
Persistent Volume Claims	`pvc`
Persistent Volumes	`pv`
Pods	`po`
Pod Disruption Budgets	`pdb`
ReplicaSets	`rs`
Replication Controllers	`rc`
Resource Quotas	`quota`
Service Accounts	`sa`
Services	`svc`
StatefulSets	`sts`
Storage Classes	`sc`

Note: Pod Security Policies (psp) were removed in Kubernetes 1.25 (August 2022). Use Pod Security Standards with the built-in Pod Security Admission controller instead.

5. Output Formatting#

kubectl supports multiple output formats for scripting and readability:

# Wide output with additional columns
kubectl get pods -o wide

# JSON output
kubectl get pods -o json

# YAML output
kubectl get pods -o yaml

# Custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase

# JSONPath for extracting specific fields
kubectl get pods -o jsonpath='{.items[*].metadata.name}'

# Sort output by a field
kubectl get pods --sort-by=.metadata.creationTimestamp

Troubleshooting#

Issue	Cause	Solution
"The connection to the server was refused"	Cluster is unreachable or kubeconfig is wrong	Verify `KUBECONFIG` path; run `kubectl config view` to check the server URL
"error: You must be logged in to the server (Unauthorized)"	Expired or invalid credentials in kubeconfig	Refresh credentials; check token expiry; re-export kubeconfig from the cluster
"No resources found in default namespace"	Resources exist in a different namespace	Add `-A` for all namespaces or `-n <namespace>` to target the correct one
kubectl is slow or hangs	Network timeout reaching the API server	Check network connectivity; try `kubectl cluster-info` to confirm reachability
"unable to recognize file: no matches for kind"	API version in the manifest does not match cluster	Run `kubectl api-versions` to list supported versions; update the manifest accordingly