From 109d55493f688e35cd5bee6a61470cd92b99cc86 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Mon, 2 Nov 2026 23:31:06 -0500 Subject: [PATCH 1/2] refactor(tailscale): centralize strictly in all/tailscale.yml and sops, eliminating muscle host-vars --- .secrets.baseline | 8 +-- inventory/group_vars/all/images.yml | 6 --- inventory/group_vars/all/main.yml | 23 --------- .../group_vars/all/secrets.sops.yml.example | 5 ++ inventory/group_vars/all/tailscale.yml | 49 ++++++++++++++++++ inventory/group_vars/muscle/tailscale.yml | 26 ---------- roles/L2_compliance/defaults/main.yml | 1 + .../general/defaults/tailscale.yml | 51 +++---------------- .../tailscale/tailscale-acls.json.j2 | 9 ++-- 9 files changed, 72 insertions(+), 106 deletions(-) create mode 100644 inventory/group_vars/all/tailscale.yml delete mode 100644 inventory/group_vars/muscle/tailscale.yml diff --git a/.secrets.baseline b/.secrets.baseline index ee2c560..085c5b6 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -133,21 +133,21 @@ "filename": "inventory/group_vars/all/secrets.sops.yml.example", "hashed_secret": "14df3e4cc9d832ea838e8b8efff1f4a38bda61a2", "is_verified": false, - "line_number": 188 + "line_number": 161 }, { "type": "Secret Keyword", "filename": "inventory/group_vars/all/secrets.sops.yml.example", "hashed_secret": "75f0d7d06d2944c3751cc0335f19bd7e7929e93b", "is_verified": false, - "line_number": 206 + "line_number": 179 }, { "type": "Secret Keyword", "filename": "inventory/group_vars/all/secrets.sops.yml.example", "hashed_secret": "2d45c0f22fd4b1b5fc62d8ecdd21633993fdb4fb", "is_verified": false, - "line_number": 263 + "line_number": 236 } ], "roles/L6_runtime/backup/defaults/main.yml": [ @@ -167,5 +167,5 @@ } ] }, - "generated_at": "2026-10-09T02:31:26Z" + "generated_at": "2026-11-03T03:57:50Z" } diff --git a/inventory/group_vars/all/images.yml b/inventory/group_vars/all/images.yml index 1fa47b3..eabd797 100644 --- a/inventory/group_vars/all/images.yml +++ b/inventory/group_vars/all/images.yml @@ -70,12 +70,6 @@ docker_version_map: caddy_user_uid: 1337 caddy_user_gid: 1337 -# ----------------------------------------------------------------------------- -# NETWORK CONFIGURATION (Tailscale Zero Trust) -# ----------------------------------------------------------------------------- -tailscale_mtu: 1280 # MTU for Tailscale -tailscale_metrics_port: 5252 # Tailscale metrics port - # ----------------------------------------------------------------------------- # ANSIBLE RUNTIME # ----------------------------------------------------------------------------- diff --git a/inventory/group_vars/all/main.yml b/inventory/group_vars/all/main.yml index 2c67ede..9838be0 100644 --- a/inventory/group_vars/all/main.yml +++ b/inventory/group_vars/all/main.yml @@ -3,11 +3,6 @@ platform_name: "Developmi Hardened" platform_version: "v7.0.0-dev" -# Global network defaults -# Source of truth for the private management overlay used by non-bootstrap playbooks. -# Set this if you use Headscale or another VPN subnet for remote administration. -tailscale_subnet: "100.64.0.0/10" - # Shared external Docker network (L3 observability stack, L4 caddy, L6 portainer) shared_network_name: "public_net" @@ -29,9 +24,6 @@ observability_cadvisor_port: 18080 # Keep dual-stack filtering enabled by default unless your environment is IPv4-only. ufw_enable_ipv6: true -# Control persistent Tailscale webclient exposure (:5252). -tailscale_enable_webclient: false - # Ingress deployment defaults (safe for all hosts) ingress_compose_pull_policy: "missing" ingress_compose_recreate_policy: "auto" @@ -172,10 +164,6 @@ bootstrap_mode: false # do NOT use it as the controller_ip. controller_ip: "{{ (ansible_facts['ansible_env']['SSH_CLIENT'] | default('')).split(' ')[0] | default('undefined') }}" -# l2_tailscale_subnet_router enables IP forwarding for nodes that -# act as Tailscale subnet routers. Default false (no subnet routing). -l2_tailscale_subnet_router: false - # ============================================================================= # L4 NETWORKING / EDGE # ============================================================================= @@ -238,17 +226,6 @@ backup_repo_base_url: >- # Set to true to deploy Portainer BE as a stack on top of Engine. enable_portainer: false -# ============================================================================== -# Tailscale Mesh VPN - Installation Variables -# ============================================================================== -# Version: v1.102.2 (latest verified) -# Docs: https://tailscale.com/changelog -tailscale_version: "1.102.2" -tailscale_gpg_key_url_debian: "https://pkgs.tailscale.com/stable/debian/bookworm.noarmor.gpg" -tailscale_gpg_key_url_ubuntu: "https://pkgs.tailscale.com/stable/ubuntu/jammy.noarmor.gpg" -tailscale_keyring_path: "/usr/share/keyrings/tailscale-archive-keyring.gpg" -tailscale_repo_list_path: "/etc/apt/sources.list.d/tailscale.list" - # /proc hidepid=2 reader group (node_exporter, etc.) # GID is auto-assigned by Ansible group task, then resolved via getent. # No hardcoded GID - value below is the group name only. diff --git a/inventory/group_vars/all/secrets.sops.yml.example b/inventory/group_vars/all/secrets.sops.yml.example index fcbed70..ffce842 100644 --- a/inventory/group_vars/all/secrets.sops.yml.example +++ b/inventory/group_vars/all/secrets.sops.yml.example @@ -63,6 +63,11 @@ tailscale_acl_automation_sources: ["admin@example.invalid"] # Used by roles/L2_compliance/general/templates/tailscale/tailscale-acls.json.j2:8. tailscale_acl_admin_ui_sources: ["admin@example.invalid"] +# Sources allowed to reach caddy-waf-ui via Tailscale Serve on muscle nodes (port 8443). +# When omitted, falls back to tailscale_acl_operator_sources (autogroup:admin). +# Used by roles/L2_compliance/general/templates/tailscale/tailscale-acls.json.j2:46. +tailscale_acl_serve_sources: ["admin@example.invalid"] + # Sources that get emergency SSH access (same rule as automation, # independent list so it can be kept empty). # Used by roles/L2_compliance/general/templates/tailscale/tailscale-acls.json.j2:7. diff --git a/inventory/group_vars/all/tailscale.yml b/inventory/group_vars/all/tailscale.yml new file mode 100644 index 0000000..9e71e2b --- /dev/null +++ b/inventory/group_vars/all/tailscale.yml @@ -0,0 +1,49 @@ +--- +# ============================================================================== +# TAILSCALE PLATFORM CONFIGURATION (Declarative & Non-Sensitive) +# ============================================================================== +# Central SSOT for all non-sensitive Tailscale settings: toolchain, network mesh, +# telemetry metrics, node attributes, service ports, and ACL policy switches. +# +# Privacy & Secrets Contract: +# All identities, authorized operator emails, private tailnet domains, and OAuth +# credentials MUST reside in inventory/group_vars/all/secrets.sops.yml. +# NEVER place emails, tokens, or PII in this file. + +# --- Toolchain & System Packages --- +# Docs: https://tailscale.com/changelog +tailscale_version: "1.102.2" +tailscale_gpg_key_url_debian: "https://pkgs.tailscale.com/stable/debian/bookworm.noarmor.gpg" +tailscale_gpg_key_url_ubuntu: "https://pkgs.tailscale.com/stable/ubuntu/jammy.noarmor.gpg" +tailscale_keyring_path: "/usr/share/keyrings/tailscale-archive-keyring.gpg" +tailscale_repo_list_path: "/etc/apt/sources.list.d/tailscale.list" + +# --- Networking & Mesh Defaults --- +tailscale_subnet: "100.64.0.0/10" +tailscale_mtu: 1280 +tailscale_metrics_port: 5252 +tailscale_enable_webclient: false +l2_tailscale_subnet_router: false + +# --- Global Tailnet ACL Policy & Capabilities --- +# The `https` nodeattr is required by the tailnet policy for Tailscale Serve +# to obtain a MagicDNS certificate. Rendered into the ACL policy file by +# the L2 tailscale role template (tailscale-acls.json.j2). +# +# FORMAT: Mirrors Tailscale policy-file `nodeAttrs` section natively: +# a list of {target: [...], attr: [...]} objects. +tailscale_node_attrs: + - target: ["tag:muscle"] + attr: ["https"] + +# Global ACL rule: allow operator sources to reach caddy-waf-ui serve on muscle nodes. +# Controls whether the rule tag:muscle: is rendered into the tailnet ACL policy. +tailscale_acl_serve_enabled: true + +# --- Tailscale Serve Host Proxy Topology --- +# Automatically enabled on nodes in the muscle group (where caddy-waf-ui runs) +tailscale_serve_enabled: "{{ 'muscle' in group_names }}" +# Local target to proxy: the loopback-only publish of caddy-waf-ui (127.0.0.1:8080) +tailscale_serve_target: "8080" +# Tailnet-facing HTTPS port. NOT 443: Caddy data plane binds 0.0.0.0:443 on host +tailscale_serve_port: "8443" diff --git a/inventory/group_vars/muscle/tailscale.yml b/inventory/group_vars/muscle/tailscale.yml deleted file mode 100644 index 42b1c26..0000000 --- a/inventory/group_vars/muscle/tailscale.yml +++ /dev/null @@ -1,26 +0,0 @@ ---- -# ============================================================================== -# Tailscale — caddy-waf-ui control-plane access (muscle nodes) -# ============================================================================== -# The `https` nodeattr is required by the tailnet policy for Tailscale Serve -# to obtain a MagicDNS certificate. It is rendered into the ACL policy file by -# the L2 tailscale role template (tailscale-acls.json.j2). -# -# FORMAT: tailscale_node_attrs mirrors the Tailscale policy-file `nodeAttrs` -# section natively — a list of {target: [...], attr: [...]} objects. A plain -# list of strings (e.g. ["https"]) is INVALID and the ACL API rejects it with -# HTTP 400 Bad Request. Ref: https://tailscale.com/docs/reference/syntax/policy-file -# -# NOTE: the L2 role deploy order matters — land the nodeattr in the policy -# FIRST (one deploy), then enable Serve (second deploy). The `tailscale serve` -# task below only starts when tailscale_serve_enabled is true. - -tailscale_node_attrs: - - target: ["tag:muscle"] - attr: ["https"] - -# Expose the loopback-only caddy-waf-ui (127.0.0.1:8080) to the tailnet at -# https://muscle-1..ts.net:8443. The UI container binding stays -# loopback-only (spec WAF-UI-002); Serve proxies from the host. HTTPS is -# mandatory (UI session cookie is Secure). ACLs of the tailnet still apply. -tailscale_serve_enabled: true diff --git a/roles/L2_compliance/defaults/main.yml b/roles/L2_compliance/defaults/main.yml index 5d42b3a..2b4f37b 100644 --- a/roles/L2_compliance/defaults/main.yml +++ b/roles/L2_compliance/defaults/main.yml @@ -14,6 +14,7 @@ l2_lynis_enabled: false # Lynis compliance audit - opt-in (NIST AU-12) user_hardening_users: [] # Tailscale Serve defaults +tailscale_acl_serve_enabled: false tailscale_serve_enabled: false tailscale_serve_target: "8080" tailscale_serve_port: "8443" diff --git a/roles/L2_compliance/general/defaults/tailscale.yml b/roles/L2_compliance/general/defaults/tailscale.yml index 353b964..73126c6 100644 --- a/roles/L2_compliance/general/defaults/tailscale.yml +++ b/roles/L2_compliance/general/defaults/tailscale.yml @@ -1,54 +1,19 @@ --- # ============================================================================== -# Tailscale Client Role - Default Variables +# Tailscale Client Role - Default Safe Fallbacks # ============================================================================== -# NOTE: Ansible only auto-loads `defaults/main.yml` for a role; this file is the -# DOCUMENTED safe-defaults reference for all tailscale vars. Tasks consume them -# with inline `| default(...)` so the role stays functional for adopters who -# never set these vars (see tasks/tailscale/main.yml and the ACL template). +# Invariant role defaults. Topology, ports, nodeAttrs, and global tailnet policies +# are configured in inventory/group_vars/all/tailscale.yml. Sensitive identities +# and credentials reside in inventory/group_vars/all/secrets.sops.yml. -# Set to true on hosts where Tailscale auth is handled manually -# (e.g., local workstation devices). When true, the auth key -# validation guard is skipped and node enrollment is deferred. +# Manual authentication bypass (e.g., local workstation devices) tailscale_manual_auth: false -# Tailscale node attributes for ACL policy. -# Ref: https://tailscale.com/docs/reference/syntax/policy-file#nodeattrs -# FORMAT: native policy-file structure — a list of {target: [...], attr: [...]} -# objects. A plain list of strings (e.g. ["https"]) is INVALID and the Tailscale -# ACL API rejects it with HTTP 400 Bad Request. -# Example (https enables MagicDNS certs for `tailscale serve`): -# tailscale_node_attrs: -# - target: ["tag:muscle"] -# attr: ["https"] +# Fallback node attributes (empty by default) tailscale_node_attrs: [] -# Tailscale Serve — expose a local TCP service to the tailnet via HTTPS -# (MagicDNS certificate). Tailnet-only (never Funnel). ACLs of the tailnet -# still apply to the serve listener. Served over HTTPS only (the caddy-waf-ui -# session cookie is Secure and does not work over plain HTTP), so the `https` -# nodeattr must be present in the tailnet policy for this node. -# -# IMPORTANT — per-node activation (never in defaults): -# 1. Set `tailscale_node_attrs: ["https"]` in the node's group_vars/host_vars -# (NOT here). The L2 tailscale role renders it into the ACL policy file -# (see templates/tailscale/tailscale-acls.json.j2). -# 2. Deploy the L2 tailscale role once so the nodeattr lands in the policy. -# 3. Then set `tailscale_serve_enabled: true` for that node and re-deploy. -# Used to reach the caddy-waf-ui on nodes that run it: the UI container -# binding stays loopback-only (127.0.0.1:8080:8080); serve proxies from -# the host. Disabled by default — opt-in per node. +# Fallback serve flags (disabled by default) +tailscale_acl_serve_enabled: false tailscale_serve_enabled: false -# Local target to proxy: the loopback-only publish of the caddy-waf-ui. tailscale_serve_target: "8080" -# Tailnet-facing HTTPS port. NOT 443: the Caddy data plane already binds -# 0.0.0.0:443 on the host (conflict on tailscale0). tailscale_serve_port: "8443" - -# ACL sources allowed to reach the serve listener -# (tag:muscle:). Deliberately NOT defined here: -# the ACL template falls back to acl_operator_sources (autogroup:admin) when -# this var is absent, so the rule renders whenever tailscale_serve_enabled -# is true. Set it per tailnet only to narrow the audience, e.g.: -# tailscale_acl_serve_sources: ["user@example.com"] -# tailscale_acl_serve_sources_extra: ["user2@example.com"] diff --git a/roles/L2_compliance/general/templates/tailscale/tailscale-acls.json.j2 b/roles/L2_compliance/general/templates/tailscale/tailscale-acls.json.j2 index 39b13dd..330354b 100644 --- a/roles/L2_compliance/general/templates/tailscale/tailscale-acls.json.j2 +++ b/roles/L2_compliance/general/templates/tailscale/tailscale-acls.json.j2 @@ -40,10 +40,11 @@ }) %} {# Tailscale Serve: operator sources reach the serve listener on muscle - (caddy-waf-ui control plane). Rendered only when serve is enabled; the - host firewall (ufw/nftables) also opens this port on tailscale0. #} -{% if tailscale_serve_enabled | default(false) %} -{% set acl_serve_sources = ((tailscale_acl_serve_sources | default(acl_operator_sources)) + (tailscale_acl_serve_sources_extra | default([]))) | unique %} + (caddy-waf-ui control plane). Rendered only when global ACL serve policy + is enabled; the host firewall (ufw/nftables) opens this port on tailscale0 + locally when tailscale_serve_enabled is true on the node. #} +{% if (tailscale_acl_serve_enabled | default(tailscale_serve_enabled | default(false))) | bool %} +{% set acl_serve_sources = ((tailscale_acl_serve_sources | default(acl_admin_ui_sources)) + (tailscale_acl_serve_sources_extra | default([]))) | unique %} {% if acl_serve_sources | length > 0 %} {% set _ = acl_rules.append({ 'action': 'accept', From 51ce8a1f9f3710bfd06ad122961d218ba4f87a06 Mon Sep 17 00:00:00 2001 From: Miguel Lozano Date: Mon, 2 Nov 2026 23:31:56 -0500 Subject: [PATCH 2/2] docs(runbook): document automated tailscale serve activation via group membership --- docs/operations/OPERATIONS_RUNBOOK.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/operations/OPERATIONS_RUNBOOK.md b/docs/operations/OPERATIONS_RUNBOOK.md index d586776..256ff9c 100644 --- a/docs/operations/OPERATIONS_RUNBOOK.md +++ b/docs/operations/OPERATIONS_RUNBOOK.md @@ -659,23 +659,32 @@ ssh -L 8080:127.0.0.1:8080 user@ **Access via Tailscale Serve:** -The UI can also be exposed to the tailnet via `tailscale serve` (HTTPS with a MagicDNS certificate, tailnet-only, never Funnel). Tailnet ACLs still apply to the serve listener: when `tailscale_serve_enabled` is true, the L2 ACL template renders an accept rule (operator sources → `tag:muscle:`) and the host firewall (ufw/nftables) opens `` on `tailscale0` — both automatically. +The UI can also be exposed to the tailnet via `tailscale serve` (HTTPS with a MagicDNS certificate, tailnet-only, never Funnel). Tailnet ACLs still apply to the serve listener: when `tailscale_acl_serve_enabled` is true in global tailnet policy (`inventory/group_vars/all/tailscale.yml`), the L2 ACL template renders an accept rule (operator sources → `tag:muscle:`). When `tailscale_serve_enabled` is true on the node, the host firewall (ufw/nftables) opens `` on `tailscale0` and activates Serve — both automatically. -**Prerequisites (order matters):** +**Prerequisites (2-center canonical partition: Declarative Public vs SOPS Encrypted):** -1. Set `tailscale_node_attrs` in the **node's** group_vars/host_vars (e.g. `inventory/group_vars/muscle/tailscale.yml`) — never in role defaults. The L2 tailscale role renders it into the ACL policy file (`tailscale-acls.json.j2`). **Format is the native policy-file structure — a list of `{target: [...], attr: [...]}` objects** (a plain string list like `["https"]` is invalid and the ACL API rejects it with HTTP 400): +1. Declare global tailnet capabilities and ports in `inventory/group_vars/all/tailscale.yml` (declarative, evaluated controller-side during L2 hardening): ```yaml tailscale_node_attrs: - target: ["tag:muscle"] attr: ["https"] + tailscale_acl_serve_enabled: true + tailscale_serve_port: "8443" + tailscale_serve_target: "8080" ``` -2. Deploy the L2 tailscale role for that node once so the nodeattr lands in the policy (e.g. `make deploy-hardening ANSIBLE_LIMIT=`). -3. HTTPS must be enabled in the tailnet. Tailscale MFA recommended on the tailnet account. -4. Tailnet ACLs apply to the serve listener. The UI session cookie is `Secure`, so plain-HTTP serve is not supported — HTTPS is mandatory. +2. Declare authorized operator identities in `inventory/group_vars/all/secrets.sops.yml` (encrypted, protects operator PII from public repo scraping): + ```yaml + tailscale_acl_serve_sources: + - "admin@example.invalid" + ``` + _(Note: If `tailscale_acl_serve_sources` is omitted, it falls back automatically to `tailscale_acl_admin_ui_sources`)._ +3. Deploy L2 hardening once so the nodeattr and ACL rule land in the policy (e.g. `make deploy-hardening`). +4. HTTPS must be enabled in the tailnet. Tailscale MFA recommended on the tailnet account. +5. Tailnet ACLs apply to the serve listener. The UI session cookie is `Secure`, so plain-HTTP serve is not supported — HTTPS is mandatory. -**Enable per node:** +**Activation:** -- Set `tailscale_serve_enabled: true` (optionally override `tailscale_serve_port`) in the node's vars, then re-run the L2 deploy for that host. Only enable AFTER the `https` nodeattr is in the policy (prereq step 2) — otherwise `tailscale serve --https` cannot obtain a certificate. +Tailscale Serve activates automatically on nodes belonging to the `muscle` inventory group (where `caddy-waf-ui` runs) via `tailscale_serve_enabled: "{{ 'muscle' in group_names }}"` declared in `inventory/group_vars/all/tailscale.yml`. No per-node file or manual override is required. Deploy L2 hardening once the tailnet ACL policy is updated. **Access URL pattern:**