What is kubectl and how do you use it?
Author: Domeny.ForSale editorial team Published
In brief: kubectl is a command-line tool for working with Kubernetes — a system that manages applications running in containers. It lets you check application status, deploy changes, read logs and manage cluster resources. It is not Kubernetes itself, nor does it automatically create an environment for running applications: it needs access to an existing cluster.
How kubectl works with Kubernetes
A Kubernetes cluster is an environment made up of machines, called nodes, and components that manage the running of applications. A container packages an application together with its dependencies. Kubernetes runs containers in units called Pods; a Pod can contain one or more containers that work together.
kubectl runs on an administrator’s or developer’s computer, or in a deployment automation system. It sends requests to the API server of Kubernetes, the communication endpoint used to read and modify cluster resources. It does not control each container directly — the components of Kubernetes perform the actions needed to reach the desired state.
For example, if you request that three copies of an application be maintained, kubectl sends that configuration to the API. Kubernetes then works to keep the required copies running. You can close the terminal: the application does not depend on the kubectl process continuing to run.
What you need to get started
Installing kubectl alone is not enough. You need a cluster — a local test environment, for example one created with kind or minikube, or a cluster provided by your company or a cloud provider — and permission to use it.
Connection details are usually stored in a kubeconfig file. It contains cluster addresses, authentication settings or references to login mechanisms, and contexts. A context specifies which cluster you are working with and which user identity you are using; it can also specify a default namespace. A namespace groups resources within a cluster.
The default configuration location is $HOME/.kube/config, but you can specify another file. Before starting work, check the client and the active connection:
kubectl version --client
kubectl config current-context
kubectl cluster-info
The first command checks the version of the local tool without confirming access to the cluster. The second shows the selected context, and the third attempts to retrieve cluster information. Errors may be caused by missing configuration, network problems, an expired login or insufficient permissions.
Check the official Kubernetes documentation for installation instructions and supported version differences between the client and server. In a company environment, also follow the administrator’s login instructions.
Basic commands for checking applications
Commands usually take the form kubectl verb resource-type name. Options let you select a namespace and an output format, among other things. Read operations are the most useful place to start:
| Command | Purpose |
|---|---|
kubectl get pods -n test | Lists Pods in the test namespace and shows their basic status. |
kubectl describe pod NAME -n test | Shows Pod details and events that can help with diagnosis. |
kubectl logs NAME -n test | Reads container logs from the specified Pod. |
kubectl get deployments -n test | Shows the status of resources that manage copies of an application. |
Replace NAME with the actual Pod name. If the Pod has several containers, you may need the -c CONTAINER_NAME option when reading logs.
Suppose an application stops responding after deployment. Start with get pods to check whether its Pods are running. Next, use describe to look for events related to issues such as pulling the image or starting the container, then read the application logs. A Pod’s status alone is not always enough to determine the cause of a problem.
How to deploy changes using a YAML file
kubectl can create resources with individual commands, but application configuration is often stored in a manifest — a file describing the desired state of resources. YAML is the most common format. You can keep this file in a repository and review changes to it before deployment.
The following manifest creates a Deployment, a resource that maintains a specified number of application copies and manages their updates:
apiVersion: apps/v1
kind: Deployment
metadata:
name: demo
spec:
replicas: 1
selector:
matchLabels:
app: demo
template:
metadata:
labels:
app: demo
spec:
containers:
- name: nginx
image: nginx:stable
Save it as deployment.yaml. In a test cluster, you can apply the configuration and check its progress:
kubectl apply -f deployment.yaml
kubectl rollout status deployment/demo
kubectl get pods -l app=demo
This example starts an nginx server, but does not automatically make it accessible over the internet. Network access requires additional configuration, often a Service resource that directs traffic to Pods. Running the example also depends on being able to pull the image and having sufficient resources available in the cluster.
How to avoid changing the wrong environment
kubectl can work with both test and production environments. Before performing an operation that changes resources, check the context and namespace. You can specify them explicitly with the --context and -n options rather than relying on defaults.
Before applying a manifest, two useful commands are kubectl diff -f deployment.yaml, which shows differences from existing resources, and kubectl apply --dry-run=server -f deployment.yaml, which sends a trial request without saving the change. Neither guarantees that the application will work correctly after deployment.
The delete command removes resources and may interrupt the application. Treat kubeconfig as a sensitive file: do not publish it in a repository or use configuration from an untrusted source. Do your first exercises in a test cluster, starting by checking the context and reading the status of Pods.
See also: What is FTP?
Read also
