At the end of the previous lesson you had a cluster started and verified with a couple of borrowed commands. Now let us go for the tool itself. kubectl is the official client for the Kubernetes API and it is going to be, by a wide margin, the program you use most in this course and in your professional life with Kubernetes: creating, querying, inspecting, debugging and deleting all go through it. The good news is that kubectl is extraordinarily regular: once you understand its grammar, you know how to use it with any type of object, including the ones that do not exist yet. This lesson teaches you that grammar, the configuration file that decides which cluster you talk to, the verbs you will use daily on the Rutas Norte components, the output formats that turn kubectl into a serious query tool, and the productivity settings that separate whoever fights the cluster from whoever works with ease.

1. What kubectl is, and installing it
2. The kubeconfig file: clusters, users and contexts
3. Anatomy of a kubectl command
4. The day-to-day verbs
5. Output formats and queries
6. Label selection and live watching
7. Imperative versus declarative
8. Productivity: aliases, completion, explain and plugins

kubectl has no intelligence of its own: it translates your commands into HTTPS requests against the kube-apiserver. Everything kubectl can do could be done by curl with the right certificate; what it adds is convenience, formatting and local validation.

Practical consequence: anything kubectl will not let you do is being forbidden by the server (RBAC), not by the tool.

Linux:

macOS:

Windows (PowerShell):

Verification:

Compatibility rule (version skew): kubectl supports a difference of one minor version above or below the server. A 1.30 client works with 1.29, 1.30 and 1.31 servers. With bigger gaps, specific commands can fail in ways that are not obvious, so keep the client close to the server.

When minikube said "kubectl is now configured to use rutas-norte" in the previous lesson, what it did was write to ~/.kube/config. That file answers three questions: which server do I talk to?, with which credentials? and in which default namespace?

The key idea: a context is a triple (cluster, user, namespace). Switching context means switching cluster or identity with a single command. In a professional environment you will have contexts such as rutas-norte-dev, rutas-norte-pre and rutas-norte-pro, and getting the context wrong is the quickest way to cause an incident.

That last command —setting the default namespace— will save you typing -n rutas-norte-dev hundreds of times during the course. Do it as soon as you create the namespace in lesson 01-07.

The KUBECONFIG variable: you can have several files and combine them. That is the usual arrangement when you work with several clients or environments:

Security tip: the kubeconfig contains credentials. Treat it like a private key: 600 permissions, never in Git, never over chat.

The whole CLI follows this grammar:

Examples read aloud:

Kubernetes accepts singular, plural and short name interchangeably. kubectl get po, kubectl get pod and kubectl get pods are identical. The short names that save the most typing:

The complete, authoritative list for your cluster, with short names, API group and whether the resource lives in a namespace:

The NAMESPACED column matters: it explains why kubectl get nodes -n rutas-norte-dev ignores the namespace (nodes are cluster-scoped).

Forgetting the namespace is the number one cause of "my pod has vanished".

We will work on a Rutas Norte scenario with the web store and the API already deployed in rutas-norte-dev.

How to read each column:

• READY 1/1: containers ready / total containers in the pod. 0/1 means the container exists but has not passed its readiness probe.
• STATUS: Running is normal; Pending (the scheduler finds no room), ContainerCreating, ImagePullBackOff (it cannot pull the image), CrashLoopBackOff (it starts and dies in a loop), Completed (finished tasks).
• RESTARTS: restarts. A growing number is the clearest sign of a problem.
• AGE: since the object was created.

In that output, notifications-worker is clearly broken. The next three verbs are how you investigate it.

The Events section is always the first thing to read. It is the diary of what the cluster has tried to do with that object and why it failed. Here it tells us that the container exits with code 1 and the kubelet retries with a growing back-off. We also see that the scheduler did assign it (so it is not a resource problem) and that the image pulled fine (so it is not a registry problem): the failure is inside the application.

