Skip to main content

Headscale Multi-Tenant Transformation: Full Isolation for ACL, Routes, DNS, and More

· 2 min read
OwnDing
Larktun Contributor

This post shows practical outcomes of transforming single-instance headscale into a multi-tenant model with isolation across tailnet, ACL, routes, DNS, CLI operations, and relay strategy.

Original post: headscale多租户改造，ACL、路由、DNS等全隔离

Transformation Goals​

Headscale is originally single-instance and effectively single-tailnet by default. Multi-tenant support requires strict per-tenant isolation for:

  • tailnet address spaces
  • ACL policies
  • route definitions
  • MagicDNS namespaces
  • CLI management flow
  • relay server strategy

Key Points​

Tailnet​

  • Each tenant has an independent tailnet.
  • Default pool 10.64.0.0/10 can remain, or be customized (for example 192.168.6.0/24).
  • A built-in default tenant keeps backward-compatible behavior.

ACL and Routes​

  • ACL policies are fully tenant-scoped.
  • Route configs are tenant-scoped as well.

MagicDNS​

  • FQDN pattern: hostname.<tenant_key>.<dns.base_domain>.
  • The default tenant uses default as subdomain.

CLI​

  • CLI commands add tenant targeting (for example -t).

Relay Servers​

  • Tenants can share relay infra.
  • Or each tenant can use dedicated relay nodes for stronger isolation.

Example Screenshots​

users with tenant nodes overview nodes with tenant

This article is mirrored on the Larktun blog. For source updates and original context, refer to: headscale多租户改造，ACL、路由、DNS等全隔离