How henryhst/gitlab-terraform-hcloud works
1. Projektart und Zweck
Das Repository ist keine Applikation, sondern eine Infrastructure-as-Code- und Betriebs-Repo für Hetzner Cloud, optional Proxmox, und eine GitLab-Installation. Die zentrale Ebene ist terraform/; dort werden Infrastruktur, DNS und optionale GitLab-Objekte zusammengesetzt.
2. Zentrale Orchestrierung im Root-Terraform
terraform/main.tf ist der Einstiegspunkt. Es verknüpft die Grundbausteine in einer festen Reihenfolge: Firewall → Server → DNS. Diese Abhängigkeiten bestimmen die Provisionierungsreihenfolge und damit den Kern der Architektur.
3. Basis-Infrastruktur auf Hetzner Cloud
Der Default-Stack erzeugt über den hcloud-Provider einen Hauptserver, eine Firewall und eine Hetzner-DNS-Zone samt Records. Der Hauptserver liefert die öffentliche IPv4, die anschließend in DNS-A-Records verwendet wird.
4. GitLab-Betriebsmodi als Architektur-Schalter
Die Variable gitlab_install_mode steuert, wie GitLab bereitgestellt wird:
- none: nur Infrastruktur
- hetzner_app: Hetzner-App-Image mit Omnibus-Setup
- docker_compose: Debian-VM mit Docker Compose-Stack
- proxmox: gleiche Compose-Basis, aber als QEMU-VM in Proxmox
Diese Modi ändern vor allem die Server- und Cloud-Init-Schicht, nicht die Root-Struktur.
5. Docker-Compose-Stack als eigener Subsystem-Bereich
Im docker_compose-Modus läuft GitLab auf Debian mit einem Stack unter /opt/gitlab. Der Stack umfasst typischerweise GitLab CE, Traefik als Reverse Proxy/TLS-Terminator und PostgreSQL als externe Datenbank. Optional kommen GitLab Runner, Container Registry und Mend Renovate CE dazu.
6. DNS als separate Außenkante
Das modules/dns-Modul verwaltet die authoritative Hetzner-DNS-Zone und mehrere Records: Web-, Mail-, Autoconfig/Autodiscover-, DKIM/SPF/DMARC-, CAA-, TLSA- und SRV-Einträge. Für den Architekturplan ist wichtig: DNS ist nicht nur ein A-Record, sondern ein eigener Verwaltungsbereich mit mehreren Zielsystemen.
7. GitLab-API-Ressourcen als unabhängige zweite Steuerungsebene
terraform/gitlab.tf und modules/gitlab-api legen optional per GitLab-Provider Gruppen, Projekte, Bot-User und Webhooks an. Diese Ressourcen hängen nicht vom Installationsmodus ab, sondern nur von enable_gitlab_resources und der Erreichbarkeit der GitLab-API. Das ist eine separate Management-Integration neben der Infrastruktur.
8. Optionaler separater GitLab Runner
Bei enable_gitlab_runner = true wird zusätzlich eine eigene Hetzner-VM provisioniert, samt eigener Firewall und DNS-A-Record. Das trennt CI-Ausführung von der GitLab-Hauptinstanz. Im Compose-Modus gibt es außerdem die Alternative, den Runner direkt im Stack zu betreiben und automatisch zu registrieren.
9. Proxmox als alternativer Ziel-Provider
Proxmox ist eine optionale Zielplattform mit eigenem Provider (telmate/proxmox) und dem Modul modules/proxmox. Dort werden QEMU-VMs und ein Cloud-Init-Snippet bereitgestellt, das inhaltlich denselben Compose-Start wie auf Hetzner nutzt. Proxmox ist also kein zweites Produkt, sondern ein alternativer Host-Layer.
10. Cloud-Init als Übergang zwischen IaC und Laufzeit
Die Templates unter terraform/templates/ bilden die Brücke von Terraform zur laufenden Maschine: Sie konfigurieren Docker, GitLab, Runner oder Compose-Bootstrapping beim ersten Start. Architekturdiagrammseitig ist das die Übergangsschicht zwischen Provisioning und Anwendungsbetrieb.
11. Provider- und Secret-Grenzen
Es gibt mehrere klar getrennte API-Bereiche:
- hcloud für Server, Firewall, Hetzner-DNS
- gitlab für GitLab-Gruppen/Projekte
- optional proxmox für VM-Management
Dazu kommen getrennte Eingaben für Cloud-, DNS- und GitLab-Tokens. Das Repository modelliert diese Grenzen bewusst separat.
12. Betriebs- und Qualitätswerkzeuge als Nebenpfad
.github/workflows/terraform.yml, .gitlab-ci.yml und Makefile decken Formatierung, Validation und TFLint ab. Die scripts/-Dateien sind Hilfswerkzeuge für Checks und Reparaturen, keine Laufzeitkomponenten der Zielumgebung. Sie gehören in die operative Unterstützungsschicht, nicht in den Produktivpfad.
13. Dokumentationsstruktur als Architektur-Hinweis
docs/ ist stark architekturorientiert: Installationsmodi, Proxmox, Referenz, Betrieb und Diagramme sind dort getrennt beschrieben. Für eine Diagrammerstellung sind vor allem docs/diagrams/* und docs/gitlab-install-modes.md die besten Quellen für Subsystemgrenzen und Datenflüsse.
14. Kern-Datenflüsse für ein Diagramm
Die wichtigsten Flüsse sind:
- Terraform-Variablen/Tokens → Provider
- Provider → Hetzner/Proxmox/GitLab APIs
- Server-Outputs → DNS-Records
- Cloud-Init/Templates → Host-Startkonfiguration
- optional GitLab-API → Gruppen/Projekte/Webhooks
- optional Runner-VM oder Compose-Runner → CI-Ausführung
Diese Flüsse bilden die eigentliche Architektur des Repos.
Main entry points: terraform/main.tf Main stack · provider.tf Providers · proxmox/main.tf Proxmox module · gitlab.tf GitLab resources
Components 25
Terraform root
Top-level orchestration, providers, variables, and entrypoint configuration.
- Main stack · Primary orchestration entrypoint that wires firewall, server, DNS, and optional GitLab resources.
terraform/main.tf - Providers · Declares the Hetzner, GitLab, and optional Proxmox provider boundaries.
terraform/provider.tf - Inputs · Defines deployment knobs such as install mode, tokens, and feature flags.
terraform/variables.tf - Outputs · Exports selected infrastructure facts from the root stack.
terraform/outputs.tf - GitLab resources · Optional root-level GitLab API resources for groups, projects, bots, and webhooks.
terraform/gitlab.tf
Terraform modules
Reusable infrastructure and integration modules.
- DNS module · Manages the authoritative Hetzner DNS zone and service records.
terraform/modules/dns/main.tf - Firewall module · Builds the Hetzner firewall policy used by server and runner hosts.
terraform/modules/firewall/main.tf - Server module · Provisions the main Hetzner cloud server and exposes its network outputs.
terraform/modules/server/main.tf - GitLab API module · Creates GitLab-side organization objects and hooks through the GitLab API.
terraform/modules/gitlab-api/main.tf - Proxmox module · Provisioning layer for QEMU VMs and cloud-init on Proxmox.
terraform/modules/proxmox/main.tf
Runtime targets
Managed external platforms and services.
- Hetzner Cloud · Target API for servers, firewalls, and DNS management.
- GitLab API · Target API for GitLab organizational resources and webhooks.
- Proxmox API · Target API for VM lifecycle management on Proxmox.
- GitLab host · The deployed GitLab instance, either on Hetzner or Proxmox depending on install mode.
- Runner host · Optional separate CI runner VM or runner process in the compose stack.
- DNS zone · Authoritative DNS zone and records for web, mail, auth, and security entries.
Operational support
Templates, docs, and automation around provisioning and validation.
- Cloud-init templates · Templates that bridge Terraform into first-boot Docker, GitLab, and runner setup.
terraform/templates/gitlab-docker-cloud-init.yaml.tpl - Install modes · Describes the GitLab deployment modes and their architecture differences.
docs/gitlab-install-modes.md - Proxmox guide · Documents the Proxmox target platform and its operational model.
docs/proxmox.md - Operations · Operational runbook for managing the infrastructure and services.
docs/operations.md - Terraform CI · GitHub Actions validation and formatting pipeline for the Terraform stack.
.github/workflows/terraform.yml - GitLab CI · Repository-side CI path for checks and related maintenance tasks.
.gitlab-ci.yml - Makefile · Local command entrypoint for formatting, validation, and checks.
Makefile - Runner checks · Operational helper for runner/bootstrap verification.
scripts/check-compose-image-versions.sh - Backup example · Example CI configuration used as reference for backup workflows.
docs/examples/gitlab-backup-ci.yml.example
Connections 29
- Main stack → Providers: uses providers · Root orchestration depends on the declared provider boundaries.
- Main stack → Inputs: reads inputs · Deployment mode and feature flags steer the chosen stack path.
- Main stack → Firewall module: creates firewall · Provisioning starts with the shared firewall baseline.
- Main stack → Server module: creates server · Main host is provisioned after the firewall baseline.
- Main stack → DNS module: creates DNS · DNS records are assembled after host outputs are available.
- Main stack → GitLab resources: optional resources · Optional GitLab-side objects are attached when enabled.
- Providers → Hetzner Cloud: hcloud · Hetzner provider drives server, firewall, and DNS APIs.
- Providers → GitLab API: gitlab · GitLab provider drives organization and webhook resources.
- Providers → Proxmox API: proxmox · Optional Proxmox provider manages alternate VM hosting.
- Firewall module → Hetzner Cloud: firewall API · Firewall rules are applied in Hetzner Cloud.
- Server module → Hetzner Cloud: server API · Main host lifecycle is managed in Hetzner Cloud.
- DNS module → Hetzner Cloud: dns API · Zone and record management is handled through Hetzner DNS.
- DNS module → DNS zone: publishes records · Creates A, MX, TXT, SRV, CAA, TLSA, and related records.
- Server module → GitLab host: hosts GitLab · The main server becomes the GitLab host in Hetzner-based modes.
- Cloud-init templates → GitLab host: bootstraps host · Cloud-init templates configure the machine at first boot.
- GitLab resources → GitLab API: manages org · Optional groups, projects, bots, and hooks are created via the API.
- GitLab resources → GitLab host: targets instance · API resources depend on the deployed GitLab endpoint being reachable.
- Proxmox module → Proxmox API: vm API · QEMU VM lifecycle is managed through Proxmox.
- Proxmox module → Cloud-init templates: uses cloud-init · Proxmox instances boot with the same bootstrap templates.
- Proxmox module → GitLab host: alt host · Proxmox provides an alternate GitLab host layer.
- Inputs → Cloud-init templates: fills templates · Inputs control cloud-init and bootstrap rendering.
- Install modes → Main stack: documents modes · Explains how install modes alter the root Terraform flow.
- Proxmox guide → Proxmox module: documents platform · Explains the alternate Proxmox target and its constraints.
- Operations → Makefile: supports ops · Operational guidance aligns with local run and check commands.
- Terraform CI → Main stack: validates · CI checks Terraform formatting and validation.
- GitLab CI → GitLab resources: runs checks · Repository CI covers GitLab-related automation paths.
- Makefile → Terraform CI: mirrors checks · Local commands mirror the automated validation pipeline.
- Runner checks → Runner host: verifies runner · Helper script inspects compose image/version expectations for runner-related flows.
- Backup example → GitLab host: backup flow · Example CI config illustrates backup handling for the GitLab deployment.