Zum Inhalt springen
Trainingslager IT-Trainingslager

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 produktion und ruft kubectl auf. GitHub merkt sich jedes Deployment samt Ergebnis.
  • kubectl rollout status wartet, 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 servicelb

Erwartet (gekürzt):

[INFO]  Using v1.37.1+k3s1 as release
...
[INFO]  systemd: Starting k3s
  • get.k3s.io ist das offizielle Installationsskript. Es lädt k3s, legt den Dienst an und verlinkt kubectl.
  • --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 nodes

Erwartet:

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.yaml

Erwartet:

          image: ghcr.io/<du>/notes-api:0.5.0
  • readinessProbe: Ein Pod bekommt erst Verkehr, wenn /healthz antwortet. Darauf wartet später rollout status.
  • {app: notes-api} ist YAML in Kurzform – dasselbe wie eine eingerückte Zeile app: 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/version

Erwartet:

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 status liefe 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 -q

Fortschritt 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-actions

Erwartet (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 -q
  • runs-on: [self-hosted, lab]: Nur dein Runner kommt an den Cluster. Über KUBECONFIG aus .env nutzt er die Datei ~/.kube/config des Benutzers ubuntu.
  • concurrency mit cancel-in-progress: false: Zwei Deployments laufen nacheinander, keines bricht das andere ab – halbe Rollouts will niemand.
  • environment.url steht 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.1

Mit 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 wide

Erwartet:

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.9

Freigeben 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/version

Erwartet (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.9 gibt es nicht; der neue Pod bleibt in ImagePullBackOff, und rollout status gibt nach 60 Sekunden auf.
  • Die alten Pods liefen die ganze Zeit weiter – ein Rolling Update ersetzt sie erst, wenn neue bereit sind. rollout undo rä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 pods

Erwartet:

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/version

Erwartet:

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 wie v0.6.0-rc.2 gehen nicht nach Produktion.
  • Dieser Job braucht keinen Checkout – nur gh und 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/version

Erwartet:

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 notes Deployments ändern darf. Bei Cloud-Clustern holt er sich den Zugang per OIDC (Tag 10).
  • Freigabe vor Produktion: Viele Teams deployen nach staging ohne Freigabe und nach produktion mit – 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).