Digitalboard/docs
6
1
Fork 0
Code Pull requests 1 Activity Actions
docs/architecture/variables.md
Simon Bärlocher 345cf4b319
docs: add architecture section and overhaul top-level README 
- Move Simon's architecture documentation into architecture/
  (setup, variables, topology, dns, deploy, security, operations
  plus index and glossary). All cross-repo references point at
  https://git.digitalboard.ch/Digitalboard/{reference-ansible,dns-zones}
  via absolute URLs so the docs remain navigable from any context.
- Rewrite README.md as a documentation hub: introduction, platform
  Mermaid overview, comparison of the three repos
  (docs / digitalboard.core / reference-ansible) and a full table of
  contents covering architecture, contributing, infrastructure,
  keycloak, ms-entra and troubleshooting.

Addresses the open items from the WKS PoC review (2026-05-26):
docs README begrüssungstext + Übersichtsgrafik + Verlinkung der
beiden anderen Repos, sowie das Verschieben der Architektur-Doku.
2026-05-28 14:25:27 +02:00

2.9 KiB
Raw Blame History

Variables — hierarchy and cheatsheet

← Back to Architecture index

3. Variable hierarchy

Ansible merges variables from multiple sources. Simplified model for this repo (see the Ansible docs for the full precedence rules):

flowchart LR
    classDef role fill:#fef3c7,stroke:#92400e,color:#000
    classDef group fill:#dbeafe,stroke:#1e40af,color:#000
    classDef host fill:#dcfce7,stroke:#166534,color:#000
    classDef vault fill:#fee2e2,stroke:#991b1b,color:#000

    R["<b>role defaults</b><br/>(lowest precedence)<br/>collections/.../roles/&lt;r&gt;/defaults/main.yml"]:::role
    GA["<b>group_vars/all/</b><br/>vault.yml, docker.yml"]:::group
    GG["<b>group_vars/&lt;group&gt;/</b><br/>traefik_servers/, backend_servers/<br/>(parallel groups, merged via<br/>ansible_group_priority)"]:::group
    HV["<b>host_vars/&lt;host&gt;/</b><br/>(highest of the three inventory sources)"]:::host
    BAO["<b>OpenBao</b><br/>lookup at runtime"]:::vault

    R --> |"&lt;overridden by&gt;"| GA
    GA --> |"&lt;overridden by&gt;"| GG
    GG --> |"&lt;overridden by&gt;"| HV
    HV -.community.hashi_vault.-> BAO
    GG -.community.hashi_vault.-> BAO

Key properties:

  • Multiple group_vars/<group>/ are parallel, not hierarchically nested. traefik_servers and backend_servers are merged by ansible_group_priority (default 1); on conflict the alphabetically-later group name wins.
  • host_vars/<host>/ beats any group.
  • host_vars/reverseproxy/traefik.yml: traefik_mode: dmz therefore overrides the default from group_vars/backend_servers/ — and only because reverseproxy is not a member of backend_servers in the first place (otherwise the override wouldn't even be needed).

Bao lookups are not a precedence layer but values inside any variable source. See security.md for the pattern.

9. Variable cheatsheet

Variable Where in demo-gymburgdorf/ Why
vault_addr, vault_mount group_vars/all/vault.yml Bao endpoint applies site-wide
docker_registry_mirrors group_vars/all/docker.yml Pulls from mirror on all hosts
traefik_acme_*, traefik_use_ssl, traefik_cert_mode group_vars/traefik_servers/traefik.yml Applies to every Traefik instance (dmz + backend)
traefik_mode: backend group_vars/backend_servers/traefik.yml Default for app + storage
traefik_mode: dmz host_vars/reverseproxy/traefik.yml Host-specific override
traefik_dmz_exposed_services host_vars/reverseproxy/ DMZ backend list — only meaningful here
nextcloud_*, authentik_*, collabora_*, drawio_* host_vars/application/<service>.yml Service runs on application
garage_* host_vars/storage/garage.yml Service runs on storage
Secrets (passwords, tokens, keys) inline variable using lookup('community.hashi_vault.hashi_vault', …) Single source of truth via Bao