13 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • Einen GitHub Actions-Workflow erstellen, der TaskBoard testet, Git-SHA-Images in die Private Container Registry hochlädt und sie in Managed Kubernetes bereitstellt
  • Die entsprechende Pipeline in GitLab CI mit Build- und Deploy-Stufen implementieren
  • Terraform in CI automatisieren: Plan bei jedem Pull Request mit dem Plan als Kommentar, Apply bei Merge auf `main`
  • Pipeline-Secrets für das Cloud API-Token, Object Storage-Schlüssel, Registry-Token und ein namespace-spezifisches kubeconfig konfigurieren
  • Ein fehlgeschlagenes Deployment mit `kubectl rollout undo` zurückrollen, den Terraform-Zustand wiederherstellen und die Infrastruktur von TaskBoard in wiederverwendbare Terraform-Module extrahieren

Einheit 3.3: CI/CD-Pipelines für IONOS CLOUD

Einführung

Bisher haben Sie jeden Schritt manuell ausgeführt: terraform apply von Ihrem Laptop, docker push aus Ihrer Shell, kubectl apply mit einer Admin-kubeconfig. Das funktioniert für eine einzelne Entwicklungsperson. Für ein Team muss jede Änderung an main denselben geprüften und wiederholbaren Weg durchlaufen, und kein Laptop sollte Produktionszugangsdaten enthalten.

In dieser Einheit automatisieren Sie beide Teile von TaskBoard. Die Anwendungspipeline baut, testet, pusht und deployt. Die Infrastrukturpipeline plant bei Pull Requests und wendet Änderungen bei Merge an. Sie speichern jedes Zugangsdatum im Secret Store des CI-Systems, wählen eine Deployment-Strategie, üben Rollbacks und wandeln das Terraform von TaskBoard in Module um, die Ihr Team wiederverwenden kann. Im Code Lab erstellen Sie eine GitHub Actions Pipeline, die TaskBoard bei jedem Push auf main deployt.

1. Pipeline-Design

TaskBoard verwendet zwei Pipelines mit unterschiedlichen Auslösern und Zugangsdaten:

Pipeline Auslöser Schritte Zugangsdaten
Anwendung Push auf main Test, Build, Image pushen, Deploy Registry-Push-Token, Deployer-kubeconfig
Infrastruktur Pull Request / Merge terraform plan, terraform apply IONOS_TOKEN, Object Storage-Schlüssel für den State

Halten Sie sie getrennt. Die Application-Pipeline benötigt niemals das Cloud API Token, sodass ein kompromittierter Build-Schritt keine Ressourcen erstellen oder löschen kann. Die Infrastructure-Pipeline benötigt niemals die kubeconfig.

1.1 Inventar der Secrets

IONOS_TOKEN            Cloud API bearer token (infrastructure pipeline only)
AWS_ACCESS_KEY_ID      Object Storage Access Key for the Terraform state bucket
AWS_SECRET_ACCESS_KEY  Object Storage Secret Key for the Terraform state bucket
CR_HOST                Registry hostname (Unit 3.1)
CR_USERNAME            Push token username
CR_PASSWORD            Push token password
KUBECONFIG_DEPLOYER    Kubeconfig of the taskboard-deployer service account (Unit 3.2)

Erstellen Sie IONOS_TOKEN für einen dedizierten CI-Benutzer, der nur über die Berechtigungen verfügt, die die Infrastruktur benötigt, und setzen Sie ein explizites ttl, wie in Einheit 1.1. Das Registry-Push-Token aus Einheit 3.1 enthält pull und push. Object Storage authentifiziert sich mit einem Access Key und einem Secret Key, nicht mit dem Bearer Token, daher benötigt das State Backend ein eigenes Paar.

1.2 Ein Kubeconfig für die Pipeline

Das Kubeconfig von der API gewährt vollen Clusterzugriff. Für CI erstellen Sie eines für das taskboard-deployer-Servicekonto aus Einheit 3.2:

kubectl -n taskboard apply -f - <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: taskboard-deployer-token
  annotations:
    kubernetes.io/service-account.name: taskboard-deployer
type: kubernetes.io/service-account-token
EOF

SA_TOKEN="$(kubectl -n taskboard get secret taskboard-deployer-token -o jsonpath='{.data.token}' | base64 -d)"
SERVER="$(kubectl config view --raw -o jsonpath='{.clusters[0].cluster.server}')"
CA="$(kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')"

kubectl config --kubeconfig=deployer.yaml set-cluster taskboard --server="$SERVER"
kubectl config --kubeconfig=deployer.yaml set clusters.taskboard.certificate-authority-data "$CA"
kubectl config --kubeconfig=deployer.yaml set-credentials deployer --token="$SA_TOKEN"
kubectl config --kubeconfig=deployer.yaml set-context taskboard --cluster=taskboard --user=deployer --namespace=taskboard
kubectl config --kubeconfig=deployer.yaml use-context taskboard

Speichern Sie deployer.yaml base64-kodiert als KUBECONFIG_DEPLOYER und löschen Sie die lokale Datei. Wenn Sie api_subnet_allow_list auf dem Cluster festlegen, muss die Ausgangsadresse des Runners darin enthalten sein, andernfalls kann kubectl den API-Server nicht erreichen.

2. GitHub Actions: Die Anwendungspipeline

# .github/workflows/deploy.yml
name: deploy
on:
  push:
    branches: [main]

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Test
        run: |
          pip install -r api/requirements.txt -r api/requirements-dev.txt
          pytest api/tests

      - name: Log in to the registry
        env:
          CR_HOST: ${{ secrets.CR_HOST }}
          CR_USERNAME: ${{ secrets.CR_USERNAME }}
          CR_PASSWORD: ${{ secrets.CR_PASSWORD }}
        run: echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin

      - name: Build and push
        env:
          CR_HOST: ${{ secrets.CR_HOST }}
        run: |
          SHA="${GITHUB_SHA::12}"
          for svc in api web; do
            docker build -t "$CR_HOST/taskboard/$svc:$SHA" "$svc/"
            docker push "$CR_HOST/taskboard/$svc:$SHA"
          done

      - name: Deploy to MKS
        env:
          CR_HOST: ${{ secrets.CR_HOST }}
          KUBECONFIG_DEPLOYER: ${{ secrets.KUBECONFIG_DEPLOYER }}
        run: |
          echo "$KUBECONFIG_DEPLOYER" | base64 -d > "$RUNNER_TEMP/kubeconfig"
          export KUBECONFIG="$RUNNER_TEMP/kubeconfig"
          SHA="${GITHUB_SHA::12}"
          kubectl set image deploy/taskboard-api api="$CR_HOST/taskboard/api:$SHA"
          kubectl set image deploy/taskboard-web web="$CR_HOST/taskboard/web:$SHA"
          kubectl rollout status deploy/taskboard-api --timeout=5m
          kubectl rollout status deploy/taskboard-web --timeout=5m

Die Gruppe concurrency lässt nur eine Bereitstellung gleichzeitig ausführen, und rollout status meldet den Job als fehlgeschlagen, wenn die neuen Pods nicht bereit werden. kubectl set image ändert nur das Image; die Manifeste selbst verbleiben in Git und werden angewendet, wenn sie sich ändern. Das sequenzielle Pushen beider Images hält einen einzelnen Runner deutlich innerhalb der pro Client geltenden Grenzen des Registry, nämlich 100 gleichzeitige Verbindungen und 60 Anfragen pro Sekunde.

3. GitLab CI: Die entsprechende Pipeline

# .gitlab-ci.yml
stages: [test, build, deploy]

variables:
  SHA: $CI_COMMIT_SHORT_SHA

test:
  stage: test
  image: python:3.12-slim
  script:
    - pip install -r api/requirements.txt -r api/requirements-dev.txt
    - pytest api/tests

build:
  stage: build
  image: docker:27
  services: [docker:27-dind]
  before_script:
    - echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin
  script:
    - for svc in api web; do docker build -t "$CR_HOST/taskboard/$svc:$SHA" "$svc/"; docker push "$CR_HOST/taskboard/$svc:$SHA"; done
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:
  stage: deploy
  image: alpine:3.20
  resource_group: production
  before_script:
    - apk add --no-cache curl
    - curl -sLo /usr/local/bin/kubectl "https://dl.k8s.io/release/v1.34.0/bin/linux/amd64/kubectl" && chmod +x /usr/local/bin/kubectl
    - echo "$KUBECONFIG_DEPLOYER" | base64 -d > /tmp/kubeconfig
  script:
    - export KUBECONFIG=/tmp/kubeconfig
    - kubectl set image deploy/taskboard-api api="$CR_HOST/taskboard/api:$SHA"
    - kubectl rollout status deploy/taskboard-api --timeout=5m
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

resource_group ist GitLabs Äquivalent zur GitHub-concurrency-Gruppe. Definieren Sie CR_PASSWORD und KUBECONFIG_DEPLOYER als maskierte, geschützte Variablen. Halten Sie die kubectl-Version innerhalb einer Nebenversion Ihres Clusters.

4. Terraform in CI/CD

4.1 Plan bei Pull Request, Apply bei Merge

# .github/workflows/infra.yml
name: infra
on:
  pull_request:
    paths: ["infra/**"]
  push:
    branches: [main]
    paths: ["infra/**"]

concurrency:
  group: terraform-production
  cancel-in-progress: false

permissions:
  contents: read
  pull-requests: write

jobs:
  terraform:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra
    env:
      IONOS_TOKEN: ${{ secrets.IONOS_TOKEN }}
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_wrapper: false
      - run: terraform init -input=false
      - run: terraform plan -input=false -no-color -out=tfplan
      - name: Comment the plan
        if: github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          terraform show -no-color tfplan > plan.txt
          gh pr comment ${{ github.event.pull_request.number }} --body-file plan.txt
      - name: Apply
        if: github.event_name == 'push'
        run: terraform apply -input=false tfplan

Der Provider liest IONOS_TOKEN aus der Umgebung, und das s3-Backend aus Einheit 1.2 liest die Object Storage-Schlüssel aus AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY. Die terraform-production-Concurrency-Gruppe serialisiert die Ausführungen, was der sichere Standard ist, bis Sie die Zustandsverriegelung gegenüber Ihrem Bucket verifiziert haben. Halten Sie den Provider auf 6.7.39 fest und commiten Sie .terraform.lock.hcl, damit der Plan im Pull Request und das Apply auf main dieselbe Release-Version verwenden.

Jedes Apply wartet auf die asynchronen IONOS CLOUD-Anfragen. Ein Cluster oder ein Node Pool kann lange dauern, daher senken Sie die timeouts des Providers nicht für CI. Wenn eine Ausführung in der Mitte fehlschlägt, enthält der Zustand bereits die abgeschlossenen Ressourcen; führen Sie die Pipeline nach der Behebung der Ursache erneut aus.

4.2 Verwalten mehrerer Umgebungen

Weisen Sie jeder Umgebung ihren eigenen State-key und ihr eigenes Workflow-Job zu, beispielsweise dev/terraform.tfstate und prod/terraform.tfstate. Schützen Sie den Produktions-Job mit einer GitHub-Umgebung, die einen Reviewer erfordert, damit ein Merge allein die Produktion nicht verändern kann.

5. Deployment-Strategien und Rollback

5.1 Rolling Update und Recreate

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

RollingUpdate ist der Standard in Kubernetes: Neue Pods starten, bevor alte gestoppt werden, und mit maxUnavailable: 0 sinkt die Kapazität nie. Recreate stoppt zuerst alle alten Pods, was Sie nur benötigen, wenn zwei Versionen nicht nebeneinander laufen können, beispielsweise bei einer Änderung des Datenbank-Schemas, die die alte Version unbrauchbar macht. Canary- und Blue-Green-Releases erfordern entweder ein zweites Deployment hinter demselben Service mit weniger Replikaten oder einen Controller wie Argo Rollouts; Einheit 5.3 behandelt GitOps mit ArgoCD.

5.2 Zurücksetzen der Anwendung

kubectl rollout history deploy/taskboard-api
kubectl rollout undo deploy/taskboard-api
kubectl rollout undo deploy/taskboard-api --to-revision=3

Da jedes Image einen Git-SHA-Tag besitzt, stellt ein Rollback einen bekannten Build wieder her. Ein sich ändernder Tag wie latest würde dazu führen, dass die vorherige Revision auf dasselbe, fehlerhafte Image verweist.

5.3 Wiederherstellung des Terraform-Zustands

Einheit 2.4 hat die Versionierung für den State-Bucket aktiviert. Ein beschädigter oder versehentlich überschriebener Zustand kann aus einer älteren Version wiederhergestellt werden:

EP="https://s3.eu-central-3.ionoscloud.com"
aws s3api list-object-versions --endpoint-url "$EP" \
  --bucket taskboard-tfstate-7f3a --prefix prod/terraform.tfstate
aws s3api get-object --endpoint-url "$EP" --bucket taskboard-tfstate-7f3a \
  --key prod/terraform.tfstate --version-id "<version-id>" restored.tfstate
terraform state push restored.tfstate
terraform plan

Halten Sie zunächst alle Pipelines an. Nach dem Push zeigt terraform plan die Differenz zwischen dem wiederhergestellten Zustand und der tatsächlichen Infrastruktur; lösen Sie diese mit Imports (Einheit 1.2) auf, bevor der nächste Apply ausgeführt wird.

6. Terraform-Modul für TaskBoard

Wenn TaskBoard wächst, wiederholen sich dieselben Blöcke in jeder Umgebung. Extrahieren Sie diese in Module:

infra/
  modules/
    mks-cluster/
      main.tf        # ionoscloud_k8s_cluster, ionoscloud_k8s_node_pool
      variables.tf
      outputs.tf
  envs/
    dev/main.tf
    prod/main.tf
# modules/mks-cluster/variables.tf
variable "name"          { type = string }
variable "datacenter_id" { type = string }
variable "lan_id"        { type = string }
variable "k8s_version"   { type = string }
variable "node_count" {
  type    = number
  default = 2
}

# modules/mks-cluster/outputs.tf
output "cluster_id" { value = ionoscloud_k8s_cluster.this.id }
# envs/prod/main.tf
module "mks" {
  source        = "git::https://git.example.com/platform/tf-modules.git//mks-cluster?ref=v1.2.0"
  name          = "taskboard-prod"
  datacenter_id = ionoscloud_datacenter.taskboard.id
  lan_id        = ionoscloud_lan.app.id
  k8s_version   = var.k8s_version
  node_count    = 3
}

Ein Modul deklariert seine Eingaben als Variablen und stellt nur die Ausgaben bereit, die anderer Code benötigt. Verankern Sie Module an einem Git-Tag mit ?ref=, genau so wie Sie den Provider verankern, und veröffentlichen Sie Änderungen als neue Tags. Legen Sie den required_providers-Block mit der ionoscloud-Quelle in jedem Modul ab, damit er den Provider angibt, mit dem er getestet wurde.

API-Referenz-Schnellkarte

Wichtige API-Endpunkte für das Thema dieser Einheit:

Methode Endpunkt Beschreibung
GET https://api.ionos.com/auth/v1/tokens/generate?ttl=<seconds> CI-Zugriffstoken ausgeben
GET /k8s/{k8sClusterId}/kubeconfig Admin-kubeconfig für die Einrichtung herunterladen
GET /requests/{requestId}/status Status einer asynchronen Anfrage abfragen
POST https://api.ionos.com/containerregistries/registries/{registryId}/tokens Registry-Token für eine Pipeline erstellen

Basis-URL: https://api.ionos.com/cloudapi/v6 Authentifizierung: Authorization: Bearer <token>

Code Lab

Ziel: Erstellen Sie eine GitHub Actions-Pipeline, die TaskBoard testet, Git-SHA-Images in die Registry pusht und sie bei jedem Push auf main auf MKS bereitstellt, und anschließend einen fehlerhaften Release zurückrollt.

Voraussetzungen:

  • Die Registry und das Push-Token aus Einheit 3.1
  • Der MKS-Cluster, der taskboard-Namespace, das Deployer-Service-Konto und die laufenden Deployments aus Einheit 3.2
  • Ein GitHub-Repository mit TaskBoard und der gh-CLI

Schritt 1: Erstellen der kubeconfig für den Deployer

Führen Sie die Befehle aus Abschnitt 1.2 mit der Admin-kubeconfig aus.

KUBECONFIG=deployer.yaml kubectl auth can-i update deployments
KUBECONFIG=deployer.yaml kubectl auth can-i create namespaces

Erwartete Ausgabe:

yes
no

Schritt 2: Die Secrets speichern

gh secret set CR_HOST --body "$CR_HOST"
gh secret set CR_USERNAME --body "taskboard-ci-push"
gh secret set CR_PASSWORD < ci-push.pass
gh secret set KUBECONFIG_DEPLOYER --body "$(base64 -w0 deployer.yaml)"
rm deployer.yaml
gh secret list

Erwartete Ausgabe:

CR_HOST              Updated ...
CR_PASSWORD          Updated ...
CR_USERNAME          Updated ...
KUBECONFIG_DEPLOYER  Updated ...

Schritt 3: Workflow hinzufügen

Speichern Sie den Workflow aus Abschnitt 2 als .github/workflows/deploy.yml, und führen Sie anschließend Commit und Push aus.

git add .github/workflows/deploy.yml
git commit -m "ci: deploy TaskBoard to MKS"
git push origin main
gh run watch

Erwartete Ausgabe:

✓ build-deploy
  ✓ Test
  ✓ Build and push
  ✓ Deploy to MKS

Schritt 4: Das laufende Image überprüfen

kubectl -n taskboard get deploy taskboard-api -o jsonpath='{.spec.template.spec.containers[0].image}'
git rev-parse --short=12 HEAD

Erwartete Ausgabe:

<registry-hostname>/taskboard/api:<sha>
<sha>

Schritt 5: Ein fehlerhaftes Release veröffentlichen

Ändern Sie den Readiness-Probe-Pfad in der API, sodass 500 zurückgegeben wird, und führen Sie Commit und Push aus.

git commit -am "break health check" && git push origin main
gh run watch

Erwartete Ausgabe:

X Deploy to MKS
error: timed out waiting for the condition

Schritt 6: Zurückrollen

kubectl -n taskboard rollout undo deploy/taskboard-api
kubectl -n taskboard rollout status deploy/taskboard-api

Erwartete Ausgabe:

deployment.apps/taskboard-api rolled back
deployment "taskboard-api" successfully rolled out

Prüfliste:

  • [ ] Ein Push an main führt Tests aus, pusht beide Images und aktualisiert die Deployments
  • [ ] Das laufende Image-Tag entspricht der Commit-SHA
  • [ ] Ein fehlgeschlagener Rollout führt zum Fehlschlag der Pipeline, und rollout undo stellt den Dienst wieder her
  • [ ] Es werden keine Zugangsdaten im Repository gespeichert

Aufräumarbeiten:

git revert --no-edit HEAD && git push origin main

Behalten Sie den Cluster für Einheit 3.4 und Modul 5 bei, oder führen Sie terraform destroy aus Einheit 3.2 aus.

Häufige Fehler

Fehler von Entwicklerinnen und Entwicklern, die bei dem Thema dieser Einheit zu vermeiden sind:

  1. Zwei Terraform-Ausführungen zur gleichen Zeit

    • Problem: Zwei Mergs in schneller Folge starten zwei Applies, und einer davon schlägt fehl oder hinterlässt den Zustand inkonsistent.
    • Grund: Beide Ausführungen lesen und schreiben dasselbe Zustandsobjekt im Bucket.
    • Lösung: Serialisieren Sie die Ausführungen mit einer concurrency-Gruppe (GitHub) oder resource_group (GitLab) pro Umgebung und wenden Sie nur die geprüften tfplan an.
  2. Zugangsdaten, die stillschweigend ablaufen

    • Problem: Die Pipeline funktionierte wochenlang, dann schlägt jede Ausführung mit 401 auf der Cloud API oder auf docker login fehl.
    • Grund: Das Zugriffstoken erreichte seine ttl, oder das Registry-Token erreichte sein Ablaufdatum und wurde gelöscht.
    • Lösung: Notieren Sie jedes Ablaufdatum neben dem Geheimnis, rotieren Sie es davor und erstellen Sie das Ersatz-Registry-Token, bevor Sie das alte entfernen.
  3. Admin-kubeconfig in CI

    • Problem: Ein kompromittierter Build-Schritt löscht Namespaces oder liest jedes Geheimnis im Cluster.
    • Grund: Die Pipeline verwendet die kubeconfig von der API, die vollen Clusterzugriff hat.
    • Lösung: Verwenden Sie die namespace-spezifische taskboard-deployer-kubeconfig aus Abschnitt 1.2 und halten Sie die Admin-kubeconfig aus CI heraus.

Zusammenfassung

Sie können TaskBoard nun ausschließlich über Code-Reviews ausliefern. Die Anwendungspipeline testet, baut Git-SHA-Images, schiebt sie in die Private Container Registry und rollt sie mit einem Namespace-basierten Konto auf MKS aus. Die Infrastrukturpipeline postet den Terraform-Plan für jeden Pull Request und wendet ihn beim Merge an, jeweils einen Lauf nach dem anderen. Sie können ein Release zurückrollen, eine ältere State-Version wiederherstellen und Infrastruktur als versionierte Module teilen.

Wichtige Punkte:

  • Trennen Sie die Anwendungspipeline und die Infrastrukturpipeline, damit jede nur die Anmeldeinformationen enthält, die sie benötigt
  • Verwenden Sie IONOS_TOKEN für Terraform, ein Access Key- und Secret Key-Paar für das State-Backend und ein Registry-Token für Docker
  • Serialisieren Sie Terraform-Läufe und Deployments pro Umgebung mit concurrency oder resource_group
  • Deployen Sie Git-SHA-Tags und warten Sie auf rollout status; rollen Sie mit kubectl rollout undo zurück
  • Fixieren Sie den Provider und Ihre Module, und stellen Sie den State nur aus Bucket-Versionen wieder her, wenn alle Pipelines gestoppt sind

Wichtige Begriffe:

  • Plan on PR: terraform plan für jeden Pull Request ausführen und das Ergebnis zur Überprüfung posten
  • Concurrency group: Eine CI-Einstellung, die nur einen Lauf pro Gruppe gleichzeitig zulässt
  • Service account kubeconfig: Ein kubeconfig mit einem Kubernetes-Service-Account-Token, das durch RBAC eingeschränkt ist
  • Rolling update: Die Standard-Deployment-Strategie, die Pods schrittweise ersetzt
  • Terraform module: Ein wiederverwendbares Verzeichnis von Ressourcen mit Eingabevariablen und Ausgaben

Nächste Schritte

Weiter lernen: Einheit 3.4: Wissensprüfung - Container und CI/CD

Verwandte Themen: