No description
  • Shell 84%
  • Dockerfile 8.5%
  • Python 4.4%
  • Go Template 1.7%
  • HTML 1.4%
Find a file
2026-10-07 22:00:41 +04:00
app feat: initiale Multiservice-App (GitLab CI + ArgoCD GitOps) 2026-10-07 20:48:05 +04:00
charts/multiservice-app chore(prod): release image tag eedff1e0 2026-10-07 17:56:28 +00:00
gitops feat: initiale Multiservice-App (GitLab CI + ArgoCD GitOps) 2026-10-07 20:48:05 +04:00
kind feat: initiale Multiservice-App (GitLab CI + ArgoCD GitOps) 2026-10-07 20:48:05 +04:00
.gitignore feat: initiale Multiservice-App (GitLab CI + ArgoCD GitOps) 2026-10-07 20:48:05 +04:00
.gitlab-ci.yml fix(ci): update-Jobs arbeiten auf aktuellem main-Stand (non-fast-forward-Proof) 2026-10-07 21:47:38 +04:00
docker-compose.yml feat: initiale Multiservice-App (GitLab CI + ArgoCD GitOps) 2026-10-07 20:48:05 +04:00
README.md docs+fix: DNS/Netzwerk-Setup (network connect, /etc/hosts, CoreDNS), public-Projekt, dind-Doku, README 2026-10-07 22:00:41 +04:00
setup-cluster.sh docs+fix: DNS/Netzwerk-Setup (network connect, /etc/hosts, CoreDNS), public-Projekt, dind-Doku, README 2026-10-07 22:00:41 +04:00
setup-gitops.sh docs+fix: DNS/Netzwerk-Setup (network connect, /etc/hosts, CoreDNS), public-Projekt, dind-Doku, README 2026-10-07 22:00:41 +04:00
setup-runner.sh feat: initiale Multiservice-App (GitLab CI + ArgoCD GitOps) 2026-10-07 20:48:05 +04:00

Multiservice-App mit GitLab CI/CD + ArgoCD (GitOps)

Beispiel-Repository, das eine Helm-basierte Multiservice-Anwendung (frontend, backend, worker) mit GitLab CI/CD baut und über ArgoCD nach dem GitOps-Pull-Modell in die Umgebungen dev und prod ausrollt.

Das Beispiel orientiert sich am Helm-Ansatz des kluctl-Beispiels simple-helm: Services werden als Helm-Chart mit Umgebungs-spezifischen Werte-Dateien beschrieben.

Ablauf (GitOps)

   Developer                         GitLab CI                         ArgoCD
   ─────────                         ─────────                         ──────

   git push (main)  ──▶  build:  Images bauen & pushen
                          update-dev: tag in values-dev.yaml ändern
                          + commit & push (ci.skip)   ──▶  erkennt Diff ──▶ DEV

   git tag v1.2.0   ──▶  build:  Images bauen & pushen
                          update-prod: tag in values-prod.yaml ändern
                          + commit & push (ci.skip)   ──▶  erkennt Diff ──▶ PROD
  • dev wird bei jedem Push auf main aktualisiert (Continuous Delivery).
  • prod wird nur bei einem Git-Tag (Release) aktualisiert.
  • ArgoCD arbeitet im Pull-Modus: Es vergleicht den Git-Stand mit dem Cluster und gleicht Abweichungen automatisch aus (self-heal).

Lokale GitLab-Instanz (docker compose)

Für lokale Tests liegt eine vollständige GitLab-Instanz mit Container Registry und einem dind-fähigen Runner bei:

docker-compose.yml   # GitLab CE + Registry (5050) + GitLab Runner
setup-runner.sh      # registriert den Runner automatisch

Starten

# 1. Hostnamen "gitlab" auflösbar machen (für Browser und Git)
echo "127.0.0.1 gitlab" | sudo tee -a /etc/hosts

# 2. GitLab starten (erster Start dauert einige Minuten)
docker compose up -d

# 3. Runner registrieren (sobald GitLab bereit ist)
./setup-runner.sh

Zugangsdaten

Einstellung Wert
Web-UI http://gitlab
Benutzer root
Passwort 12345qwfpg
E-Mail (root) denis.keksel@keksel.pro
Registry gitlab:5050 (HTTP, insecure)
Git-SSH ssh://git@gitlab:2222

Hinweis: Die Registry ist über mehrere Namen erreichbar (Details im Abschnitt kind-Cluster mit ArgoCD).

kind-Cluster mit ArgoCD

Das Kubernetes-Zielcluster (inkl. ArgoCD) wird per kind angelegt:

kind/kind-config.yaml   # kind-Config (containerd vertraut der lokalen Registry)
setup-cluster.sh        # legt das Cluster an und installiert ArgoCD (Helm)
setup-gitops.sh         # Projekt anlegen, Repo pushen, ArgoCD verdrahten

Cluster + ArgoCD anlegen

./setup-cluster.sh

Das Skript

  1. baut ggf. das ZFS-fähige Node-Image kind-node-zfs:v1.37.0 (siehe kind/),
  2. legt das kind-Cluster argocd-gitops an (Registry-Config auf den Nodes),
  3. macht die GitLab-Namen im Cluster auflösbar (siehe unten),
  4. installiert ArgoCD per Helm (Namespace argocd, Chart argo-cd:10.10.0 = ArgoCD v3.5.4),
  5. wartet auf die ArgoCD-Komponenten.

Nameauflösung zwischen kind und GitLab (wichtig!)

Docker isoliert Netzwerke voneinander: Vom kind-Netz aus ist der GitLab-Container nicht direkt erreichbar. ArgoCD (Repo-Clone) und containerd (Image-Pulls + JWT-Auth der Registry) brauchen aber beide Namen, die auf die lokale Umgebung zeigen. setup-cluster.sh regelt das:

  • docker network connect gitlab-net <kind-node> – die Node hängt sich ins Compose-Netz, kann gitlab (Container-IP) direkt erreichen.
  • /etc/hosts auf der Node: host.docker.internal → Host-Gateway-IP (für containerd) und gitlab → Container-IP (für den Registry- JWT-Endpoint http://gitlab/jwt/auth, der aus der Registry-Config kommt). Zusätzlich die suffixed Form <name>.<Search-Domain> – solange eine externe Search-Domain (z. B. eine DynDNS-Domain mit Wildcard) im resolv.conf des Nodes steht, fragt der Resolver die suffixed Form zuerst an und würde sonst das öffentliche A-Record bekommen.
  • CoreDNS-Stub (Hosts-Plugin im Corefile): derselbe hosts-Eintrag für alle Pods, damit z. B. der ArgoCD repo-server GitLab unter host.docker.internal erreicht.
  • Das Projekt ist in GitLab public (wird von setup-gitops.sh gesetzt) – die Registry erlaubt damit anonyme Pulls, und der Cluster braucht kein imagePullSecret.

ArgoCD-Zugang

# Chart 10.x (ArgoCD v3.x): Resource-Name "argocd-*" (nicht "argo-cd-*")
kubectl -n argocd port-forward svc/argocd-server 8080:443
  • Benutzer: admin
  • Passwort: kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d

Registry-Namen im Überblick (eine Registry, drei Namen)

Wer Name
Browser / Host localhost:5050 (Port-Mapping aus docker compose)
GitLab-CI-Jobs gitlab:5050 (Servicename im Compose-Netz)
kind / Kubernetes host.docker.internal:5050 (kind leitet an den Host weiter)

Die kind-Nodes vertrauen der HTTP-Registry über /etc/containerd/certs.d/host.docker.internal:5050/hosts.toml (wird von kind/kind-config.yaml geschrieben).

Repository-Struktur

argocd-multiservice/
├── .gitlab-ci.yml              # CI/CD-Pipeline (validate, build, update-dev, update-prod)
├── docker-compose.yml          # Lokale GitLab-Instanz (Registry 5050) + Runner
├── setup-runner.sh             # Runner registrieren
├── setup-cluster.sh            # kind-Cluster anlegen + ArgoCD installieren
├── setup-gitops.sh             # Projekt, Push, Tokens, ArgoCD-Verdrahtung
├── kind/
│   └── kind-config.yaml        # kind-Config (containerd vertraut der Registry)
├── app/                        # Quellcode der Services
│   ├── frontend/               #   nginx (statische Seite)
│   ├── backend/                #   Python-HTTP-API (Port 8080)
│   └── worker/                 #   Python-Hintergrundjob
├── charts/multiservice-app/    # Helm-Chart (Umbrella)
│   ├── Chart.yaml
│   ├── values.yaml             #   Standardwerte (Registry, Images, Ports)
│   ├── values-dev.yaml         #   DEV-Overrides (Tags werden von CI ersetzt)
│   ├── values-prod.yaml        #   PROD-Overrides (Tags werden von CI ersetzt)
│   └── templates/              #   Deployments + Services
└── gitops/
    └── applicationset.yaml     # ArgoCD ApplicationSet für dev + prod

CI/CD-Details (dind + GitLab 17.9)

  • dind ohne TLS: docker:27-dind startet standardmäßig mit TLS auf Port 2376 (DOCKER_TLS_CERTDIR=/certs). Der Job setzt die Job-Variable DOCKER_TLS_CERTDIR: "" → plain TCP auf 2375. (GitLab 17.9 erlaubt im erweiterten Service-Syntax kein environment für Services; Job-Variablen werden aber an die Service-Container durchgereicht.)
  • Insecure Registry: gitlab:5050 ist HTTP-only, daher command: ["--insecure-registry=gitlab:5050"] am dind-Service.
  • Non-fast-forward-sicher: Die Jobs update-dev/update-prod arbeiten immer auf dem aktuellen main-Stand (git fetch + git checkout -B ci-release origin/main), weil Tags bzw. Pipeline-Commits hinter main liegen können (z. B. wenn update-dev zwischenzeitlich gecommittet hat).
  • ZFS-Host: Auf Hosts mit ZFS-Root-Dateisystem crasht der kubelet ohne zfs-CLI im Node (cAdvisor) – deshalb das custom Node-Image kind/Dockerfile.

Voraussetzungen (lokal)

  • Docker (mit Compose), kind, kubectl, helm
  • ca. 12 GiB freier RAM (GitLab + kind-Cluster) und ~10 GB Platte

Für eine reale Umgebung braucht man: GitLab mit Container Registry, einen Docker-fähigen Runner, ein Kubernetes-Cluster mit ArgoCD und einen Token (GITOPS_TOKEN) mit Scope write_repository.

Einrichtung

Lokal (mit den Skripten aus diesem Repository)

# einmalig: Hostnamen "gitlab" auflösbar machen
echo "127.0.0.1 gitlab" | sudo tee -a /etc/hosts

docker compose up -d     # 1. GitLab + Runner starten
./setup-runner.sh        # 2. Runner registrieren
./setup-cluster.sh       # 3. kind-Cluster + ArgoCD
./setup-gitops.sh        # 4. Projekt, Push, Tokens, ArgoCD verdrahten

Die Skripte übernehmen dabei die manuellen Schritte unten (Tokens, CI/CD-Variable, ArgoCD-Credentials, ApplicationSet).

Manuell (z. B. für GitLab.com)

  1. GitLab CI/CD-Variable GITOPS_TOKEN anlegen (Settings → CI/CD → Variables): Project Access Token mit Scope write_repository. ($CI_REGISTRY_USER, $CI_REGISTRY_PASSWORD und $CI_REGISTRY_IMAGE stellt GitLab automatisch bereit.)

  2. Registry anpassen: In charts/multiservice-app/values.yaml den Wert global.imageRegistry auf $CI_REGISTRY_IMAGE des Projekts setzen (z. B. registry.gitlab.com/<gruppe>/<projekt>).

  3. ArgoCD: Das Git-Repository als Credential/Repository hinterlegen, gitops/applicationset.yaml (repoURL) anpassen und anwenden:

    kubectl apply -f gitops/applicationset.yaml
    

ArgoCD erzeugt daraus automatisch zwei Applications:

  • multiservice-app-dev → Namespace multiservice-app-dev
  • multiservice-app-prod → Namespace multiservice-app-prod

Promotion-Workflow

# DEV aktualisieren (jeder Push auf main)
git commit -m "feat: neue Funktion"
git push origin main
# -> CI baut Images und aktualisiert values-dev.yaml -> ArgoCD synct DEV

# PROD releasen (nur über Tags)
git tag v1.2.0
git push origin v1.2.0
# -> CI baut Images und aktualisiert values-prod.yaml -> ArgoCD synct PROD

Wichtige Hinweise

  • Die Umgebungs-Werte-Dateien liegen im Chart-Verzeichnis, weil ArgoCD valueFiles relativ zum Chart-Pfad auflöst und ../-Pfade (path traversal) blockiert.
  • git push -o ci.skip verhindert, dass der CI-Commit eine neue Pipeline auslöst (Endlosschleife).
  • In Produktion trennt man üblicherweise App-Repo (Build) und Config-Repo (Deployment). Hier ist beides bewusst in einem Repo zusammengefasst, um das Beispiel einfach zu halten.
  • CI pusht zusätzlich den Tag latest (neben dem SHA-Tag), damit beide Umgebungen – die initial auf tag: "latest" zeigen – bereits vor dem ersten Release-Tag Images in der Registry finden.