describe works with any type: kubectl describe node rutas-norte, kubectl describe svc bookings-api, kubectl describe pvc postgres-data.

There is the cause: the worker cannot find redis-cache through DNS, probably because the Service does not exist yet. --previous is the most forgotten flag and the most useful: without it, in a CrashLoopBackOff you will see the logs of a container that has just started and has not failed yet.

The -- separates kubectl's flags from the command to run inside; forgetting it is a classic mistake. -it means interactive with a terminal, just as in Docker.

A professional note: many well-built images are distroless and have neither sh nor networking tools. For those cases there is kubectl debug, which injects an ephemeral container with utilities; we will see it in module 7.

apply is the heart of the declarative model and we will study it thoroughly in the next lesson, Objects, YAML Manifests and the Declarative Model.

About delete: remember that deletion is asynchronous and that deleting a pod managed by a controller does not remove it, it only causes a new one to be created. To remove it for real you have to delete the controller.

It opens the object in your editor ($EDITOR) and applies the changes when you save. It is convenient for experimenting and dangerous in production: the change does not end up in Git, so the next apply from the repository will silently revert it. Use it to explore; never as a way to deploy.

Now http://localhost:8080 reaches that pod. The format is local-port:container-port. It also works against a Service (svc/bookings-api 8081:80). It is the fastest way to check that something works before you have Ingress, and it is exactly what you will use in lesson 01-07 to see the Rutas Norte store in your browser. The process stays in the foreground: stop it with Ctrl+C.

This command deserves a paragraph of its own because it is the one that pays off most in the long run. It queries the schema of your own cluster, including the CRDs installed, so it never gives you stale information or information from another version. It works at any depth and, with --recursive, shows the complete tree of fields:

In the CKA/CKAD certification, where only the official documentation may be consulted, kubectl explain is the shortcut that saves minutes.

The -o flag turns kubectl from a viewer into a query tool.

custom-columns and jsonpath are the two tools that make kubectl fit for quick audits: "give me every image in use in production", "tell me which pods have no memory limits".

Remember from the lesson Key Concepts and Terminology that labels are the system's coupling mechanism. The -l flag gives you access to that same mechanism from the CLI:

That last query is the reason it is worth being disciplined about the project's labelling scheme: it lets you see, delete or inspect the entire platform with a single command.

Live watching with --watch (or -w): the command does not finish and prints changes as they happen. It is the best way to see the reconciliation loop in action:

You recognise that sequence: it is exactly the walkthrough from the lesson Kubernetes Architecture —Pending while the scheduler decides, ContainerCreating while the kubelet works, Running when the container is alive— happening in front of your eyes because the ReplicaSet has replaced a deleted pod.

Sibling commands that also wait:

kubectl supports both styles and it is worth having a view on when to use each.

The middle ground, and probably the most useful trick in the whole lesson: generate the manifest with an imperative command and save it, using --dry-run=client -o yaml.

This creates nothing in the cluster: it only prints the YAML kubectl would have sent. You edit it, version it and apply it. It is the usual way to avoid writing manifests from scratch, and in the CKAD it is practically mandatory if you want to finish in time. The next lesson goes deeper into --dry-run, kubectl diff and the internal mechanics of apply.

Add this to your ~/.bashrc or ~/.zshrc. The difference in comfort is enormous:

For zsh, swap completion bash for completion zsh. With this, k get po -n <TAB> even completes the names of the existing namespaces for you, because completion queries the API.

Other tools worth knowing about, even though we are not using them yet:

Installing krew and a plugin, by way of example:

None of this is essential, but on a real working day it saves hours. What matters is the previous part: aliases, completion and kubectl explain.

