Module mesh_service 

Recipe helpers for stateful services bound exclusively to the Headscale mesh (R040-F16).

Inter-node TCP (Postgres primary↔replica, NATS clusters, etc.) lives on the WireGuard mesh, not on Hetzner public IPs. Each node has a stable 100.64.x.x mesh IP that survives box replacement, so connection strings and pg_hba.conf never need to churn when a CPX-22 is rebuilt.

Standard pattern for a mesh-bound port

ServiceConfig {
    name: "postgres",
    bind_interface: Some("tailscale0"),
    mesh_only: true,
    ...
}

The compose renderer emits network_mode: "host" for such a service. Pair it with the ufw rules from ufw_rules_for_mesh_port (applied by the yubaba’s POST /compose via the firewall_cmds field) and the pg_hba snippet from pg_hba_snippet (injected into the Postgres container via a mounted config volume or env).

First-boot POSTGRES_LISTEN_ADDRESSES

Postgres must bind to the node’s tailscale mesh IP, not 0.0.0.0. Since the IP is only known at boot time, cloud-init or a systemd ExecStartPre can resolve it:

# cloud-init write_files
- path: /etc/yah-cloud/mesh-ip.env
  content: ""   # overwritten by runcmd below

runcmd:
  - sh -c 'echo "POSTGRES_LISTEN_ADDRESSES=$(tailscale ip --4)" > /etc/yah-cloud/mesh-ip.env'

Then reference env_file: [/etc/yah-cloud/mesh-ip.env] in the compose service block. The compose renderer sets this automatically when bind_interface is set on a service that exposes port 5432.

Constants

MESH_IP_ENV_FILE

The env file path written by cloud-init that holds the node’s mesh IP. Referenced as env_file in compose when bind_interface is set.

MESH_SUBNET

Tailscale/Headscale CGNAT subnet — all mesh peers have addresses in this range.

TAILSCALE_IFACE

The network interface name that carries Tailscale/Headscale mesh traffic.

Functions

mesh_ip_env_runcmd

Build the cloud-init runcmd lines that write the mesh IP env file at first boot. Append these to a machine’s mirror.yml runcmd block to make POSTGRES_LISTEN_ADDRESSES available to the compose stack via env_file: [{MESH_IP_ENV_FILE}].

pg_hba_snippet

Generate a pg_hba.conf block that allows connections from any mesh peer.

ufw_rules_for_mesh_port

Generate the ufw commands needed to make port port reachable only on interface iface (typically tailscale0), blocking all other ingress.