Kubernetes, Hands-On

kubectl config current-context
kubectl get nodes -o wide
kubectl get pods

kind-k8s-lab

NAME                    STATUS   ROLES           AGE   VERSION   INTERNAL-IP
k8s-lab-control-plane   Ready    control-plane   8m    v1.34.0   172.18.0.4
k8s-lab-worker          Ready    <none>          7m    v1.34.0   172.18.0.2
k8s-lab-worker2         Ready    <none>          7m    v1.34.0   172.18.0.3

No resources found in default namespace.

"No resources found" is correct, not an error. You have not deployed anything yet.

The context tells kubectl which cluster to talk to. You have only one today. In a job you will have three or four, including production. Check your context before you run anything that deletes. It takes two seconds and it prevents very bad days.

Why your apps will never run on the control plane

The control plane is healthy and has free space. Your Pods will still not go there. Here is the reason:

kubectl describe node k8s-lab-control-plane | grep -i -A1 taints

Taints:   node-role.kubernetes.io/control-plane:NoSchedule

A taint is a "keep out" sign on a node. Your app does not have a pass, so it is never placed there. This is on purpose. If your app used all the memory on the control plane, you would lose the ability to fix anything.

Kubernetes runs itself as Pods

kubectl get pods -n kube-system -o wide

A namespace is a folder inside the cluster. Your work goes in default. Kubernetes keeps its own parts in kube-system. Look at the NODE column and you will see a pattern:

You will run nginx, a real web server. In Docker that was docker run -d nginx. Here you write the wish down instead.

nano deployment.yaml

Type this in. YAML uses spaces, never tabs. Two spaces per level. If your editor adds tabs, fix it now.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:stable
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"

Save with Ctrl+O, Enter. Exit with Ctrl+X.

Check the file first, then apply it. Then ask when it is ready instead of guessing:

kubectl apply --dry-run=client -f deployment.yaml
kubectl apply -f deployment.yaml
kubectl wait --for=condition=Available deployment/nginx --timeout=120s
kubectl get pods -o wide

deployment.apps/nginx created
deployment.apps/nginx condition met

NAME                     READY   STATUS    RESTARTS   AGE   IP           NODE
nginx-7c9f4d8b6d-k2xvp   1/1     Running   0          20s   10.244.1.4   k8s-lab-worker
nginx-7c9f4d8b6d-m8ztq   1/1     Running   0          20s   10.244.2.3   k8s-lab-worker2
nginx-7c9f4d8b6d-p4wnc   1/1     Running   0          20s   10.244.1.5   k8s-lab-worker

One file, three objects

kubectl get deployments
kubectl get replicasets
kubectl get pods

Read the three names. The whole story is in them:

Deployment:   nginx
ReplicaSet:   nginx-7c9f4d8b6d
Pod:          nginx-7c9f4d8b6d-k2xvp

• Deployment — what you wrote. It handles new versions (step 5).
• ReplicaSet — made for you. Its only job is "exactly three must exist" (step 4).
• Pod — made by the ReplicaSet. One running copy, with its own IP address.

You created one thing. Kubernetes built the other two and keeps them correct, forever.

What happened when you pressed Enter

This is worth 60 seconds, because it explains most confusing errors later.

1. kubectl sends your file to the API server over HTTPS.
2. The API server checks who you are, checks you are allowed, and saves it in etcd. Then it replies created.
3. Your command is finished here. Nothing is running yet.
4. Controllers notice the new Deployment and create a ReplicaSet, then Pods with no node.
5. The scheduler picks a node for each Pod. The kubelet on that node starts the container.

Nobody in that list talks to anybody else. They all watch the API server and react. This is why created means "your wish was saved", not "your app is running", and why you used kubectl wait above.

You can see the handover written down:

kubectl describe deployment nginx | tail -n 8

That Events block is the object's diary. When something breaks later today, look here first.

Those Pod IP addresses disappear when the Pod does. You will see that in step 4. You cannot build anything on an address that disappears. That is why we need a Service.

nano service.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80          # the Service's port inside the cluster
      targetPort: 80    # the port inside the container
      nodePort: 30000   # the port you type in your browser

Note apiVersion: v1 here, but apps/v1 in the Deployment. Services are older and belong to the core group. Copying the wrong one gives a confusing error.

kubectl apply -f service.yaml
kubectl get services
kubectl get endpoints nginx

NAME         TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
kubernetes   ClusterIP   10.96.0.1      <none>        443/TCP        18m
nginx        NodePort    10.96.142.88   <none>        80:30000/TCP   4s

NAME    ENDPOINTS                                   AGE
nginx   10.244.1.4:80,10.244.1.5:80,10.244.2.3:80   4s

Now open your normal browser on Windows, Chrome or Edge:

http://localhost:30000

You should see the "Welcome to nginx!" page. 🎉 No tunnel. No terminal held open. You could close Ubuntu and the page would still load.

Three ports, and people mix them up

Your request reached a Pod on a worker, but you knocked on the control plane. A NodePort opens on every node, and Kubernetes forwards it to whichever node has a Pod.

The other way in: a quick tunnel

Sometimes you just want to look at an app without opening a port. Open your second terminal:

kubectl port-forward service/nginx 8080:80

The command looks frozen. That is correct. It is holding a tunnel open. Visit http://localhost:8080 and you get the same page. Press Ctrl+C to stop it.

Scale up

kubectl scale deployment nginx --replicas=5
kubectl get pods -o wide
kubectl get endpoints nginx

Two new Pods. The old three were not restarted. Kubernetes only created what was missing.

The Service picked up the new Pods on its own. You did not touch service.yaml. It matches by label, so any new Pod with app=nginx joins as soon as it is ready. Go back to three:

kubectl scale deployment nginx --replicas=3

Now delete one on purpose

In your second terminal, start watching:

kubectl get pods -o wide -w

In the first terminal, copy a real Pod name from your output and delete it:

kubectl get pods
kubectl delete pod <paste-one-of-your-pod-names>

nginx-7c9f4d8b6d-k2xvp   1/1   Terminating         0   8m    k8s-lab-worker
nginx-7c9f4d8b6d-z9rtb   0/1   Pending             0   0s    <none>
nginx-7c9f4d8b6d-z9rtb   0/1   ContainerCreating   0   0s    k8s-lab-worker2
nginx-7c9f4d8b6d-z9rtb   1/1   Running             0   2s    k8s-lab-worker2

A new Pod appeared in about two seconds. It has a new name, a new IP, and it may be on a different machine. Press Ctrl+C to stop watching.

Now reload http://localhost:30000. The site never went down. The other two Pods served every request while this happened.

5.1 — Ship a new version

kubectl set image deployment/nginx nginx=nginx:stable-alpine
kubectl rollout status deployment/nginx

Reload http://localhost:30000 while it runs. The site stays up. New Pods start and are checked before old ones are removed.

In that command, deployment/nginx is the Deployment name and nginx= is the container name from your file. They are the same word here by chance.

There are two common ways to ship a new version:

• Imperative: change the live object directly with kubectl set image. This is fast and useful when you are experimenting or fixing something quickly.
• Declarative: edit the YAML file and then run kubectl apply -f deployment.yaml. This is the standard production workflow because the cluster is told the desired state from a file.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: burgxy/webapps:v4
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: "250m"
              memory: "164Mi"

kubectl apply -f deployment.yaml
kubectl rollout status deployment/nginx

This declarative approach is often preferred in real projects because the change is stored in Git, is easy to review, and is easy to reproduce.

kubectl get replicasets

NAME               DESIRED   CURRENT   READY   AGE
nginx-5d7b9c4f8a   3         3         3       40s
nginx-7c9f4d8b6d   0         0         0       14m

Two ReplicaSets now, with a new code in the name. The new one runs your Pods. The old one is empty but kept. That empty one is your undo button:

kubectl rollout undo deployment/nginx
kubectl rollout status deployment/nginx
kubectl get deployment nginx -o jsonpath='{.spec.template.spec.containers[0].image}'; echo

