Kubectl Absolute Basics

If you are already using Kubectl, this article is not for you. I wrote this as an on-boarding material for new employees. The aim of the article is to provide the minimum necessary instructions on how to inspect and debug running applications.

The Kubeconfig

After retrieving redentials to a Kubernetes cluster, e.g. on GCP, Azure or AWS, a “context” is created and merged it into your Kubeconfig. The kubeconfig is a yaml file that is normally stored in your home folder at ${HOME}/.kube/config. Although it may be interesting to look at the file directly, modifications to the config will normally happen using kubectl config commands.

To view the contexts listed in the kubectl file, run:

kubectl config get-contexts

Chances are that your namespace is set to ‘default’ or completely unset. To make changes to the context, such as changing the default namespace, use the kubectl config set-context command. For example, to set the default namespace to seb, I would run:

kubectl config set-context --current --namespace=seb

Listing resources

There are a ton of different resources in Kubernetes. The most simple way to list resources is to just use kubectl get:

kubectl get pods
kubectl get services
kubectl get deployments

The three commands above can all be run in one command by comma-separating the resources:

kubectl get pods,services,deployments

To list all resources in your namespace, you can run:

kubectl get all

All kubectl commands implicitly use the namespace set in your config, to view resources from another namespace, add the --namespace flag:

kubectl get all --namespace kube-system

To view a certain resource in all namespaces, use the --all-namespaces flag:

kubectl get services --all-namespaces

Some Kubernetes resources have shorthands. For example, kubectl get services can be replaced with kubectl get svc. To list these shorthands, run

kubectl api-resources

Kubectl has a built-in --watch flag. It will show any changes to the state of the output as a new row in the output. I personally prefer the Unix watch since it will replace the rows in-place instead of print new lines in my terminal:

# run kubectl get pods every 0.2s
watch -n 0.2 kubectl get pods

Listing by labels

If your pod has labels, you can list these labels with the --show-labels flag. Be sure to have a wide screen:

kubectl get pods --show-labels

These labels can be used to filter resources. To only show pods with the label tier=frontend, we pass this filter to the -l flag:

kubectl get pods -l "tier=frontend"

If you only care about the existence of a label, just pass in the label name:

kubectl get pods -l "tier"

Inspecting resources

Listing using get is cool and all, but often you want more details. For this you can use the describe command:

kubectl describe service orders-api

For pods and services, view logs with:

kubectl logs my-pod-name

If you have multiple pods running behind a service, running the log command on the service will show logs from all pods that match the service route (matchLabels).

To follow the log, add the -f flag:

kubectl logs -f svc/my-service

Running a shell inside a running Pod

If the Docker image being run by your Pod has some shell installed, you can run a shell inside the running pod to inspect state. For example, to run bash on a pod called my-pod, run:

kubectl exec -it my-pod bash

Note that since the exec command only can be run on pods, there is no need to specify the resource type.

Running ad-hoc Pods

You may also run pods directly in the cluster using kubectl run. For example, to run a pod called mycurlrun that is interactive, and that will be cleaned up when you are finished, run:

kubectl run -it --rm --image=pstauffer/curl mycurlrun

Note: I highly suggest to avoid running pods like this. There is a great tool called Telepresence which allows you to run a local shell that can interact with resources internal to Kubernetes. By running

telepresence --run bash

You will achieve the above result while keeping all the tools on your local machine available to you. I have written a more in-depth article on Telepresence that you may bookmark for further reading once Kubernetes is more familiar to you.

Starting, restarting and stopping pods

Unlike Docker containers, you don’t start, restart or stop pods in Kubernetes. If you wish to reboot a pod that is part of a deployment, delete it with:

kubectl delete pod my-pod

And the pod will automatically be re-created.

What next?

There are tons of great resources on Kubernetes. I highly recommend bookmarking the Kubectl Cheat Sheet.