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
mainfü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 undostellt 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:
-
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) oderresource_group(GitLab) pro Umgebung und wenden Sie nur die geprüftentfplanan.
-
Zugangsdaten, die stillschweigend ablaufen
- Problem: Die Pipeline funktionierte wochenlang, dann schlägt jede Ausführung mit
401auf der Cloud API oder aufdocker loginfehl. - 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.
- Problem: Die Pipeline funktionierte wochenlang, dann schlägt jede Ausführung mit
-
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_TOKENfü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
concurrencyoderresource_group - Deployen Sie Git-SHA-Tags und warten Sie auf
rollout status; rollen Sie mitkubectl rollout undozurü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 planfü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: