Kubernetes Basics: Your First Cluster and Pod

kind boots a single-node Kubernetes cluster where the node itself is a Docker container. The --name lab flag names the cluster (and its kubectl context, which becomes kind-lab), so you can run several throwaway clusters side by side without them colliding. The first run pulls the kindest/node image, which is a few hundred MB, so expect a minute or two; later clusters on the same machine start in seconds.

kind also merges credentials into your kubeconfig (~/.kube/config) and switches the active context automatically, which is why kubectl works immediately afterwards with no extra configuration.

Verify: the cluster answers and the context is what you expect.

Common mistake: running this with Docker Desktop closed. The error Cannot connect to the Docker daemon means exactly that, start Docker and retry. Also note the API server port (51234 above) is random per machine; never hard-code it.

Expected output:

$ kind create cluster --name lab
Creating cluster "lab" ...
  Ensuring node image (kindest/node:v1.36.1)
  Ready: nodes joined the cluster

What this teaches: A local cluster gives you a real control plane for free; creation is the only step that differs from the cloud.

Before deploying anything of your own, confirm the cluster itself is healthy. kubectl get nodes shows the machines Kubernetes can schedule onto, and listing pods in kube-system shows the control plane's own workloads. A fresh kind cluster has exactly one node, which is both control plane and worker.

Those kube-apiserver, etcd, kube-scheduler, and kube-controller-manager pods are the control plane from the architecture diagram, running as static pods on the node. If any of them is not Running, stop here and fix the cluster before continuing, nothing else will work reliably.

Common mistake: forgetting -n kube-system and concluding the cluster is broken because kubectl get pods shows No resources found in default namespace. That just means your namespace is empty, which is expected right now.

Expected output:

$ kubectl get nodes
NAME               STATUS   ROLES
lab-control-plane  Ready    control-plane

What this teaches: System pods are Kubernetes running itself; a healthy cluster shows them all Running before you deploy anything.

A Deployment declares desired replicas; the controller keeps that many pods running. You could create a bare pod with kubectl run, but a bare Pod has no controller behind it: its containers restart according to restartPolicy, yet if the Pod object itself is deleted, or its node dies, nothing recreates it, it is gone forever. A Deployment creates a ReplicaSet, and the ReplicaSet's whole job is to notice a missing pod and replace it, that is the self-healing you will test later. Always wrap workloads in a Deployment (or StatefulSet/DaemonSet) in real life.

Breaking the command down: web is the Deployment's name (and the app=web label the pods inherit, which you will use for selectors later), --image=nginx:stable is the container image pulled from Docker Hub, and --replicas=2 is the desired count written into etcd. The moment the record exists, the scheduler and ReplicaSet controller act on it, you never touched a node yourself.

Verify: the Deployment reports both replicas available.

Common mistake: using a tag that does not exist (e.g. nginx:stabel). The Deployment is created happily, the failure only shows up later as ImagePullBackOff on the pods, because the spec itself was valid. The object existing is not proof the workload is running.

Expected output:

$ kubectl create deployment web --image=nginx:stable
deployment.apps/web created

What this teaches: Imperative kubectl create is the fastest way to get a first deployment; declarative manifests come later in this lab.

kubectl get is your microscope. With -o wide it adds the node and IP columns; kubectl describe shows the full event history of an object, which is where you look first when something is stuck. Get comfortable reading both before moving on.

The pod names tell a story: web (Deployment) → 6f... (ReplicaSet hash) → a1b2 (random pod suffix). That nesting is the object hierarchy you just created. To see all of it at once:

Verify: kubectl describe deployment web should end with an event like Scaled up replica set web-6f... to 2. If a pod is stuck, kubectl describe pod web-6f...-a1b2 shows exactly which stage (pulling, scheduling, starting) is failing, with the reason in the Events section at the bottom.

Expected output:

$ kubectl get deployments,pods
NAME                 READY   UP-TO-DATE
deployment.apps/web 2/2     2
NAME                     READY   STATUS
pod/web-7c9c5f6b8d-x1y2z 1/1    Running
pod/web-7c9c5f6b8d-z9a8b 1/1    Running

What this teaches: Inspecting the cluster teaches the object model: deployments own ReplicaSets, ReplicaSets own pods.

Scaling is just editing the replica count in the desired state, the ReplicaSet controller does the rest. This is the fastest way to feel the reconciliation loop: change a number, watch reality catch up.

The -w (watch) flag streams changes live, press Ctrl+C to stop it. Watching the transition from ContainerCreating to Running is the reconciliation loop made visible. Now scale back down so the self-healing test later stays readable:

Common mistake: editing a pod directly to "scale", pods are disposable units, not the place where state lives. Any change you make to a single pod (including deleting it) is overridden by the controller. Always change the Deployment, never the pod.

Expected output:

$ kubectl scale deployment web --replicas=4
deployment.apps/web scaled

What this teaches: Scaling is changing desired state and watching the controllers converge; the speed of convergence is the platform's job.

Two commands you will use daily: kubectl logs streams a container's stdout/stderr, and kubectl exec opens a shell inside a running container for live debugging. These work on any pod, in any cluster, with no SSH keys or node access required, one of the biggest operational wins over managing VMs by hand.

Using deploy/web instead of a pod name is a handy trick: kubectl picks one of the Deployment's pods for you, so you do not have to copy a random pod suffix. To look around inside the container:

OPEN A SHELL INSIDE A POD

kubectl exec -it deploy/web -- /bin/sh
# inside the container:
cd /usr/share/nginx/html && ls
cat /etc/nginx/nginx.conf | head -20
exit

Expected output:

$ kubectl logs deploy/web --tail=1
/docker-entrypoint.sh: Configuration complete; ready for start up

Verify: while inside, run hostname, it prints the pod name, confirming you are genuinely inside that pod's network namespace. If exec fails with executable file not found, the image is minimal (distroless/scratch) and has no shell; use kubectl debug with an ephemeral container instead.

What this teaches: Logs and exec are the debugging pair: logs show what the app said, exec shows what the app sees.

Imperative commands like kubectl create and kubectl scale are fine for learning, but they are not reproducible, nothing records why the cluster looks the way it does. Real teams declare the desired state in YAML, store it in git, and apply it. Kubernetes merges the manifest into the live object, so the file becomes the source of truth. Generate a starting manifest from the running Deployment instead of writing one from scratch:

Strip the server-managed fields (status:, resourceVersion, uid, creationTimestamp) and you are left with the clean, minimal manifest:

web-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:stable
          ports:
            - containerPort: 80

Expected output:

$ kubectl apply -f web-deployment.yaml
deployment.apps/web configured

Change replicas to 3 in the file, then apply it:

Note the word configured instead of created, apply is idempotent. Run it twice and the second run prints unchanged. That property is what makes manifests safe to keep in CI pipelines.

Common mistake: applying the raw -o yaml dump without removing the status block and server fields. It usually still works, but the file is noisy and some fields cause warnings. Always trim to the minimal spec shown above.

What this teaches: Declarative manifests are versionable desired state; apply becomes the only deployment verb.

Every change to a Deployment's pod template creates a new revision, and kubectl keeps the history. This means a bad image push is a 10-second fix, not an outage: roll back to the previous ReplicaSet and the old pods come back.

Current kubectl versions deprecated and ignore --record, so CHANGE-CAUSE stays <none>; revision numbers are the reliable identifier. To undo that image change instantly:

Verify: kubectl get deployment web -o jsonpath='{.spec.template.spec.containers[0].image}' prints nginx:stable again after the undo finishes.

Expected output:

$ kubectl rollout history deployment/web
REVISION  CHANGE-CAUSE
1         <none>
2         <none>

What this teaches: Revision history makes rollbacks boring, which is exactly what you want from a safety mechanism.

The defining promise of Kubernetes is that it repairs itself. Do not take it on faith, delete exactly one web pod by name and watch the ReplicaSet replace it. Deleting by name matters here: a label selector such as -l app=web would delete every matching pod at once, which is a different and more destructive test.

Within seconds the Deployment should report full readiness again, proving self-healing:

Read the pod ages carefully: the replacement pod web-6f...-j9k0 is 4 seconds old with a fresh random suffix, while its siblings are untouched. Nobody restarted anything by hand, the ReplicaSet controller saw current=2, desired=3 and created a pod to close the gap. That is the reconciliation loop from the architecture diagram, observed end to end.

What this teaches: self-healing is the ReplicaSet controller reconciling desired versus actual state, no manual intervention required.