ansible/TAILSCALE_SETUP.md

Tailscale Setup Guide

This guide will help you deploy Tailscale across all your machines using Ansible.

Quick Start

1. Get your Tailscale auth key:

   • Go to https://login.tailscale.com/admin/settings/keys
   • Generate a new auth key (preferably reusable and non-expiring for automation)

2. Store the auth key securely:

   make create-vault
   

   Add this content to the vault file:

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

3. Install Tailscale on all machines:

   # Dry run first to check what will happen
   make tailscale-check
   
   # Install on all machines
   make tailscale
   

Available Commands

• make tailscale - Install Tailscale on all machines
• make tailscale-check - Dry run to see what changes will be made
• make tailscale-dev - Install only on dev machines
• make tailscale-status - Check Tailscale status on all machines

Manual Installation Options

Install on specific machines:

ansible-playbook -i hosts tailscale-playbook.yml --limit "devVM,bottom"

Install with custom auth key:

ansible-playbook -i hosts tailscale-playbook.yml --extra-vars "tailscale_auth_key=your-key-here"

Install as part of existing playbooks:

The Tailscale role has been added to both dev-playbook.yml and local-playbook.yml with the tag tailscale.

Run only Tailscale tasks:

ansible-playbook -i hosts dev-playbook.yml --tags tailscale

Configuration Options

You can customize Tailscale behavior by setting these variables in group_vars/all.yml or host_vars/hostname.yml:

tailscale_auth_key: "{{ vault_tailscale_auth_key }}"  # Auth key from vault
tailscale_hostname: "{{ inventory_hostname }}"        # Custom hostname
tailscale_accept_routes: true                         # Accept subnet routes
tailscale_accept_dns: true                           # Accept DNS settings
tailscale_ssh: true                                  # Enable SSH server
tailscale_advertise_routes: "192.168.1.0/24"        # Advertise subnets
tailscale_shields_up: false                         # Block incoming connections

Troubleshooting

Check if Tailscale is running:

make tailscale-status

Manual connection (if auth key wasn't provided):

# SSH to the machine and run:
sudo tailscale up

Reset connection:

ansible-playbook -i hosts tailscale-playbook.yml --extra-vars "tailscale_reset=true"

View logs:

# On the target machine:
sudo journalctl -u tailscaled -f

Security Notes

• Store your Tailscale auth key in Ansible Vault for security
• Consider using ephemeral auth keys for one-time setups
• The role enables SSH by default - disable if not needed
• Machines will need to be authorized in your Tailscale admin console

Supported Operating Systems

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

The role automatically detects the OS and uses the appropriate package manager (apt for Ubuntu/Debian, apk for Alpine).