Tag 1: Der erste Pod
Ziel: den Namespace
notesanlegen, 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,metadataund meistspec(das Soll). Denstatus(das Ist) schreibt das Cluster. kubectl apply -fschickt eine Datei an den API-Server – das ist das Gegenstück zudocker compose up, nur ohne Container-Start auf deinem Rechner.- Ein Namespace trennt Objekte gleichen Namens. Ab
heute ist
notesdein 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 podsErwartet (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.yamlErwartet:
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}'; echoErwartet (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 nichtlatestist, nimmt der Kubelet das perkind loadgeladene Image und fragt keine Registry.restartPolicy: Always: Stirbt der Prozess, startet der Kubelet den Container im selben Pod neu.uid: 65532(unterstatus.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/apiErwartet (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 -- shErwartet (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 %1Erwartet (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 podsErwartet:
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 %1Erwartet (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 namespaceErwartet: notes ist der Standard-Namespace im
Kontext.
namespace: notes
kubectl get pods --show-labelsErwartet: 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 apiErwartet: 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-testErwartet (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 execundport-forwardsind mächtige Rechte. Im Betrieb sind sie per RBAC auf wenige Personen beschränkt und werden im Audit-Log protokolliert.ImagePullBackOffin Produktion heißt meist: Tippfehler im Tag, fehlendes Pull-Secret für die private Registry oder Rate-Limit von Docker Hub.