2.2. kubectl and Manifests
In this lab, you see how kubectl finds your cluster, create a Pod in two different ways and
explore the API.
Step 1: Inspect the Context
kubectl reads the connection details of your clusters from the kubeconfig (~/.kube/config). List the contexts
it contains:
If you have worked with other clusters before, you see more contexts. The * marks the current one.
Explanation
A context combines a cluster (CLUSTER) with a user (AUTHINFO) that kubectl logs in with. k3d created the
context k3d-labs in 2.1. The column NAMESPACE is empty, so kubectl works in the Namespace
default, the namespace for your own resources. The add-ons from 2.1 run in kube-system.
Step 2: Create a Pod Imperatively
Tell kubectl directly to create a Pod named hello that runs the web server nginx:
List the Pods:
If the status is ContainerCreating, the image is still downloading. Wait a moment and repeat the command.
Delete the Pod again, because Step 3 creates it from a manifest:
Explanation
This is the imperative way: you tell kubectl what to do, one command at a time. It’s quick for trying something
out, but no file records what you created. To create the same Pod again, you have to remember the command.
Step 3: Create a Pod Declaratively
Create a directory for the files of this lab and change into it:
Create the file hello.yaml in ~/labs/2.2 with your editor or IDE and the following content:
Apply the manifest:
Apply it a second time:
Explanation
This is the declarative way: the manifest describes the state you want, and kubectl apply makes the cluster match
it. The cluster already matches after the first apply, so the second one changes nothing.
Most manifests have the same four top-level fields:
| Field | Meaning |
|---|---|
apiVersion | Version of the API that defines the resource type |
kind | Resource type |
metadata | Identifies the resource, at least with a name |
spec | Desired state, here one container from the image nginx:1.29 |
Keep the file: you can create the same Pod again at any time, and you can store it in Git like your source code.
Step 4: Explore the API
List the resource types your cluster knows:
Watch how kubectl talks to the API server. -v=6 logs every request it sends:
Show the documentation of a resource type:
Follow the fields down to the image of a container:
Explanation
kubectl api-resources lists about 70 resource types. pods and nodes appear a second time with the API version
metrics.k8s.io/v1beta1, which is the CPU and memory usage collected by the metrics-server. The columns tell you
how to use each resource type:
| Column | Meaning |
|---|---|
NAME | Name for kubectl, e.g. kubectl get pods |
SHORTNAMES | Shorter alternative, e.g. kubectl get po |
APIVERSION | Value for apiVersion in a manifest |
NAMESPACED | true if the resource lives in a namespace |
KIND | Value for kind in a manifest |
APIVERSION is the API group and its version: apps/v1 is version v1 of the group apps. Core types like
Pod have no group, only v1. v1beta1 marks a beta version that may still change.
kubectl is a client of the REST API of Kubernetes: kubectl get pods sent a GET request to the API server at
the address from your kubeconfig (the paths and the port differ on your machine). The URL is built from what
kubectl api-resources lists: the API version v1, the namespace default and the resource type pods.
kubectl explain documents every field you can write in a manifest. Separate the fields with dots to go deeper.
Optional Tasks
Finished early? Try these tasks. The following labs don’t depend on them. Each task lists the commands you need. Open the solution if you get stuck.
Task 1: Spot the Difference
Compare your manifest hello.yaml with the Pod that Kubernetes stores.
| Command | Effect |
|---|---|
kubectl get <type> <name> -o yaml | Shows the complete resource as YAML |
Task 2: Whack-a-Pod
Delete your Pod hello and the CoreDNS Pod in the namespace kube-system. Which one comes back?
| Command | Effect |
|---|---|
kubectl get pods -n <namespace> --watch | Lists the Pods and keeps running: every change prints a new line |
kubectl delete pod <name> -n <namespace> | Deletes a Pod in a namespace |
Stop a running --watch with Ctrl+C.
Task 3: Manifest Generator
Let kubectl write a manifest for you instead of typing it.
| Command | Effect |
|---|---|
kubectl run <name> --image=<image> --dry-run=client -o yaml | Prints the manifest of the Pod instead of creating it |
Clean Up
Delete the Pod, since the following labs don’t need it: