ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/docs/guides/tailscale.md
ilia c7a300b922
Some checks failed
CI / lint-and-test (pull_request) Successful in 1m21s
Details
CI / ansible-validation (pull_request) Successful in 9m3s
Details
CI / secret-scanning (pull_request) Successful in 3m19s
Details
CI / dependency-scan (pull_request) Successful in 7m13s
Details
CI / sast-scan (pull_request) Successful in 6m38s
Details
CI / license-check (pull_request) Successful in 1m16s
Details
CI / vault-check (pull_request) Failing after 6m40s
Details
CI / playbook-test (pull_request) Successful in 9m28s
Details
CI / container-scan (pull_request) Successful in 7m59s
Details
CI / sonar-analysis (pull_request) Failing after 1m11s
Details
CI / workflow-summary (pull_request) Successful in 1m11s
Details
Add POTE app project support and improve IP conflict detection 
- Add roles/pote: Python/venv deployment role with PostgreSQL, cron jobs
- Add playbooks/app/: Proxmox app stack provisioning and configuration
- Add roles/app_setup: Generic app deployment role (Node.js/systemd)
- Add roles/base_os: Base OS hardening role
- Enhance roles/proxmox_vm: Split LXC/KVM tasks, improve error handling
- Add IP uniqueness validation: Preflight check for duplicate IPs within projects
- Add Proxmox-side IP conflict detection: Check existing LXC net0 configs
- Update inventories/production/group_vars/all/main.yml: Add pote project config
- Add vault.example.yml: Template for POTE secrets (git key, DB, SMTP)
- Update .gitignore: Exclude deploy keys, backup files, and other secrets
- Update documentation: README, role docs, execution flow guides

Security:
- All secrets stored in encrypted vault.yml (never committed in plaintext)
- Deploy keys excluded via .gitignore
- IP conflict guardrails prevent accidental duplicate IP assignments
2025-12-28 20:54:50 -05:00

3.3 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 playbooks/tailscale.yml --limit "dev01,bottom"

Manual Installation

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

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

Configuration

Global Settings (inventories/production/group_vars/all/main.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 (inventories/production/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 playbooks/tailscale.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 inventory group vars → 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