Back to nginx:stable in about two seconds. Nothing was rebuilt or downloaded again, because the old ReplicaSet was never deleted.

5.2 — Redeploy when nothing changed

This is the job you will do most often at work. Try applying the file you have not edited:

kubectl apply -f deployment.yaml

deployment.apps/nginx unchanged

unchanged is not a warning. apply compares your file with the cluster and only acts on differences. No difference means no action.

But sometimes you do want all Pods replaced. Maybe you rebuilt the image with the same tag. Maybe a setting changed. Note the Pod names first, so you can compare:

kubectl get pods -l app=nginx          # before
kubectl rollout restart deployment/nginx
kubectl rollout status deployment/nginx
kubectl get pods -l app=nginx          # after

NAME                     READY   STATUS    RESTARTS   AGE
nginx-7c9f4d8b6d-m8ztq   1/1     Running   0          14m
nginx-7c9f4d8b6d-p4wnc   1/1     Running   0          14m
nginx-7c9f4d8b6d-t8kqn   1/1     Running   0          14m

deployment.apps/nginx restarted
deployment "nginx" successfully rolled out

NAME                     READY   STATUS    RESTARTS   AGE
nginx-8a3e1c7d25-6rzv2   1/1     Running   0          21s
nginx-8a3e1c7d25-hq4nd   1/1     Running   0          17s
nginx-8a3e1c7d25-xp9ck   1/1     Running   0          13s

6.1 — Break it

kubectl set image deployment/nginx nginx=nginx:this-tag-does-not-exist

Wait about 20 seconds, then:

kubectl get pods
curl -s http://localhost:30000 | head -n 1

NAME                     READY   STATUS             RESTARTS   AGE
nginx-8a3e1c7d25-6rzv2   1/1     Running            0          6m
nginx-8a3e1c7d25-hq4nd   1/1     Running            0          6m
nginx-6b4d9f2c1e-t5qmx   0/1     ImagePullBackOff   0          22s

<!DOCTYPE html>

6.2 — Find out why

Two commands. Knowing which one to use is the real skill. Use your broken Pod name:

kubectl describe pod <your-broken-pod-name>

Scroll to Events at the bottom:

Normal   Scheduled  45s  default-scheduler  Successfully assigned default/nginx-6b4d9f2c1e-t5qmx to k8s-lab-worker
Normal   Pulling    44s  kubelet            Pulling image "nginx:this-tag-does-not-exist"
Warning  Failed     42s  kubelet            Failed to pull image: not found
Warning  Failed     15s  kubelet            Error: ImagePullBackOff

The answer is right there in plain English: the image tag does not exist. You can also see which part failed. The scheduler worked. The kubelet could not pull the image.

Now try the other command:

kubectl logs <your-broken-pod-name>

Error from server (BadRequest): container "nginx" is waiting to start:
trying and failing to pull image

6.3 — Fix it

kubectl rollout undo deployment/nginx
kubectl rollout status deployment/nginx
kubectl get pods -o wide
kubectl get endpoints nginx

You must finish with: 3/3, three Pods Running, three endpoints, and http://localhost:30000 still showing the nginx page.

What each status means

Commands worth keeping

If something goes wrong

kubectl delete deployment nginx --ignore-not-found
kubectl delete service nginx --ignore-not-found
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl wait --for=condition=Available deployment/nginx --timeout=120s

Check yourself

Try to answer out loud before opening each one.

Option A — keep the cluster, remove the app

kubectl delete -f service.yaml
kubectl delete -f deployment.yaml
kubectl get all

Only the built-in kubernetes Service should remain. Notice you never deleted a Pod or a ReplicaSet. Deleting the Deployment removed everything it owned. That is the chain from step 2, working backwards.

Option B — delete the whole cluster

kind delete cluster --name k8s-lab
kind get clusters      # prints nothing

This deletes all three containers. Everything inside is gone. Your YAML files on disk are safe, so you can rebuild the whole lab in about four minutes.