Entity: Tailscale (Mesh Networking)

This page is the repository hub for the Tailscale mesh networking layer.

Overview

Tailscale provides the zero-trust WireGuard mesh that connects operator environments, the Talos cluster, and the Hetzner Vault runtime. It replaces public exposure and ad-hoc VPNs with identity-based, tag-controlled access.

Network Segments

Tailscale connects three distinct domains:

DomainNodesTags
OperatorTazPod container (hostnet+TUN default, userspace daemon fallback)tag:tazpod
ClusterTalos control-plane + worker nodes (Talos System Extension)tag:tazlab-k8s
VaultHetzner VPS running Vaulttag:tazlab-vault, tag:vault-api

Important Vault Hostname Evolution

The Vault runtime has converged through several hostname models:

PhaseHostnameStatus
Originallushycorp-vm.ts.tazlab.netSuperseded
Custom aliaslushycorp-api.ts.tazlab.netDebt (non-Tailscale-owned)
Current (Phase 1)lushycorp-vault (tailnet), lushycorp-vault.magellanic-gondola.ts.net (MagicDNS)Operational

TD-020 tracks the custom alias as architecture debt.

Management Model

Tailscale is managed as infrastructure-as-code via the Tailscale Terraform provider in ephemeral-castle/tailscale/:

ResourcePurpose
main.tfACL policy, tailnet settings, OAuth clients
acl.jsonTag ownership and ACL rules
setup.shInfrastructure-side initial setup (bootstrap OAuth + operator OAuth)

Kubernetes Operator (Deployed 2026-05-08)

The Tailscale Kubernetes Operator was deployed via CRISP project 10-operator-dns-resolution (part of the 07-tailscale-operator-deployment split). It deploys via 3-layer Flux DAG (infrastructure-tailscale → infrastructure-operators-tailscale → infrastructure-tailscale-dns) in namespace tailscale using a dedicated OAuth client k8s_operator (tag tag:k8s-operator, scopes: devices, auth_keys, services).

DNS resolution: The Operator’s DNSConfig CR creates a nameserver (app=nameserver) in namespace tailscale. CoreDNS forwards ts.net queries to the static Service nameserver-static (ClusterIP 10.96.0.101). The hostNetwork CoreDNS relay DaemonSet was deprecated after 15-tailscale-operator-hardening.

Service Exposure (CRISP 20-tailscale-service-exposure, Completed 2026-05-24): The operator now exposes 6 internal services via Tailscale Ingress and LoadBalancer, replacing MetalLB and public Traefik ingress. See Service Exposure.

Operator-side daemon: inside TazPod, tools/tailscale/start.sh auto‑detects /dev/net/tun and uses kernel‑native TUN mode (full DNS + routing) with userspace‑networking fallback. The .bashrc auto‑starts it on shell entry via singleton check (socket‑based). Log: logs/tailscaled.log, Socket: state/tailscaled.sock. See bashrc reference and start.sh reference.

Quick Facts

PropertyValue
ProviderTailscale Terraform provider
ACL modeltag-based, managed as acl.json
OAuth clientstazlab-bootstrap (scopes: auth_keys, devices); k8s_operator (scopes: devices, auth_keys, services, tag: tag:k8s-operator)
Key duration180 days
Auth methodOAuth client → short-lived auth keys
Operator daemonHostnet+TUN mode inside TazPod (default); .bashrc auto-start with setsid
K8s OperatorDeployed (CRISP 10-operator-dns-resolution): 3-layer Flux DAG, HelmRelease in ns tailscale, DNSConfig CR, CoreDNS forward ts.net → 10.96.0.101
Service Exposure6 services migrated (CRISP 20-tailscale-service-exposure): Ingress + LoadBalancer via Operator
Cluster integrationTalos System Extension
Tailnetmagellanic-gondola.ts.net
HTTPSEnabled (Let’s Encrypt auto-provisioned certificates via tailnet API)

Known Issues

  • TD-006: Hotspot IPv6 unverified — IPv6-only validation can produce false negatives
  • TD-025: Wildcard TLS cert (*.tazlab.net) expires 2026-07-30 — no auto-renewal (HTTP01 only, DNS01 pending)

See Also