# henryhst/gitlab-terraform-hcloud architecture

> Architecture diagram of the GitHub repository henryhst/gitlab-terraform-hcloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/henryhst/gitlab-terraform-hcloud
- Repository: https://github.com/henryhst/gitlab-terraform-hcloud

## Overview

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`](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/main.tf) (Main stack), [`terraform/provider.tf`](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/provider.tf) (Providers), [`terraform/modules/proxmox/main.tf`](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/proxmox/main.tf) (Proxmox module), [`terraform/gitlab.tf`](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/gitlab.tf) (GitLab resources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_terraform_root["Terraform root"]
  node_n_main_tf["Main stack<br/>root terraform<br/>[main.tf]"]
  node_n_provider_tf["Providers<br/>provider config<br/>[provider.tf]"]
  node_n_variables_tf["Inputs<br/>variables<br/>[variables.tf]"]
  node_n_outputs_tf["Outputs<br/>[outputs.tf]"]
  node_n_gitlab_tf["GitLab resources<br/>gitlab integration<br/>[gitlab.tf]"]
end

subgraph group_g_modules["Terraform modules"]
  node_n_dns_module[("DNS module<br/>hcloud dns<br/>[main.tf]")]
  node_n_fw_module["Firewall module<br/>hcloud firewall<br/>[main.tf]"]
  node_n_server_module["Server module<br/>hcloud server<br/>[main.tf]"]
  node_n_gitlab_api_module["GitLab API module<br/>gitlab provider<br/>[main.tf]"]
  node_n_proxmox_module["Proxmox module<br/>proxmox vm<br/>[main.tf]"]
end

subgraph group_g_runtime["Runtime targets"]
  node_n_hetzner_api[("Hetzner Cloud<br/>external platform")]
  node_n_gitlab_api[("GitLab API<br/>external platform")]
  node_n_proxmox_api[("Proxmox API<br/>external platform")]
  node_n_gitlab_host["GitLab host<br/>managed service"]
  node_n_runner_host["Runner host<br/>managed service"]
  node_n_dns_zone[("DNS zone<br/>managed dns")]
end

subgraph group_g_support["Operational support"]
  node_n_templates["Cloud-init templates<br/>bootstrap templates"]
  node_n_gitlab_modes_doc["Install modes<br/>docs"]
  node_n_proxmox_doc["Proxmox guide<br/>docs<br/>[proxmox.md]"]
  node_n_operations_doc["Operations<br/>docs<br/>[operations.md]"]
  node_n_workflow["Terraform CI<br/>automation<br/>[terraform.yml]"]
  node_n_gitlab_ci["GitLab CI<br/>automation<br/>[.gitlab-ci.yml]"]
  node_n_makefile["Makefile<br/>ops tooling"]
  node_n_runner_script["Runner checks<br/>script"]
  node_n_backup_example["Backup example<br/>example config"]
end

node_n_main_tf -->|"uses providers"| node_n_provider_tf
node_n_main_tf -->|"reads inputs"| node_n_variables_tf
node_n_main_tf -->|"creates firewall"| node_n_fw_module
node_n_main_tf -->|"creates server"| node_n_server_module
node_n_main_tf -->|"creates DNS"| node_n_dns_module
node_n_main_tf -.->|"optional resources"| node_n_gitlab_tf
node_n_provider_tf -->|"hcloud"| node_n_hetzner_api
node_n_provider_tf -->|"gitlab"| node_n_gitlab_api
node_n_provider_tf -.->|"proxmox"| node_n_proxmox_api
node_n_fw_module -->|"firewall API"| node_n_hetzner_api
node_n_server_module -->|"server API"| node_n_hetzner_api
node_n_dns_module -->|"dns API"| node_n_hetzner_api
node_n_dns_module -->|"publishes records"| node_n_dns_zone
node_n_server_module -->|"hosts GitLab"| node_n_gitlab_host
node_n_templates -->|"bootstraps host"| node_n_gitlab_host
node_n_gitlab_tf -->|"manages org"| node_n_gitlab_api
node_n_gitlab_tf -.->|"targets instance"| node_n_gitlab_host
node_n_proxmox_module -->|"vm API"| node_n_proxmox_api
node_n_proxmox_module -->|"uses cloud-init"| node_n_templates
node_n_proxmox_module -.->|"alt host"| node_n_gitlab_host
node_n_variables_tf -->|"fills templates"| node_n_templates
node_n_gitlab_modes_doc -.->|"documents modes"| node_n_main_tf
node_n_proxmox_doc -.->|"documents platform"| node_n_proxmox_module
node_n_operations_doc -.->|"supports ops"| node_n_makefile
node_n_workflow -.->|"validates"| node_n_main_tf
node_n_gitlab_ci -.->|"runs checks"| node_n_gitlab_tf
node_n_makefile -.->|"mirrors checks"| node_n_workflow
node_n_runner_script -.->|"verifies runner"| node_n_runner_host
node_n_backup_example -.->|"backup flow"| node_n_gitlab_host

click node_n_main_tf "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/main.tf"
click node_n_provider_tf "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/provider.tf"
click node_n_variables_tf "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/variables.tf"
click node_n_outputs_tf "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/outputs.tf"
click node_n_gitlab_tf "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/gitlab.tf"
click node_n_dns_module "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/dns/main.tf"
click node_n_fw_module "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/firewall/main.tf"
click node_n_server_module "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/server/main.tf"
click node_n_gitlab_api_module "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/gitlab-api/main.tf"
click node_n_proxmox_module "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/proxmox/main.tf"
click node_n_templates "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/templates/gitlab-docker-cloud-init.yaml.tpl"
click node_n_gitlab_modes_doc "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/gitlab-install-modes.md"
click node_n_proxmox_doc "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/proxmox.md"
click node_n_operations_doc "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/operations.md"
click node_n_workflow "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/.github/workflows/terraform.yml"
click node_n_gitlab_ci "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/.gitlab-ci.yml"
click node_n_makefile "https://github.com/henryhst/gitlab-terraform-hcloud/tree/main/Makefile"
click node_n_runner_script "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/scripts/check-compose-image-versions.sh"
click node_n_backup_example "https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/examples/gitlab-backup-ci.yml.example"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main_tf,node_n_provider_tf,node_n_variables_tf,node_n_outputs_tf,node_n_gitlab_tf toneBlue
class node_n_dns_module,node_n_fw_module,node_n_server_module,node_n_gitlab_api_module,node_n_proxmox_module toneAmber
class node_n_hetzner_api,node_n_gitlab_api,node_n_proxmox_api,node_n_gitlab_host,node_n_runner_host,node_n_dns_zone toneMint
class node_n_templates,node_n_gitlab_modes_doc,node_n_proxmox_doc,node_n_operations_doc,node_n_workflow,node_n_gitlab_ci,node_n_makefile,node_n_runner_script,node_n_backup_example toneRose
```

## Components

### Terraform root

Top-level orchestration, providers, variables, and entrypoint configuration.

- [Main stack](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/main.tf): root terraform · Primary orchestration entrypoint that wires firewall, server, DNS, and optional GitLab resources. · `terraform/main.tf`
- [Providers](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/provider.tf): provider config · Declares the Hetzner, GitLab, and optional Proxmox provider boundaries. · `terraform/provider.tf`
- [Inputs](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/variables.tf): variables · Defines deployment knobs such as install mode, tokens, and feature flags. · `terraform/variables.tf`
- [Outputs](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/outputs.tf): outputs · Exports selected infrastructure facts from the root stack. · `terraform/outputs.tf`
- [GitLab resources](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/gitlab.tf): gitlab integration · Optional root-level GitLab API resources for groups, projects, bots, and webhooks. · `terraform/gitlab.tf`

### Terraform modules

Reusable infrastructure and integration modules.

- [DNS module](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/dns/main.tf): hcloud dns · Manages the authoritative Hetzner DNS zone and service records. · `terraform/modules/dns/main.tf`
- [Firewall module](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/firewall/main.tf): hcloud firewall · Builds the Hetzner firewall policy used by server and runner hosts. · `terraform/modules/firewall/main.tf`
- [Server module](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/server/main.tf): hcloud server · Provisions the main Hetzner cloud server and exposes its network outputs. · `terraform/modules/server/main.tf`
- [GitLab API module](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/gitlab-api/main.tf): gitlab provider · Creates GitLab-side organization objects and hooks through the GitLab API. · `terraform/modules/gitlab-api/main.tf`
- [Proxmox module](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/modules/proxmox/main.tf): proxmox vm · Provisioning layer for QEMU VMs and cloud-init on Proxmox. · `terraform/modules/proxmox/main.tf`

### Runtime targets

Managed external platforms and services.

- **Hetzner Cloud**: external platform · Target API for servers, firewalls, and DNS management.
- **GitLab API**: external platform · Target API for GitLab organizational resources and webhooks.
- **Proxmox API**: external platform · Target API for VM lifecycle management on Proxmox.
- **GitLab host**: managed service · The deployed GitLab instance, either on Hetzner or Proxmox depending on install mode.
- **Runner host**: managed service · Optional separate CI runner VM or runner process in the compose stack.
- **DNS zone**: managed dns · 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](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/terraform/templates/gitlab-docker-cloud-init.yaml.tpl): bootstrap templates · Templates that bridge Terraform into first-boot Docker, GitLab, and runner setup. · `terraform/templates/gitlab-docker-cloud-init.yaml.tpl`
- [Install modes](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/gitlab-install-modes.md): docs · Describes the GitLab deployment modes and their architecture differences. · `docs/gitlab-install-modes.md`
- [Proxmox guide](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/proxmox.md): docs · Documents the Proxmox target platform and its operational model. · `docs/proxmox.md`
- [Operations](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/operations.md): docs · Operational runbook for managing the infrastructure and services. · `docs/operations.md`
- [Terraform CI](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/.github/workflows/terraform.yml): automation · GitHub Actions validation and formatting pipeline for the Terraform stack. · `.github/workflows/terraform.yml`
- [GitLab CI](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/.gitlab-ci.yml): automation · Repository-side CI path for checks and related maintenance tasks. · `.gitlab-ci.yml`
- [Makefile](https://github.com/henryhst/gitlab-terraform-hcloud/tree/main/Makefile): ops tooling · Local command entrypoint for formatting, validation, and checks. · `Makefile`
- [Runner checks](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/scripts/check-compose-image-versions.sh): script · Operational helper for runner/bootstrap verification. · `scripts/check-compose-image-versions.sh`
- [Backup example](https://github.com/henryhst/gitlab-terraform-hcloud/blob/main/docs/examples/gitlab-backup-ci.yml.example): example config · Example CI configuration used as reference for backup workflows. · `docs/examples/gitlab-backup-ci.yml.example`

## Connections

- 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.