Tag 11: Deployment auf Kubernetes
Ziel: k3s auf der Labor-VM, notes-api als Deployment, und ein Workflow, der eine gewählte Version nach Freigabe ausrollt, den Rollout abwartet und im Fehlerfall zurückrollt. · Dauer: ca. 90 min · Voraussetzung: Tag 10
Briefing
- Der Cluster läuft auf deiner VM und ist von außen nicht erreichbar. Die Runner von GitHub kommen nicht heran – dein eigener Runner von Tag 5 schon.
- Der Workflow nimmt die Version als Eingabe, läuft im Environment
produktionund ruftkubectlauf. GitHub merkt sich jedes Deployment samt Ergebnis. kubectl rollout statuswartet, bis die neuen Pods bereit sind, und scheitert nach einer Frist – dann rollt der nächste Step zurück.
gh workflow run deploy.yml -f version=0.5.1
─► Freigabe ─► Runner gha-vm ─► kubectl set image ─► rollout status
└── Fehler ─► rollout undo
k3s auf der VM: Namespace notes ─ Deployment notes-api ─ Service :30081
Drill 1: k3s
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.37.1+k3s1 \
sh -s - --disable traefik --disable servicelbErwartet (gekürzt):
[INFO] Using v1.37.1+k3s1 as release
...
[INFO] systemd: Starting k3s
get.k3s.ioist das offizielle Installationsskript. Es lädt k3s, legt den Dienst an und verlinktkubectl.--disable traefik --disable servicelb: kein Ingress und kein Load-Balancer, die sich die Ports 80 und 443 der VM nehmen. Für das Lab genügt ein NodePort.
Die Zugangsdaten liegen unter /etc/rancher/k3s/k3s.yaml
und gehören root. Eine Kopie für dich:
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$(id -u):$(id -g)" ~/.kube/config
chmod 600 ~/.kube/config
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc
export KUBECONFIG=~/.kube/config
kubectl get nodesErwartet:
NAME STATUS ROLES AGE VERSION
gha Ready control-plane 6m7s v1.37.1+k3s1
KUBECONFIG ist hier Pflicht: Das kubectl
von k3s liest sonst immer /etc/rancher/k3s/k3s.yaml und
scheitert mit permission denied. Die Zeile in
~/.bashrc setzt die Variable bei jeder neuen Anmeldung.
Fortschritt speichern? Kostenlos registrieren
Drill 2: notes-api im Cluster
Die Manifeste gehören ins Repository, neben den Code:
cd ~/gha-lab/notes-actions
mkdir -p k8s
cat > k8s/notes-api.yaml <<'EOF'
apiVersion: v1
kind: Namespace
metadata:
name: notes
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: notes-api
namespace: notes
spec:
replicas: 2
selector:
matchLabels: {app: notes-api}
template:
metadata:
labels: {app: notes-api}
spec:
containers:
- name: notes-api
image: ghcr.io/OWNER/notes-api:0.5.0
ports: [{containerPort: 8080}]
env:
- name: NOTES_API_KEY
valueFrom:
secretKeyRef: {name: notes-api, key: api-key}
readinessProbe:
httpGet: {path: /healthz, port: 8080}
periodSeconds: 2
---
apiVersion: v1
kind: Service
metadata:
name: notes-api
namespace: notes
spec:
type: NodePort
selector: {app: notes-api}
ports: [{port: 8080, nodePort: 30081}]
EOF
sed -i "s/OWNER/$(gh api user --jq .login)/" k8s/notes-api.yaml
grep image: k8s/notes-api.yamlErwartet:
image: ghcr.io/<du>/notes-api:0.5.0
readinessProbe: Ein Pod bekommt erst Verkehr, wenn/healthzantwortet. Darauf wartet späterrollout status.{app: notes-api}ist YAML in Kurzform – dasselbe wie eine eingerückte Zeileapp: notes-api.
Das Secret entsteht von Hand, einmalig – es gehört nicht ins Repository. Erst der Namespace und das Secret, dann der Rest:
kubectl create namespace notes
kubectl -n notes create secret generic notes-api --from-literal=api-key=lab-api-key-123
kubectl apply -f k8s/notes-api.yaml
kubectl -n notes rollout status deployment/notes-api --timeout=180s
curl -s localhost:30081/versionErwartet:
namespace/notes created
secret/notes-api created
namespace/notes unchanged
deployment.apps/notes-api created
service/notes-api created
deployment "notes-api" successfully rolled out
0.5.0
- Andersherum stünden die Pods erst ohne Secret da
(
CreateContainerConfigError) und kämen nach einer Wartepause wieder –rollout statusliefe dann leicht in die Frist. - Das Image ist öffentlich (Tag 6); ein Pull-Secret braucht k3s nicht.
git add k8s
git commit -qm "k8s: Manifeste für notes-api"
git push -qFortschritt speichern? Kostenlos registrieren
Drill 3: Der Deploy-Workflow
Der Runner läuft als Dienst und liest ~/.bashrc nicht.
Umgebungsvariablen für alle seine Jobs stehen in der Datei
.env im Runner-Ordner:
echo "KUBECONFIG=$HOME/.kube/config" >> ~/gha-lab/runner/.env
cd ~/gha-lab/runner
sudo ./svc.sh stop
sudo ./svc.sh start
cd ~/gha-lab/notes-actionsErwartet (gekürzt, am Ende):
Active: active (running) since ...
Der Runner liest .env nur beim Start – darum der
Neustart.
deploy.yml bekommt eine Eingabe und echte Arbeit:
cat > .github/workflows/deploy.yml <<'EOF'
name: deploy
on:
workflow_dispatch:
inputs:
version:
description: Image-Tag, z. B. 0.5.1
required: true
permissions:
contents: read
concurrency:
group: deploy-produktion
cancel-in-progress: false
jobs:
deploy:
runs-on: [self-hosted, lab]
environment:
name: produktion
url: http://localhost:30081/version
env:
IMAGE: ghcr.io/${{ github.repository_owner }}/notes-api:${{ inputs.version }}
steps:
- name: Version setzen
run: kubectl -n notes set image deployment/notes-api notes-api="$IMAGE"
- name: Rollout abwarten
run: kubectl -n notes rollout status deployment/notes-api --timeout=60s
- name: Zurückrollen
if: failure()
run: kubectl -n notes rollout undo deployment/notes-api
EOF
git commit -qam "deploy: Version auf k3s ausrollen"
git push -qruns-on: [self-hosted, lab]: Nur dein Runner kommt an den Cluster. ÜberKUBECONFIGaus.envnutzt er die Datei~/.kube/configdes Benutzersubuntu.concurrencymitcancel-in-progress: false: Zwei Deployments laufen nacheinander, keines bricht das andere ab – halbe Rollouts will niemand.environment.urlsteht später neben dem Deployment in GitHub.- Kein Checkout:
set imageändert nur das Image des bestehenden Deployments. Die Manifeste selbst wendest du bei Änderungen von Hand an. In Produktion schreibt man die Version lieber in die Datei und lässt den Cluster sie holen (GitOps) – das Schwesterbuch zu Argo CD zeigt das.
gh workflow run deploy.yml -f version=0.5.1Mit der ID aus
gh run list --workflow deploy.yml --limit 1 freigeben – wie
an Tag 10, mit der ID deines Environments:
gh api -X POST repos/{owner}/{repo}/actions/runs/<ID>/pending_deployments \
-F 'environment_ids[]=26123220715' -f state=approved -f comment='0.5.1' \
--jq '.[].environment'Sobald der Lauf fertig ist:
curl -s localhost:30081/version
kubectl -n notes get deployment notes-api -o wideErwartet:
0.5.1
NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES ...
notes-api 2/2 2 2 2m59s notes-api ghcr.io/<du>/...
-o wide zeigt zusätzlich Container und Images – ganz
rechts steht ghcr.io/<du>/notes-api:0.5.1.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ein Rollout, der scheitert
Eine Version, die es nicht gibt:
gh workflow run deploy.yml -f version=9.9.9Freigeben wie eben. Nach gut einer Minute:
gh run view <ID> -v | grep -E 'Rollout|Zurück'Erwartet:
X Rollout abwarten
✓ Zurückrollen
gh run view <ID> --log | grep -E 'Z (error|deployment.apps)'
curl -s localhost:30081/versionErwartet (gekürzt):
deploy Version setzen ... deployment.apps/notes-api image updated
deploy Rollout abwarten ... error: timed out waiting for the condition
deploy Zurückrollen ... deployment.apps/notes-api rolled back
0.5.1
- Das Image
9.9.9gibt es nicht; der neue Pod bleibt inImagePullBackOff, undrollout statusgibt nach 60 Sekunden auf. - Die alten Pods liefen die ganze Zeit weiter – ein Rolling Update
ersetzt sie erst, wenn neue bereit sind.
rollout undoräumt den kaputten Versuch weg.
GitHub hat beide Deployments protokolliert:
Erst die Deployments:
gh api repos/{owner}/{repo}/deployments --jq '.[0:2][] | "\(.id) \(.environment)"'Erwartet (IDs weichen ab):
7517792135 produktion
7517780729 produktion
Dann den Status eines davon:
gh api repos/{owner}/{repo}/deployments/7517792135/statuses --jq '.[0].state'Erwartet:
failure
Im Browser zeigt Deployments dieselbe Liste mit der
url aus dem Workflow.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
kubectl -n notes get podsErwartet:
NAME READY STATUS RESTARTS AGE
notes-api-55dd946cfc-h67wt 1/1 Running 0 105s
notes-api-55dd946cfc-xm2s9 1/1 Running 0 109s
curl -s localhost:30081/versionErwartet:
0.5.1
gh run list --workflow deploy.yml --limit 2 --json conclusion --jq '.[].conclusion'Erwartet:
failure
success
Challenge
Nach jedem Release soll das Deployment von selbst starten (die
Freigabe bleibt). Ergänze release.yml um einen Job, der
deploy.yml mit der neuen Version auslöst, und teste es mit
v0.5.2.
Hinweis: Ein Release, das ein Workflow mit dem
GITHUB_TOKEN anlegt, löst keine anderen
Workflows aus – Schutz gegen Endlosschleifen. Die Ausnahme:
workflow_dispatch. gh workflow run braucht
actions: write.
Lösung
cat >> .github/workflows/release.yml <<'EOF'
deploy:
needs: release
if: ${{ !contains(github.ref_name, '-') }}
runs-on: ubuntu-24.04
permissions:
actions: write
steps:
- name: Deployment anstoßen
env:
GH_TOKEN: ${{ github.token }}
run: >-
gh workflow run deploy.yml --repo "$GITHUB_REPOSITORY"
-f version="${GITHUB_REF_NAME#v}"
EOF
git commit -qam "release: Deployment anstoßen"
git push -q
git tag v0.5.2
git push -q origin v0.5.2!contains(…, '-'): Vorabversionen wiev0.6.0-rc.2gehen nicht nach Produktion.- Dieser Job braucht keinen Checkout – nur
ghund das Token.
Nach etwa zwei Minuten (Release und Image müssen fertig sein):
gh run list --workflow deploy.yml --limit 1 --json event,status --jq '.[0]'Erwartet:
{"event":"workflow_dispatch","status":"waiting"}
Freigeben wie in Drill 3. Danach:
curl -s localhost:30081/versionErwartet:
0.5.2
Achtung, Wettlauf: deploy wartet nur auf
release, nicht auf image.yml – beide laufen
parallel. Hier rettet dich die Freigabe, die du erst gibst, wenn das
Image da ist. Ohne Freigabe gehört ein Warten auf das Image in den
Deploy-Job.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Push oder Pull: Hier schiebt CI in den Cluster (Push). Mit GitOps (Argo CD, Flux) schreibt CI nur die neue Version ins Git, und der Cluster holt sie sich – kein Runner braucht Zugang zum Cluster.
- Zugang zum Cluster: Statt einer kubeconfig mit
Admin-Rechten bekommt der Runner einen ServiceAccount, der nur im
Namespace
notesDeployments ändern darf. Bei Cloud-Clustern holt er sich den Zugang per OIDC (Tag 10). - Freigabe vor Produktion: Viele Teams deployen nach
stagingohne Freigabe und nachproduktionmit – zwei Environments, derselbe Workflow. - Signatur prüfen: Ein Admission-Controller kann im Cluster verlangen, dass nur Images mit Signatur und Provenance aus deinem Repository starten (Tag 8).