ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/docs/guides/tailscale.md

3.2 KiB
Raw Blame History

Tailscale VPN Setup Guide

Tailscale provides secure mesh networking across all your machines with zero-config VPN connectivity.

Prerequisites

Quick Setup (3 Steps)

1. Get Your Auth Key

  1. Visit https://login.tailscale.com/admin/settings/keys
  2. Click "Generate auth key"
  3. Configure key:
    • Reusable: Yes (for multiple machines)
    • Expiration: 90 days or longer
  4. Copy the key (starts with tskey-auth-)

2. Store Key Securely

make create-vault

Add this content when prompted:

---
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"

3. Deploy Tailscale

# Preview changes (dry run)
make tailscale-check

# Install on all machines
make tailscale

# Check status
make tailscale-status

Deployment Options

Target Specific Machines

# Development machines only
make tailscale-dev

# Specific hosts
ansible-playbook tailscale-playbook.yml --limit "dev01,bottom"

Manual Installation

# With custom auth key (not recommended - use vault instead)
ansible-playbook tailscale-playbook.yml -e "tailscale_auth_key=your-key"

# As part of existing playbooks
ansible-playbook dev-playbook.yml --tags tailscale

Configuration

Global Settings (group_vars/all.yml)

tailscale_auth_key: "{{ vault_tailscale_auth_key }}"  # From vault
tailscale_accept_routes: true                         # Accept subnet routes
tailscale_accept_dns: true                           # Accept DNS settings
tailscale_ssh: true                                  # Enable SSH over Tailscale

Host-Specific Settings (host_vars/hostname.yml)

tailscale_hostname: "custom-name"              # Override hostname
tailscale_advertise_routes: "192.168.1.0/24"  # Share local subnet
tailscale_shields_up: false                   # Block incoming connections

Troubleshooting

Check Service Status

# Via Ansible
make tailscale-status

# On target machine
sudo systemctl status tailscaled
tailscale status

View Logs

sudo journalctl -u tailscaled -f

Manual Connection

If auth key wasn't provided during setup:

sudo tailscale up

Reset Connection

ansible-playbook tailscale-playbook.yml -e "tailscale_reset=true"

Security Best Practices

  • Always use Ansible Vault for auth keys
  • Consider ephemeral keys for one-time setups
  • Authorize machines in Tailscale admin console
  • Review SSH settings if enabling Tailscale SSH

Supported Platforms

  • Ubuntu: focal, jammy, noble
  • Debian: bullseye, bookworm, trixie
  • Alpine Linux: all versions

The role automatically detects OS and uses appropriate package manager.

How It Works

  1. Playbook runs → looks for tailscale_auth_key
  2. Checks all.yml → finds {{ vault_tailscale_auth_key }}
  3. Decrypts vault → retrieves actual auth key
  4. Installs Tailscale → configures with your settings
  5. Connects to network → machine appears in admin console

Related Documentation