• Working in the wrong context. The most expensive mistake of all. Before any destructive command, kubectl config current-context. Configure your prompt to show context and namespace (kube-ps1, starship, oh-my-zsh) and treat it as non-negotiable as soon as you have access to a production environment.
• Forgetting the namespace. If an object "does not exist", try it with -A before concluding anything. Set the default namespace with kubectl config set-context --current --namespace=....
• Reading logs without --previous in a CrashLoopBackOff. You will see the current container starting up, not the error that killed the previous one.
• Omitting the -- in kubectl exec. Without it, kubectl reads your command's flags as its own and fails confusingly.
• Using kubectl edit as a deployment method. The change is not recorded anywhere and is lost on the next apply. It is for investigating, not for operating.
• Believing kubectl delete pod removes the application. If there is a controller behind it, the pod comes back. You have to delete the Deployment, or better, the manifest with kubectl delete -f.
• Ignoring kubectl explain. It is exact documentation for your version, with no internet connection and without switching windows. Get into the habit of using it before searching the web.
• Tip: memorise this diagnostic trio and always apply it in this order — kubectl get (does it exist and in what state?), kubectl describe (what has the cluster tried and what do the events say?), kubectl logs (what does the application say?). It resolves the vast majority of incidents.

On your rutas-norte cluster:

1. Show the active context and check that it is the right one.
2. Create the rutas-norte-dev namespace and set it as the context's default namespace.
3. List every pod in the cluster, from every namespace, showing the node and the IP.
4. Find out, without leaving the terminal and without searching the internet, what a pod's spec.restartPolicy field means and which values it accepts.
5. Show the kube-system pods sorted by age, from oldest to most recent.

Rutas Norte's security team asks for an inventory. Write the commands that answer:

1. Every image in use in the cluster, with the pod and the namespace it belongs to, in table format.
2. The pods of the whole cluster sorted by restart count, to spot the unstable ones.
3. Only the names of the pods carrying the label app.kubernetes.io/part-of=rutas-norte, in a format suitable for chaining with another command.
4. Every resource in the cluster that does not live in a namespace.

Without creating anything in the cluster, generate the YAML manifest of a pod called web-store with the image registry.rutasnorte.example/web-store:1.8.0, save it to k8s/base/web-store-pod.yaml, and then explain what the difference is between running that command with --dry-run=client and without it. As an extra check, use kubectl to find out whether the Pod resource belongs to the core API group or to apps.

Solution 1

Solution 2

Point 3 returns lines such as pod/bookings-api-6c8d7f9b45-2xk9p, which can be piped straight into kubectl delete or kubectl describe. Point 4 lists nodes, namespaces, persistentvolumes, storageclasses, clusterroles, among others: the cluster-scoped resources we saw in the concepts lesson.

Solution 3

The difference: with --dry-run=client, kubectl builds the object locally and prints it, sending nothing to the server; no pod is created and the cluster does not even need to be running. Without that flag, the request is sent to the apiserver, goes through authentication, authorization and admission, is written to etcd and the pod is really created. There is also --dry-run=server, which does send the request but tells the server not to persist it: it validates against the real admission webhooks without creating anything. We will see it in the next lesson.

For the API group:

The APIVERSION column shows a plain v1, with no slash and no group prefix: that means Pod belongs to the core group (or "legacy"), unlike Deployment, which appears as apps/v1.

kubectl is an HTTP client with a very regular grammar: verb, type, name and flags. Mastering it comes down to internalising that grammar, always knowing which context and namespace you are working in, handling the get → describe → logs diagnostic trio fluently, and taking advantage of the output formats and label selection to turn the CLI into a genuine query tool. With kubectl explain you also have exact documentation for your own cluster without leaving the terminal, and with aliases and completion the daily work stops being typing.

In this lesson we have used apply without fully explaining what it does inside, and we have seen YAML manifests without breaking down their structure. The next lesson settles that debt, Objects, YAML Manifests and the Declarative Model: the field-by-field anatomy of an object, API groups and versions, the YAML you need to know, the real difference between apply, create and replace, the tools for validating beforehand and how to organise the Rutas Norte manifests in the k8s/ directory.