Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Der erste Pod

Ziel: den Namespace notes anlegen, notes-api als einzelnen Pod starten, ihn von außen und innen untersuchen – und sehen, warum ein Pod allein nicht reicht. · Dauer: ca. 60 min · Voraussetzung: Tag 0

Briefing

  • Ein Pod ist die kleinste Einheit in Kubernetes: ein oder mehrere Container mit gemeinsamer IP. Heute genau ein Container, notes-api:0.1.0.
  • Jedes Objekt hat apiVersion, kind, metadata und meist spec (das Soll). Den status (das Ist) schreibt das Cluster.
  • kubectl apply -f schickt eine Datei an den API-Server – das ist das Gegenstück zu docker compose up, nur ohne Container-Start auf deinem Rechner.
  • Ein Namespace trennt Objekte gleichen Namens. Ab heute ist notes dein Standard.
 k8s/api-pod.yaml ──apply──► API-Server ──► etcd (Soll gespeichert)
                                 │
                     Scheduler wählt lab-worker2
                                 │
                     Kubelet ──► containerd ──► Container notes-api:0.1.0

Drill 1: Namespace und Standard-Kontext

source ~/k8s-lab/setup/env.sh
mkdir -p ~/k8s-lab/tag01/k8s && cd ~/k8s-lab/tag01
cp -R "$LAB/code/notes/." .
cat > k8s/namespace.yaml <<'EOF'
# k8s/namespace.yaml – Stand Ende Tag 1
apiVersion: v1
kind: Namespace
metadata:
  name: notes
EOF
kubectl apply --dry-run=server -f k8s/namespace.yaml
kubectl apply -f k8s/namespace.yaml
kubectl config set-context --current --namespace notes
kubectl config get-contexts
kubectl get pods

Erwartet (gekürzt):

namespace/notes created (server dry run)
namespace/notes created
Context "kind-lab" modified.
CURRENT   NAME       CLUSTER    AUTHINFO   NAMESPACE
*         kind-lab   kind-lab   kind-lab   notes
No resources found in notes namespace.

--dry-run=server lässt den API-Server die Datei vollständig prüfen, ohne etwas zu speichern. Das machst du vor jedem neuen Manifest. Der Standard-Namespace steht im Kontext; ohne ihn bräuchte jeder Befehl -n notes.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das Pod-Manifest

cat > k8s/api-pod.yaml <<'EOF'
# k8s/api-pod.yaml – Stand Ende Tag 1
apiVersion: v1
kind: Pod
metadata:
  name: api
  labels:
    app.kubernetes.io/name: api
    app.kubernetes.io/part-of: notes
spec:
  containers:
    - name: api
      image: notes-api:0.1.0
      env:
        - name: NOTES_API_KEY
          value: lab-api-key-123
      ports:
        - containerPort: 8080
EOF
kubectl apply --dry-run=server -f k8s/api-pod.yaml

Erwartet:

pod/api created (server dry run)
Feld Bedeutung Entspricht in Compose
apiVersion, kind Welcher Objekttyp in welcher API-Version –
metadata Name, Namespace, Labels Dienstname
spec.containers Image, Umgebung, Ports image, environment
containerPort Dokumentiert den Port, veröffentlicht nichts expose

Die Labels nutzt du ab Tag 2. Der API-Key als Klartext ist eine Zwischenlösung, an Tag 4 wird daraus ein Secret.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Anwenden und ansehen

kubectl apply -f k8s/api-pod.yaml
kubectl get pods
sleep 4
kubectl get pods -o wide
kubectl get pod api -o jsonpath='{.status.phase} {.status.podIP} {.spec.nodeName}'; echo

Erwartet (gekürzt, Namen, IPs und Zeiten weichen bei dir ab):

pod/api created
NAME   READY   STATUS              RESTARTS   AGE
api    0/1     ContainerCreating   0          0s
NAME   READY   STATUS    RESTARTS   AGE   IP           NODE          …
api    1/1     Running   0          4s    10.244.2.2   lab-worker2   …
Running 10.244.2.2 lab-worker2

Der Scheduler hat einen Worker gewählt, der Pod hat eine eigene IP aus dem Pod-Netz. Was das Cluster aus deinen 17 Zeilen gemacht hat, zeigt -o yaml:

kubectl get pod api -o yaml | grep -E \
  'imagePullPolicy|restartPolicy|nodeName|dnsPolicy|phase|qosClass|^ +uid: [0-9]+$'

