Tailscale Integration with Management Network #2928

tvarohohlavy · 2025-11-11T00:07:49Z

Tailscale VPN Integration with MagicDNS Support

Overview

This PR adds native Tailscale VPN integration to containerlab, enabling secure remote access to lab management networks from anywhere. The integration includes optional DNS server support with intelligent DNS doctoring for seamless name resolution via Tailscale's MagicDNS feature.

Features

🔐 Tailscale VPN Integration

Automatic deployment of Tailscale container as lab infrastructure
Route advertisement of management network (IPv4/IPv6) to Tailscale network
Flexible configuration with sensible defaults
Lifecycle management - Tailscale container created/destroyed with lab
Infrastructure labeling - Generic clab-is-infrastructure label for extensibility

🌐 DNS Services

CoreDNS for authoritative lab DNS resolution (A and AAAA records)
Python DNS Proxy with location-aware DNS doctoring:
- Tailscale clients automatically receive NAT-translated IPs
- Local management network clients receive original IPs
- Automatic detection based on client source address
Dynamic DNS records - Nodes automatically registered as <node-name>.<lab-name>.clab
Split DNS ready - Integrates with Tailscale MagicDNS for seamless resolution
Configurable - Custom domain suffix and CoreDNS version
Auto-updates - DNS records populated after node deployment

🛠️ Advanced Features

1:1 NAT support - Advertise different subnet with bidirectional mapping using iptables NETMAP
DNS Doctoring - Automatic IP translation in DNS responses when NAT is enabled
Configurable image - Pin specific Tailscale version
ACL tags - Support for Tailscale tag-based access control
Health checks - Container health monitoring
Custom IP addressing - Override automatic IP assignment

Configuration

Basic Setup

name: my-lab
mgmt:
  tailscale:
    authkey: "tskey-auth-xxxxx"

With MagicDNS

name: my-lab
mgmt:
  tailscale:
    authkey: "tskey-auth-xxxxx"
    dns:
      enabled: true
      domain: "my-lab.clab"     # optional, defaults to "<lab-name>.clab"
      coredns-version: "1.13.1" # optional

Advanced Configuration with NAT and DNS Doctoring

mgmt:
  ipv4-subnet: 172.20.20.0/24
  tailscale:
    enabled: true
    authkey: "tskey-auth-xxxxx"
    image: "tailscale/tailscale:v1.56.0"
    ipv4-address: "172.20.20.254"
    tags:
      - "lab-access"
    snat: true
    ephemeral-state: true
    accept-routes: false
    accept-dns: false
    one-to-one-nat: "10.0.0.0/24"
    dns:
      enabled: true
      domain: "lab.example.com"
      coredns-version: "1.13.1"

Architecture

DNS Integration

Post-deployment DNS update - UpdateInfrastructureDNS() called after all nodes deployed
CoreDNS installation - Downloaded and configured automatically in Tailscale container
Dynamic record generation - Extracts node info (shortname, IPs) and creates DNS records
Split DNS workflow - Tailscale MagicDNS → CoreDNS → containerlab nodes

DNS Architecture with Doctoring

Tailscale Clients (port 53)
    ↓
Python DNS Proxy (port 53)
    ↓ [rewrites IPs: mgmt subnet → NAT subnet]
    ↓ [based on client source address]
    ↓
CoreDNS (port 5353)
    ↓ [serves from /etc/coredns/hosts]
    ↓
Docker DNS (127.0.0.11) [fallback]

How it works:

CoreDNS serves authoritative DNS for lab domain with real management IPs
When NAT is enabled, Python DNS proxy intercepts queries
Proxy detects client source: Tailscale network vs. management network
For Tailscale clients: translates management IPs → NAT IPs in responses
For local clients: passes through unchanged

Files Changed

Core Implementation

types/types.go - Added TailscaleConfig and TailscaleDNSConfig structs
constants/labels.go - Added IsInfrastructure label constant
tailscale.go - Complete Tailscale lifecycle management
clab/clab.go - Added DeployInfrastructure(), DestroyInfrastructure(), UpdateInfrastructureDNS()
clab/deploy.go - Integrated infrastructure deployment and DNS updates
core/destroy.go - Integrated infrastructure cleanup
clab/config.go - Generic infrastructure container detection
utils/ip.go - Added LastHostIPInSubnet() helper

Script Files (NEW)

runtime/docker/scripts/nat-setup.sh - NAT configuration with iptables NETMAP
runtime/docker/scripts/dns-proxy.py - Python DNS proxy with intelligent doctoring
runtime/docker/scripts/coredns-install.sh - Optimized CoreDNS installation
Corefile.tmpl - CoreDNS configuration template
runtime/docker/scripts/README.md - Comprehensive script documentation

Documentation

docs/manual/network.md - Brief Tailscale introduction with reference
docs/manual/tailscale.md - Comprehensive guide (NEW)
mkdocs.yml - Added Tailscale VPN navigation entry

Usage Examples

Remote Lab Access

# Deploy lab with Tailscale
sudo clab deploy -t topology.yml

# Accept routes in Tailscale admin console
# Access nodes from anywhere
ssh [email protected]

With MagicDNS

# Deploy lab with DNS enabled
sudo clab deploy -t topology.yml

# Configure split DNS in Tailscale admin console
# Access nodes by name from anywhere
ssh [email protected]
ping switch1.my-lab.clab

Testing

Tested with:

✅ Basic Tailscale deployment
✅ Route advertisement (IPv4/IPv6)
✅ 1:1 NAT functionality
✅ DNS server installation
✅ DNS record generation
✅ DNS Doctoring for NAT + DNS combination
✅ MagicDNS split DNS resolution
✅ Location-aware DNS responses (Tailscale vs local clients)
✅ Container lifecycle management
✅ Multiple labs with different configurations

Known Limitations

PTR (Reverse DNS) records are not currently supported - This is documented as TODO in the code. CoreDNS hosts plugin can auto-generate PTR records, but proper zone configuration is needed to make CoreDNS authoritative for in-addr.arpa zones. This requires further investigation.

Documentation

Comprehensive documentation includes:

Prerequisites and auth key setup
Quick start guide
Full configuration reference
MagicDNS setup walkthrough
NAT and DNS doctoring configuration
Script architecture and troubleshooting
Use cases and examples
Operations and troubleshooting

Migration Path

N/A - New feature with opt-in configuration. Fully backward compatible.

Future Enhancements

Potential follow-ups:

PTR (reverse DNS) records support
Separate DNS infrastructure container option
IPv6 NAT support
Custom DNS record injection

Related Issues: #2396 #1394

Copilot

Pull Request Overview

This PR introduces comprehensive Tailscale VPN integration to containerlab, enabling secure remote access to lab management networks. The integration includes automatic deployment of Tailscale containers as infrastructure, optional DNS services with CoreDNS and MagicDNS support, and advanced features like 1:1 NAT with DNS doctoring for IP translation.

Key Changes

Tailscale VPN Integration: Automatic deployment and lifecycle management of Tailscale containers with route advertisement, configurable addressing, ACL tags, and NAT support
DNS Services: CoreDNS integration with automatic node record generation, split DNS support via Tailscale MagicDNS, and intelligent DNS proxy for NAT scenarios
Infrastructure Management: New infrastructure container concept with dedicated lifecycle methods and labeling system to distinguish from user nodes

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
`types/types.go`	Defines TailscaleConfig and TailscaleDNSConfig structs with comprehensive configuration options
`utils/ip.go`	Adds LastHostIPInSubnet helper function to calculate container IP addresses
`runtime/docker/tailscale.go`	Core implementation (~1000 lines) handling Tailscale deployment, DNS setup, and container management
`runtime/docker/scripts/nat-setup.sh`	Embedded shell script for iptables NETMAP rules to enable 1:1 NAT
`runtime/docker/scripts/dns-proxy.py`	Python DNS proxy with intelligent IP rewriting based on client source address
`runtime/docker/scripts/coredns-install.sh`	CoreDNS installation script with optional Python dependency
`runtime/docker/scripts/Corefile.tmpl`	CoreDNS configuration template for lab domain resolution
`runtime/docker/scripts/README.md`	Comprehensive documentation for embedded scripts architecture
`core/clab.go`	Infrastructure lifecycle methods (Deploy/Destroy/UpdateDNS)
`core/deploy.go`	Integration point for infrastructure deployment after network creation
`core/destroy.go`	Integration point for infrastructure cleanup before network deletion
`core/config.go`	Infrastructure container exclusion from uniqueness checks
`constants/labels.go`	New IsInfrastructure label constant
`docs/manual/tailscale.md`	Extensive documentation (795 lines) covering configuration, use cases, and troubleshooting
`docs/manual/network.md`	Brief introduction to Tailscale feature with reference to full documentation
`mkdocs.yml`	Navigation menu entry for Tailscale documentation

runtime/docker/scripts/dns-proxy.py

runtime/docker/scripts/nat-setup.sh

runtime/docker/scripts/README.md

runtime/docker/scripts/dns-proxy.py

runtime/docker/tailscale.go

utils/ip.go

runtime/docker/tailscale.go

docs/manual/tailscale.md

runtime/docker/scripts/dns-proxy.py

Co-authored-by: Copilot <[email protected]>

tvarohohlavy · 2025-11-12T08:17:29Z

Thanks @hellt
I have fixed the suggestions from Copilot.

kaelemc · 2025-11-12T16:53:55Z

@tvarohohlavy looks cool, I will try this one out :)

tailscale integration with mgmt network

77d9ee2

hellt requested a review from Copilot November 11, 2025 10:16

Copilot started reviewing on behalf of hellt November 11, 2025 10:17 View session

Copilot finished reviewing on behalf of hellt November 11, 2025 10:21

Copilot AI reviewed Nov 11, 2025

View reviewed changes

tvarohohlavy and others added 9 commits November 11, 2025 11:28

remove old script step description

b08e775

Co-authored-by: Copilot <[email protected]>

corrected markdown formatting

7cd928a

LastHostIPInSubnet tests and edge cases

6e5cacd

fix python syntax error due to golang template syntax

b3e1fc8

dns-proxy template parsing fixed and error handling adjusted

ae08c54

nat-setup.sh error handling

a7923ab

coredns-install.sh error handling

a5f8305

tailscale healthcheck config optimized

0beadac

tailscale - remove obsolete ContianerExecStart

0da7580

kaelemc self-requested a review November 12, 2025 16:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Tailscale Integration with Management Network #2928

Tailscale Integration with Management Network #2928

Uh oh!

tvarohohlavy commented Nov 11, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tvarohohlavy commented Nov 12, 2025

Uh oh!

kaelemc commented Nov 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Tailscale Integration with Management Network #2928

Are you sure you want to change the base?

Tailscale Integration with Management Network #2928

Uh oh!

Conversation

tvarohohlavy commented Nov 11, 2025

Tailscale VPN Integration with MagicDNS Support

Overview

Features

🔐 Tailscale VPN Integration

🌐 DNS Services

🛠️ Advanced Features

Configuration

Basic Setup

With MagicDNS

Advanced Configuration with NAT and DNS Doctoring

Architecture

DNS Integration

DNS Architecture with Doctoring

Files Changed

Core Implementation

Script Files (NEW)

Documentation

Usage Examples

Remote Lab Access

With MagicDNS

Testing

Known Limitations

Documentation

Migration Path

Future Enhancements

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tvarohohlavy commented Nov 12, 2025

Uh oh!

kaelemc commented Nov 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants