- Shell 84%
- Dockerfile 8.5%
- Python 4.4%
- Go Template 1.7%
- HTML 1.4%
| app | ||
| charts/multiservice-app | ||
| gitops | ||
| kind | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| docker-compose.yml | ||
| README.md | ||
| setup-cluster.sh | ||
| setup-gitops.sh | ||
| setup-runner.sh | ||
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
mainaktualisiert (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
- baut ggf. das ZFS-fähige Node-Image
kind-node-zfs:v1.37.0(siehekind/), - legt das kind-Cluster
argocd-gitopsan (Registry-Config auf den Nodes), - macht die GitLab-Namen im Cluster auflösbar (siehe unten),
- installiert ArgoCD per Helm (Namespace
argocd, Chartargo-cd:10.10.0= ArgoCD v3.5.4), - 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, kanngitlab(Container-IP) direkt erreichen./etc/hostsauf der Node:host.docker.internal→ Host-Gateway-IP (für containerd) undgitlab→ Container-IP (für den Registry- JWT-Endpointhttp://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) imresolv.confdes 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 unterhost.docker.internalerreicht. - Das Projekt ist in GitLab public (wird von
setup-gitops.shgesetzt) – die Registry erlaubt damit anonyme Pulls, und der Cluster braucht keinimagePullSecret.
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-dindstartet standardmäßig mit TLS auf Port 2376 (DOCKER_TLS_CERTDIR=/certs). Der Job setzt die Job-VariableDOCKER_TLS_CERTDIR: ""→ plain TCP auf 2375. (GitLab 17.9 erlaubt im erweiterten Service-Syntax keinenvironmentfür Services; Job-Variablen werden aber an die Service-Container durchgereicht.) - Insecure Registry:
gitlab:5050ist HTTP-only, dahercommand: ["--insecure-registry=gitlab:5050"]am dind-Service. - Non-fast-forward-sicher: Die Jobs
update-dev/update-prodarbeiten immer auf dem aktuellenmain-Stand (git fetch+git checkout -B ci-release origin/main), weil Tags bzw. Pipeline-Commits hintermainliegen können (z. B. wennupdate-devzwischenzeitlich gecommittet hat). - ZFS-Host: Auf Hosts mit ZFS-Root-Dateisystem crasht der kubelet
ohne
zfs-CLIim Node (cAdvisor) – deshalb das custom Node-Imagekind/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)
-
GitLab CI/CD-Variable
GITOPS_TOKENanlegen (Settings → CI/CD → Variables): Project Access Token mit Scopewrite_repository. ($CI_REGISTRY_USER,$CI_REGISTRY_PASSWORDund$CI_REGISTRY_IMAGEstellt GitLab automatisch bereit.) -
Registry anpassen: In
charts/multiservice-app/values.yamlden Wertglobal.imageRegistryauf$CI_REGISTRY_IMAGEdes Projekts setzen (z. B.registry.gitlab.com/<gruppe>/<projekt>). -
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→ Namespacemultiservice-app-devmultiservice-app-prod→ Namespacemultiservice-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
valueFilesrelativ zum Chart-Pfad auflöst und../-Pfade (path traversal) blockiert. git push -o ci.skipverhindert, 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 auftag: "latest"zeigen – bereits vor dem ersten Release-Tag Images in der Registry finden.