Erwartet:

    imagePullPolicy: IfNotPresent
  dnsPolicy: ClusterFirst
  nodeName: lab-worker2
  restartPolicy: Always
        uid: 65532
  phase: Running
  qosClass: BestEffort

Ohne Filter sind es über 100 Zeilen: Kubernetes füllt jedes Feld, das du weglässt, mit einem Standardwert.

  • imagePullPolicy: IfNotPresent: Weil der Tag nicht latest ist, nimmt der Kubelet das per kind load geladene Image und fragt keine Registry.
  • restartPolicy: Always: Stirbt der Prozess, startet der Kubelet den Container im selben Pod neu.
  • uid: 65532 (unter status.containerStatuses): Der Container läuft als der Nutzer aus dem Dockerfile.

Fortschritt speichern? Kostenlos registrieren

Drill 4: describe und Events

kubectl describe pod api | sed -n '/^Events:/,$p'
kubectl events --for pod/api

Erwartet (gekürzt):

Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  9s    default-scheduler  Successfully assigned notes/api to lab-w…
  Normal  Pulled     9s    kubelet            spec.containers{api}: Container image "…
  Normal  Created    8s    kubelet            spec.containers{api}: Container created
  Normal  Started    8s    kubelet            spec.containers{api}: Container started
LAST SEEN   TYPE     REASON      OBJECT    MESSAGE
10s         Normal   Scheduled   Pod/api   Successfully assigned notes/api to lab-work…
10s         Normal   Pulled      Pod/api   Container image "notes-api:0.1.0" already pr…
9s          Normal   Created     Pod/api   Container created
9s          Normal   Started     Pod/api   Container started

Events sind das Protokoll des Clusters: wer was wann mit dem Objekt gemacht hat. Klemmt ein Pod in Pending oder ContainerCreating, steht der Grund fast immer hier. Events verfallen nach einer Stunde.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Logs und exec

kubectl logs api
kubectl exec api -- sh

Erwartet (gekürzt):

time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=memory
time=… level=INFO msg=listening addr=:8080 version=0.1.0 pid=1
error: Internal error occurred: … OCI runtime exec failed: exec failed: unable to start
container process: exec: "sh": executable file not found in $PATH

kubectl logs liest stdout und stderr des Containers, wie docker logs. Eine Shell gibt es nicht: notes-api ist ein scratch-Image mit genau einer Datei. Programme, die im Image liegen, startet exec trotzdem:

kubectl exec api -- /notes-api healthcheck; echo "Exit: $?"

Erwartet:

Exit: 0

Wie du trotzdem in einen solchen Container schaust, ohne das Image aufzublähen, zeigt kubectl debug an Tag 11.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Port-Forward

Der Pod hat eine IP im Cluster-Netz, vom Mac aus erreichst du sie nicht. kubectl port-forward tunnelt einen lokalen Port über den API-Server in den Pod:

kubectl port-forward pod/api 8080:8080 &
sleep 2
curl -s localhost:8080/version
curl -s localhost:8080/notes
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -H 'Content-Type: application/json' -d '{"text":"Tag 1 lebt im Pod"}'
curl -s localhost:8080/notes
curl -s -X POST localhost:8080/notes -d '{"text":"ohne Key"}'
kill %1

Erwartet (gekürzt, IDs weichen ab):

Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
Handling connection for 8080
0.1.0
[]
{"id":"d847b492-…","text":"Tag 1 lebt im Pod"}
[{"id":"d847b492-…","text":"Tag 1 lebt im Pod"}]
{"error":"invalid api key"}

Port-Forward ist ein Werkzeug für dich, kein Weg für Nutzer: Es endet mit dem Prozess und hängt an genau einem Pod. Den richtigen Weg baust du an Tag 3.

Fortschritt speichern? Kostenlos registrieren

Drill 7: kubectl explain

Welche Felder es gibt und was sie bedeuten, weiß das Cluster selbst:

kubectl explain pod.spec.containers.imagePullPolicy | head -12
kubectl api-resources | grep -E '^NAME|^pods |^namespaces |^deployments |^services '

Erwartet (gekürzt):

KIND:       Pod
VERSION:    v1

FIELD: imagePullPolicy <string>
ENUM:
    Always
    IfNotPresent
    Never

DESCRIPTION:
    Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if
    :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More
NAME          SHORTNAMES   APIVERSION   NAMESPACED   KIND
namespaces    ns           v1           false        Namespace
pods          po           v1           true         Pod
services      svc          v1           true         Service
deployments   deploy       apps/v1      true         Deployment

explain arbeitet mit Punkten durch die Struktur (pod.spec.containers.env), --recursive zeigt den ganzen Baum. api-resources liefert die Kurznamen: kubectl get po ist dasselbe wie kubectl get pods.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Pod weg, Notiz weg

kubectl delete pod api
kubectl get pods

Erwartet:

pod "api" deleted from notes namespace
No resources found in notes namespace.

restartPolicy: Always hilft hier nicht: Sie startet Container in einem Pod neu. Ist der Pod selbst weg – gelöscht, oder sein Node ausgefallen –, ersetzt ihn niemand. Also wieder anlegen:

kubectl apply -f k8s/api-pod.yaml
kubectl wait --for=condition=Ready pod/api --timeout=60s
kubectl port-forward pod/api 8080:8080 &
sleep 2
curl -s localhost:8080/notes
kill %1

Erwartet (gekürzt):

pod/api created
pod/api condition met
Forwarding from 127.0.0.1:8080 -> 8080
…
[]

Der neue Pod läuft womöglich auf einem anderen Node, hat eine neue IP – und deine Notiz ist weg, weil notes-api ohne Datenbank im Speicher arbeitet. Das erste Problem löst morgen ein Deployment, das zweite Postgres an Tag 7.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl config view --minify | grep namespace

Erwartet: notes ist der Standard-Namespace im Kontext.

    namespace: notes
kubectl get pods --show-labels

Erwartet: genau ein Pod api, Running, mit den beiden Labels.

NAME   READY   STATUS    RESTARTS   AGE   LABELS
api    1/1     Running   0          2s    app.kubernetes.io/name=api,app.kubernetes.io/…
kubectl logs api

Erwartet: Version 0.1.0, Speicher memory.

time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=memory
time=… level=INFO msg=listening addr=:8080 version=0.1.0 pid=1

Challenge

Starte einen zweiten Pod api-test mit dem Image notes-api:9.9.9 (gibt es nicht), finde mit Bordmitteln heraus, warum er nicht startet, und repariere ihn, ohne ihn zu löschen. Räum danach auf.

Hinweis: kubectl run legt einen Pod ohne Datei an; das Image eines Containers ist eines der wenigen Pod-Felder, die sich nachträglich ändern lassen (kubectl set image).

Lösung

kubectl run api-test --image=notes-api:9.9.9 --env NOTES_API_KEY=lab-api-key-123
sleep 15
kubectl get pod api-test
kubectl events --for pod/api-test
kubectl set image pod/api-test api-test=notes-api:0.1.0
kubectl wait --for=condition=Ready pod/api-test --timeout=90s
kubectl get pods
kubectl delete pod api-test

Erwartet (gekürzt):

pod/api-test created
NAME       READY   STATUS             RESTARTS   AGE
api-test   0/1     ImagePullBackOff   0          15s
LAST SEEN          TYPE      REASON      OBJECT         MESSAGE
16s                Normal    Scheduled   Pod/api-test   Successfully assigned notes/…
14s                Normal    BackOff     Pod/api-test   Back-off pulling image "notes-…
2s (x2 over 15s)   Normal    Pulling     Pod/api-test   Pulling image "notes-api:9.9.9"
1s (x2 over 14s)   Warning   Failed      Pod/api-test   Failed to pull image "notes-api…
…: pull access denied, repository does not exist or may require authorization: …
1s (x2 over 14s)   Warning   Failed      Pod/api-test   Error: ErrImagePull
pod/api-test image updated
pod/api-test condition met
NAME       READY   STATUS    RESTARTS   AGE
api        1/1     Running   0          19s
api-test   1/1     Running   0          17s
pod "api-test" deleted from notes namespace

Den Tag 9.9.9 gibt es in keinem Node, also versucht der Kubelet docker.io/library/notes-api zu ziehen und scheitert. Nach jedem Fehlschlag wartet er länger (ImagePullBackOff). kubectl run nennt den Container wie den Pod – darum api-test=… bei set image.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Nackte Pods gibt es in Produktion praktisch nicht. Alles läuft über Controller wie Deployment, StatefulSet oder Job, die Pods ersetzen (ab Tag 2).
  • Ein API-Key als value: landet im Klartext in Git und in etcd. Dafür gibt es Secrets (Tag 4) und externe Secret-Speicher („OpenBao-Secrets zum Anfassen”).
  • kubectl exec und port-forward sind mächtige Rechte. Im Betrieb sind sie per RBAC auf wenige Personen beschränkt und werden im Audit-Log protokolliert.
  • ImagePullBackOff in Produktion heißt meist: Tippfehler im Tag, fehlendes Pull-Secret für die private Registry oder Rate-Limit von Docker Hub.