13 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • ArgoCD auf Managed Kubernetes installieren und TaskBoard aus Git mit einem `Application` bereitstellen, das automatisch synchronisiert und sich selbst heilt
  • TaskBoard in ein Infrastruktur-Repository (Terraform, apply on merge) und ein Anwendungs-Repository (Manifeste, ArgoCD sync) aufteilen
  • Image-Tags von dev über staging bis production mit Kustomize-Overlays und Pull Requests hochstufen
  • Zweigumgebungen automatisch aus der CI erstellen und zerstören, um Kosten unter Kontrolle zu halten
  • Eine klare Zuständigkeitsgrenze zwischen Terraform und ArgoCD ziehen, damit die beiden Werkzeuge nie um dasselbe Objekt konkurrieren

Einheit 5.3: GitOps und Deployment-Operationen

Einführung

Die Pipeline von TaskBoard aus Einheit 3.3 schiebt Änderungen in den Cluster: CI hält eine kubeconfig und führt kubectl set image aus. Das funktioniert, aber der Clusterzustand ist, was der letzte Job getan hat, ein manuelles kubectl edit bleibt unbemerkt, und jede Pipeline benötigt Zugangsdaten für den Cluster.

GitOps dreht das um. Git hält den gewünschten Zustand der Anwendung, und ein Agent innerhalb des Clusters zieht ihn ab und gleicht ihn kontinuierlich ab. Wenn jemand ein Deployment manuell ändert, stellt der Agent es wieder her. Wenn Sie zurückrollen möchten, setzen Sie einen Commit zurück. In dieser Einheit installieren Sie ArgoCD auf MKS, verbinden es mit den Manifests von TaskBoard, strukturieren die Repositories, fördern Releases über Umgebungen hinweg und räumen Branch-Umgebungen automatisch ab. Sie entscheiden auch, welches Tool welches Objekt verwaltet, damit Terraform und ArgoCD die Arbeit des jeweils anderen nicht rückgängig machen.

1. GitOps-Prinzipien in der Praxis

1.1 Push vs. Pull

Aspekt Push (Einheit 3.3) Pull (GitOps)
Wer ändert den Cluster CI-Job mit einer kubeconfig Agent im Cluster
Quelle der Wahrheit Letzter erfolgreicher Job Git-Branch oder Tag
Manuelle Änderung im Cluster Bleibt bis zum nächsten Deploy Wird erkannt und zurückgesetzt
Rollback kubectl rollout undo git revert
Cluster-Zugangsdaten in CI Erforderlich Nicht erforderlich

Das Pull-Modell vereinfacht auch den Zugriff auf die Kubernetes API. Wenn Sie diese mit api_subnet_allow_list (Einheit 3.2) eingeschränkt haben, muss jeder externe CI-Runner in dieser Liste aufgeführt sein. ArgoCD läuft innerhalb des Clusters und kommuniziert mit dem API-Server über https://kubernetes.default.svc, wobei der interne Cluster-Verkehr von der Zulassungsliste nicht betroffen ist.

1.2 Drift-Erkennung

Drift ist jede Abweichung zwischen Git und dem Live-Zustand. Sie erkennen bereits Infrastruktur-Drift mit terraform plan -detailed-exitcode (Einheit 5.2). ArgoCD macht dasselbe für Manifeste:

argocd app diff taskboard-dev        # exit code 1 when live state differs from Git
argocd app get taskboard-dev -o json | jq -r '.status.sync.status, .status.health.status'

Synced und Healthy bedeuten, dass der Cluster mit Git synchron ist und alle Ressourcen ihre Health Checks bestehen, einschließlich der Readiness-Probes aus Einheit 5.1.

2. ArgoCD auf MKS

2.1 Installation

kubectl create namespace argocd
kubectl apply -n argocd \
  -f "https://raw.githubusercontent.com/argoproj/argo-cd/${ARGOCD_VERSION}/manifests/install.yaml"
kubectl -n argocd rollout status deploy/argocd-server
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d

Festigen Sie ARGOCD_VERSION an einem Release-Tag, genau so wie Sie den Terraform-Provider festlegen, und führen Sie das Upgrade über einen Pull Request durch. Greifen Sie über kubectl -n argocd port-forward svc/argocd-server 8080:443 auf die Benutzeroberfläche zu. Stellen Sie sie nicht mit type: LoadBalancer bereit: Auf MKS erhält dieser Service eine statische IP-Adresse auf einem einzelnen Knoten, nicht einen Load Balancer (Einheit 3.2). Wenn das Team einen dauerhaften Zugriff benötigt, leiten Sie den Verkehr über den Ingress-Controller hinter dem ALB.

2.2 Verknüpfen des Anwendungs-Repositorys

apiVersion: v1
kind: Secret
metadata:
  name: taskboard-deploy-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://git.example.com/taskboard/deploy.git
  username: argocd
  password: <read-only access token>

Erstellen Sie dieses Secret aus Ihrem Secret Store, wie in Einheit 5.2 beschrieben, niemals aus einer Datei in Git. ArgoCD benötigt nur Lesezugriff; es schiebt niemals Änderungen.

2.3 Die Application-CRD

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: taskboard-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example.com/taskboard/deploy.git
    targetRevision: main
    path: overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: taskboard
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

automated synchronisiert jeden neuen Commit auf main. prune löscht Objekte, die Sie aus Git entfernt haben, und selfHeal hebt manuelle Änderungen im Cluster zurück. ArgoCD wendet Manifeste an, stellt aber keine Registry-Zugangsdaten bereit: Die Pods benötigen weiterhin den Eintrag imagePullSecrets und das Pull-Secret aus Einheit 3.2, sonst verbleiben sie im Zustand ImagePullBackOff.

3. Repository-Topologie und Promotion

3.1 Zwei Repositories, zwei Verantwortliche

taskboard-infra/                 taskboard-deploy/
  modules/                         base/
    mks-cluster/                     api-deployment.yaml
    postgres/                        web-deployment.yaml
  envs/                              worker-deployment.yaml
    dev/main.tf                      kustomization.yaml
    staging/main.tf                overlays/
    prod/main.tf                     dev/kustomization.yaml
  .github/workflows/infra.yml        staging/kustomization.yaml
                                     prod/kustomization.yaml

taskboard-infra ist das Infrastruktur-Repository aus Einheit 3.3: Planung über Pull Request, Anwendung bei Merge, mit IONOS_TOKEN in seinen Secrets. taskboard-deploy enthält ausschließlich Kubernetes-Manifeste und verfügt über keinerlei Cloud-Zugangsdaten. Der Quellcode der Anwendung verbleibt in einem dritten Repository, dessen CI Bilder baut und pusht.

3.2 Overlays und Image-Tags

Das Produktions-Overlay, overlays/prod/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: taskboard
resources:
  - ../../base
images:
  - name: taskboard-api
    newName: <registry-hostname>/taskboard/api
    newTag: 3f9c2a1b7d04
replicas:
  - name: taskboard-api
    count: 3

Die Basis-Manifeste verweisen auf das Image als taskboard-api, und jedes Overlay fixiert den Git-SHA-Tag aus Einheit 3.1. Eine Promotion ist ein Commit, der einen getesteten Tag von einem Overlay zum nächsten kopiert.

3.3 Promotion aus CI

Die Anwendung-CI greift nicht mehr in den Cluster ein. Nach dem Push des Images öffnet sie einen Pull Request gegen taskboard-deploy:

SHA="${GITHUB_SHA::12}"
git clone "https://x-access-token:${DEPLOY_REPO_TOKEN}@git.example.com/taskboard/deploy.git"
cd deploy/overlays/dev
kustomize edit set image "taskboard-api=${CR_HOST}/taskboard/api:${SHA}"
git checkout -b "promote-dev-${SHA}"
git commit -am "dev: taskboard-api ${SHA}"
git push origin "promote-dev-${SHA}"
gh pr create --title "dev: taskboard-api ${SHA}" --body "Automated promotion" --base main

Für die Entwicklungsumgebung können Sie bei bestandenen Prüfungen automatisch zusammenführen. Für Staging und Produktion ist eine Überprüfung erforderlich, sodass der Verlauf der Pull Requests Ihr Veröffentlichungsprotokoll darstellt. Ein Rollback ist git revert des Promotion-Commits; ArgoCD synchronisiert das vorherige Tag zurück.

4. Branch-Umgebungen und automatisierte Aufräumvorgänge

4.1 Ein Zustand pro Branch

Der Workflow .github/workflows/branch-env.yml in taskboard-infra:

on:
  pull_request:
    types: [opened, synchronize, closed]
jobs:
  env:
    runs-on: ubuntu-latest
    concurrency: branch-${{ github.head_ref }}
    defaults:
      run:
        working-directory: envs/branch
    env:
      IONOS_TOKEN: ${{ secrets.IONOS_TOKEN }}
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      TF_VAR_branch: ${{ github.head_ref }}
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init -input=false -backend-config="key=branches/${TF_VAR_branch}/terraform.tfstate"
      - if: github.event.action != 'closed'
        run: terraform apply -input=false -auto-approve
      - if: github.event.action == 'closed'
        run: terraform destroy -input=false -auto-approve

Jede Pull Request erhält ihr eigenes Zustandsobjekt im State-Bucket, sodass eine Branch-Umgebung niemals den Zustand von dev oder production berühren kann. Benennen Sie jede Ressource nach var.branch und halten Sie den Branch-Stack klein: ein Object Storage-Bucket, eine Datenbank und ein Namespace auf dem gemeinsamen dev-Cluster, nicht ein eigenes Cluster.

4.2 Aufräumen, das tatsächlich ausgeführt wird

Ressourcen verursachen Kosten ab dem Moment, in dem sie existieren, und eine vergessene Branch-Umgebung kostet Geld jede Stunde. Das nächtliche Sicherheitsnetz zerstört Branch-Zustände, deren Pull Request geschlossen ist:

for key in $(aws s3 ls --endpoint-url "$EP" "s3://taskboard-tfstate-7f3a/branches/" | awk '{print $2}' | tr -d /); do
  state=$(gh pr list --head "$key" --state open --json number --jq 'length')
  if [ "$state" = "0" ]; then
    terraform init -reconfigure -input=false -backend-config="key=branches/${key}/terraform.tfstate"
    TF_VAR_branch="$key" terraform destroy -input=false -auto-approve
  fi
done

Das ist eine von drei Schutzmaßnahmen. Erstens zerstört das closed-Event den Stack, wenn der Pull Request gemergt oder geschlossen wird. Zweitens erfasst der nächtliche Job fehlgeschlagene Ausführungen; er setzt Branch-Namen ohne / voraus, verwenden Sie daher einen Slug, falls Ihre Namen eines enthalten. Drittens versehen Sie Branch-Ressourcen mit dem Branch-Namen und einem Erstellungsdatum, sofern die Ressource dies unterstützt, damit bei einer Prüfung des Vertrags Rückstände sichtbar werden. Wenn ein Managed Kubernetes-Cluster Teil eines Branch-Stacks ist, müssen seine Node Pools vor dem Cluster gelöscht werden; Terraform ordnet dies über die Abhängigkeit zwischen ionoscloud_k8s_node_pool und ionoscloud_k8s_cluster an.

Die ArgoCD-Seite räumt ebenfalls auf. Mit prune: true und einem ApplicationSet, das einen Application pro offenem Pull Request generiert, wird beim Schließen des Pull Requests der generierte Application und seine Namespace-Ressourcen gelöscht.

5. Terraform und ArgoCD: Wer besitzt was

5.1 Die Grenze der Zuständigkeit

Objekt Zuständig Grund
Rechenzentren, LANs, NSGs, ALB, Zielgruppen Terraform IONOS CLOUD-Ressourcen, benötigen IONOS_TOKEN
MKS-Cluster, Node-Pools, kubeconfig Terraform IONOS CLOUD-Ressourcen
DBaaS, In-Memory DB, Kafka, Object Storage-Buckets Terraform IONOS CLOUD-Ressourcen
Deployments, Services, Ingress, ConfigMaps, NetworkPolicies ArgoCD Kubernetes-Objekte, versioniert mit der App
Secrets mit Zugangsdaten External Secrets Operator, synchronisiert durch ArgoCD Werte verbleiben im Secret Store
ArgoCD selbst und seine Application-Objekte Einmalige Initialisierung, danach ArgoCD Vermeidet eine Abhängigkeitsschleife

Ein Objekt, ein Zuständiger. Die Brücke zwischen den beiden Welten sind Daten, keine geteilten Ressourcen: Terraform-Ausgaben wie pg_host werden in den Secret Store übernommen, und die Manifeste verweisen auf das daraus resultierende Kubernetes-Secret (Einheit 5.2).

5.2 Vermeidung von Konfliktschleifen

Eine Konfliktschleife entsteht, wenn zwei Controller dasselbe Feld immer wieder ändern. Damit ein HorizontalPodAutoscaler die Anzahl der Replikate verwaltet, fügen Sie dies zum Application hinzu:

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      name: taskboard-api
      jsonPointers:
        - /spec/replicas

Typische TaskBoard-Fälle:

  • HPA vs Git: Wenn eine HPA taskboard-api skaliert, entfernen Sie replicas aus dem Overlay oder ignorieren Sie das Feld wie gezeigt, da sonst selfHeal die Anzahl bei jeder Synchronisierung zurücksetzt.
  • Autoscaler vs Terraform: Bei auto_scaling in einem Node-Pool behalten Sie lifecycle { ignore_changes = [node_count] } aus Einheit 3.2 bei, da sonst jeder Apply den Pool zurücksetzt.
  • CI vs ArgoCD: Entfernen Sie kubectl set image aus dem Workflow von Einheit 3.3, wenn ArgoCD übernimmt. Mit selfHeal stellt ArgoCD den Zustand innerhalb weniger Minuten wieder her, und die Bereitstellung scheint von selbst zurückgerollt zu werden.
  • Terraform vs MKS: Die Server, NICs und IPs, die Managed Kubernetes in Ihrem Rechenzentrum erstellt, werden in der DCD schreibgeschützt angezeigt. Importieren Sie diese niemals in Terraform; verwalten Sie sie über den Node-Pool.

Schnellreferenz für die API

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

Methode Endpunkt Beschreibung
GET /k8s/{k8sClusterId}/kubeconfig Kubeconfig herunterladen, um ArgoCD einzurichten
GET /k8s/{k8sClusterId}/nodepools Knotenpools vor dem Abbau einer Branch prüfen
DELETE /k8s/{k8sClusterId}/nodepools/{nodepoolId} Einen Knotenpool löschen (vor dem Cluster)
DELETE /k8s/{k8sClusterId} Ein Cluster ohne Knotenpools löschen
GET /requests/{requestId}/status Eine asynchrone Löschung abfragen

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

Code Lab

Ziel: Richten Sie die automatische Synchronisierung von ArgoCD für die Manifeste von TaskBoard ein, schieben Sie eine Manifeständerung und beobachten Sie die Abgleichung, rollen Sie eine manuelle Änderung über die Selbstheilung zurück und räumen Sie eine Branch-Umgebung ab.

Voraussetzungen:

  • Der MKS-Cluster und der TaskBoard-Namespace aus Einheit 3.2, einschließlich der admin-kubeconfig
  • Ein taskboard-deploy-Repository mit base/ und overlays/dev/ gemäß Abschnitt 3
  • Die argocd-CLI, kustomize, gh und Terraform mit dem State-Bucket aus Einheit 2.4

Schritt 1: ArgoCD installieren

export ARGOCD_VERSION="<release tag>"
kubectl create namespace argocd
kubectl apply -n argocd -f "https://raw.githubusercontent.com/argoproj/argo-cd/${ARGOCD_VERSION}/manifests/install.yaml"
kubectl -n argocd rollout status deploy/argocd-server

Erwartete Ausgabe:

deployment "argocd-server" successfully rolled out

Schritt 2: Anmelden

kubectl -n argocd port-forward svc/argocd-server 8080:443 &
argocd login localhost:8080 --username admin --insecure \
  --password "$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d)"

Erwartete Ausgabe:

'admin:login' logged in successfully

Schritt 3: Repository und Anwendung registrieren

Wenden Sie das Repository-Secret (Abschnitt 2.2) und das Application (Abschnitt 2.3) an.

kubectl apply -f argocd/repo-secret.yaml -f argocd/taskboard-dev.yaml
argocd app wait taskboard-dev --health --timeout 300

Erwartete Ausgabe:

Name:     argocd/taskboard-dev
Sync Status:   Synced to main (<sha>)
Health Status: Healthy

Schritt 4: Änderungen an einem Manifest hochladen

cd taskboard-deploy/overlays/dev
kustomize edit set image "taskboard-api=${CR_HOST}/taskboard/api:<new-sha>"
git commit -am "dev: taskboard-api <new-sha>" && git push
argocd app get taskboard-dev --refresh | grep -E "Sync Status|Health"

Erwartete Ausgabe:

Sync Status:   Synced to main (<new commit>)
Health Status: Healthy

Schritt 5: Selbstheilung beobachten

kubectl -n taskboard scale deploy/taskboard-web --replicas=0
sleep 30
kubectl -n taskboard get deploy taskboard-web

Erwartete Ausgabe:

NAME            READY   UP-TO-DATE   AVAILABLE
taskboard-web   2/2     2            2

Schritt 6: Zweigumgebung erstellen und zerstören

Öffnen Sie in taskboard-infra eine Pull Request mit dem Workflow aus Abschnitt 4.1, warten Sie auf die Anwendung und schließen Sie anschließend die Pull Request.

gh pr close <number>
gh run watch

Erwartete Ausgabe:

✓ env
  ✓ terraform destroy -input=false -auto-approve
Destroy complete! Resources: <n> destroyed.

Validierungscheckliste:

  • [ ] taskboard-dev ist Synced und Healthy
  • [ ] Ein Commit auf overlays/dev ändert das laufende Image, ohne dass CI auf den Cluster zugreifen muss
  • [ ] Ein manuelles Herunterskalieren wird durch die Selbstheilung rückgängig gemacht
  • [ ] Das Schließen des Pull Requests zerstört den Branch-Stack und hinterlässt keinen Zustand außer dem leeren Zustandsobjekt

Aufräumarbeiten:

argocd app delete taskboard-dev --yes
kubectl delete namespace argocd
kill %1

Häufige Fehler

Fehler von Entwicklerinnen und Entwicklern, die bei diesem Thema der Einheit zu vermeiden sind:

  1. Die Deployment, die sich selbst zurückrollt

    • Problem: CI deployt ein neues Image, und wenige Minuten später läuft wieder das alte Image.
    • Ursache: Der alte kubectl set image-Schritt ist noch in der Pipeline, und ArgoCDs selfHeal stellt den Tag aus Git wieder her.
    • Lösung: Images nur über Commits im Overlay ändern (Abschnitt 3.3) und die Cluster-Anmeldeinformationen aus der CI der Anwendung entfernen.
  2. Branch-Umgebungen, die niemand zerstört

    • Problem: Die Abrechnung wächst jeden Monat, und der Vertrag enthält Buckets und Datenbanken, die nach längst gemergten Branches benannt sind.
    • Ursache: Der closed-Job ist einmal fehlgeschlagen oder wurde ausgeführt, bevor terraform init auf den State-Schlüssel des Branches zeigte.
    • Lösung: Einen State-Schlüssel pro Branch verwenden, destroy auf closed ausführen und das nächtliche Sicherheitsnetz aus Abschnitt 4.2 hinzufügen.
  3. Terraform und ArgoCD verwalten dasselbe Objekt

    • Problem: Jede terraform apply ändert eine Deployment, und jeder ArgoCD-Sync ändert sie wieder zurück.
    • Ursache: Die Deployment wurde mit dem Kubernetes Terraform Provider erstellt und befindet sich auch im Deployment-Repository.
    • Lösung: Einen Besitzer pro Objekt festlegen (Abschnitt 5.1); die Ressource mit terraform state rm aus dem Terraform-State entfernen und ArgoCD als Besitzer überlassen.

Zusammenfassung

Sie können TaskBoard nun deklarativ betreiben. Terraform verwaltet alle Ressourcen, die IONOS CLOUD-Ressourcen sind, und wendet sie beim Merge an; ArgoCD verwaltet alle Objekte, die Kubernetes-Objekte sind, und synchronisiert sie aus Git mit Pruning und Self-Heal. Releases werden als geprüfte Commits zu Kustomize-Overlays zwischen Umgebungen verschoben, und Branch-Umgebungen werden durch den Lebenszyklus der Pull Requests erstellt und zerstört.

Wichtige Punkte:

  • Git ist die einzige Wahrheit; ArgoCD zieht und versöhnt, daher benötigt CI keine Cluster-Zugangsdaten
  • ArgoCD verwendet kubernetes.default.svc, daher blockiert die API-Allowlist es nicht
  • Promotion durch Commit von Image-Tags in Overlays; Rollback mit git revert
  • Ein State-Key pro Branch, Zerstörung beim Schließen des Pull Requests, plus ein nächtliches Sicherheitsnetz
  • Ein Besitzer pro Objekt: Terraform für IONOS CLOUD-Ressourcen, ArgoCD für Kubernetes-Objekte

Wichtige Begriffe:

  • GitOps: Betrieb eines Systems durch Deklaration des gewünschten Zustands in Git und automatische Versöhnung
  • Application: Das ArgoCD-Custom Resource, das einen Git-Pfad einem Cluster-Namespace zuordnet
  • Self-Heal: Automatische Rücknahme von Änderungen durch ArgoCD, die direkt im Cluster vorgenommen wurden
  • Overlay: Ein Kustomize-Verzeichnis, das die gemeinsame Basis für eine Umgebung patcht
  • Fight loop: Zwei Controller überschreiben wiederholt dasselbe Feld desselben Objekts

Nächste Schritte

Weiter lernen: Einheit 5.4: Wissensprüfung - Produktionsbetrieb

Verwandte Themen: