Ansible WireGuard Egress VPN

Automação Ansible para implantar um servidor WireGuard em Ubuntu 24 LTS e usá-lo como VPN full-tunnel de saída para a internet.

Escopo

• Host alvo público de exemplo: vpn.example.com
• Ambiente suportado: prod
• Sistema operacional remoto: Ubuntu 24 LTS
• Interface WireGuard: wg0
• Porta WireGuard: 51820/udp
• Rede IPv4 VPN de exemplo: 10.8.0.0/24
• Prefixo IPv6 VPN de exemplo: fd42:8:8::/64
• Cliente inicial de exemplo: example-client

O deploy instala WireGuard, habilita forwarding IPv4/IPv6, configura NAT para IPv4, roteia IPv6 por prefixo global quando possível e ativa NAT66 apenas como fallback automático para prefixo ULA ou VPS com IPv6 limitado a /128.

Pré-requisitos

• Python 3.12+
• uv
• Acesso SSH bootstrap ao host com um usuário que tenha sudo
• Depois do preparo, acesso SSH técnico com a chave em ssh/ansible_wireguard_egress_vpn_ed25519
• Arquivo .vault_pass local apenas se existir group_vars/prod/vault.yml

make prepare aceita acesso bootstrap por senha ou por chave SSH. Use senha quando a chave inicial ainda não estiver configurada no VPS. Se sshpass existir localmente, o script automatiza a senha SSH; caso contrário, ssh e sudo pedirão as senhas diretamente no terminal dentro de uma única sessão SSH.

Arquivos em ssh/, logs/, artifacts/clients/, .vault_pass, inventories/*.local.yml, group_vars/*/zz-local.yml e group_vars/*/vault.yml são locais e ignorados pelo Git.

Fluxo rápido

make bootstrap
make prepare
make security-check
make install-roles
make syntax
make lint
make docs
make test
make deploy-prod

Ou usando o wrapper operacional:

./deploy.sh --limit prod --check
./deploy.sh --limit prod

Segurança

• Não versionar chaves privadas, senha Vault, configs de cliente ou logs.
• Rode make security-check antes de publicar alterações ou executar deploys relevantes.
• Segredos reais ficam em arquivos Ansible Vault, como group_vars/prod/vault.yml.
• O Ansible valida a identidade SSH do VPS com host_key_checking = True e ssh/known_hosts local, gerado pelo make prepare.
• prepare.sh cria o usuário técnico ansible sem senha utilizável, instala chave SSH dedicada e configura sudo sem senha em /etc/sudoers.d/ansible. NOPASSWD:ALL é aceito por compatibilidade com provisionamento Ansible geral e mitigado por chave dedicada, usuário técnico sem senha e host key checking.
• O playbook permite SSH antes de habilitar UFW para reduzir risco de lockout.
• IPv6 full-tunnel prefere roteamento com prefixo IPv6 global. Se o prefixo do túnel for ULA (fd00::/8) ou o servidor tiver apenas IPv6 /128, o playbook avisa e ativa NAT66 para preservar conectividade externa.

Clientes WireGuard

Defina clientes em group_vars/prod/vars.yml ou no override local ignorado group_vars/prod/zz-local.yml apenas pelo nome quando quiser IP automático:

wireguard_server_clients:
  - name: example-client

Os endereços são gerados pela ordem da lista, a partir de 10.8.0.2/32 e fd42:8:8::2/128 no exemplo público. Para preservar IPs e perfis existentes, não reordene clientes; adicione novos nomes sempre no final. Quando necessário, fixe os IPs com address e address_ipv6.

Configuração local

O repositório público é um template neutro. Valores reais de produção devem ficar em:

• inventories/inventory.local.yml
• group_vars/prod/zz-local.yml
• group_vars/prod/vault.yml

Esses arquivos são ignorados pelo Git. deploy.sh, make syntax e make lint carregam os overrides locais quando eles existem.

Documentação

• TechDocs: docs/
• Runbooks operacionais: runbooks/
• Política de segurança: SECURITY.md
• Guia de contribuição: CONTRIBUTING.md