f5e32afd81
Some checks failed
CI / lint-and-test (pull_request) Failing after 1m20s
CI / ansible-validation (pull_request) Successful in 6m40s
CI / secret-scanning (pull_request) Successful in 2m36s
CI / dependency-scan (pull_request) Successful in 6m12s
CI / sast-scan (pull_request) Successful in 6m48s
CI / license-check (pull_request) Successful in 1m16s
CI / vault-check (pull_request) Failing after 6m13s
CI / playbook-test (pull_request) Successful in 6m34s
CI / container-scan (pull_request) Successful in 6m57s
CI / sonar-analysis (pull_request) Failing after 1m10s
CI / workflow-summary (pull_request) Successful in 1m11s
- 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
129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
# Tailscale VPN Setup Guide
|
|
|
|
Tailscale provides secure mesh networking across all your machines with zero-config VPN connectivity.
|
|
|
|
## Prerequisites
|
|
- Tailscale account (free at https://tailscale.com)
|
|
- Auth key from Tailscale admin console
|
|
|
|
## 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
|
|
```bash
|
|
make create-vault
|
|
```
|
|
Add this content when prompted:
|
|
```yaml
|
|
---
|
|
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
|
|
```
|
|
|
|
### 3. Deploy Tailscale
|
|
```bash
|
|
# Preview changes (dry run)
|
|
make tailscale-check
|
|
|
|
# Install on all machines
|
|
make tailscale
|
|
|
|
# Check status
|
|
make tailscale-status
|
|
```
|
|
|
|
## Deployment Options
|
|
|
|
### Target Specific Machines
|
|
```bash
|
|
# Development machines only
|
|
make tailscale-dev
|
|
|
|
# Specific hosts
|
|
ansible-playbook playbooks/tailscale.yml --limit "dev01,bottom"
|
|
```
|
|
|
|
### Manual Installation
|
|
```bash
|
|
# 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`)
|
|
```yaml
|
|
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`)
|
|
```yaml
|
|
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
|
|
```bash
|
|
# Via Ansible
|
|
make tailscale-status
|
|
|
|
# On target machine
|
|
sudo systemctl status tailscaled
|
|
tailscale status
|
|
```
|
|
|
|
### View Logs
|
|
```bash
|
|
sudo journalctl -u tailscaled -f
|
|
```
|
|
|
|
### Manual Connection
|
|
If auth key wasn't provided during setup:
|
|
```bash
|
|
sudo tailscale up
|
|
```
|
|
|
|
### Reset Connection
|
|
```bash
|
|
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
|
|
- [Ansible Vault Guide](./vault.md) - Managing secrets securely
|
|
- [Network Architecture](../reference/network.md) - Overall network design |