operation

Operação

Preparação local

make bootstrap
make prepare
make security-check
make install-roles

make prepare cria ou valida o usuário técnico ansible, instala uma chave dedicada em ssh/ansible_wireguard_egress_vpn_ed25519, configura sudo sem senha para automação, registra a host key SSH do VPS em ssh/known_hosts e atualiza inventário/variáveis locais.

No preparo inicial, escolha senha quando a chave SSH bootstrap ainda não estiver instalada no VPS; escolha ssh quando já houver chave funcional. sshpass é opcional: quando não estiver instalado, os próprios comandos ssh/sudo pedirão as senhas no terminal dentro de uma única sessão SSH.

Garanta que .vault_pass esteja disponível localmente antes das validações Ansible quando houver group_vars/prod/vault.yml.

ssh/known_hosts, inventories/inventory.local.yml e group_vars/prod/zz-local.yml são locais, ignorados pelo Git e necessários para deploy real. Se forem removidos, rode make prepare novamente antes do deploy.

Validação

make security-check
make syntax
make lint
make docs
make test

make test executa --check --diff contra prod. Na primeira execução, o modo check não gera as chaves remotas do servidor; isso ocorre apenas no deploy real.

Deploy

./deploy.sh --limit prod --yes

Após o deploy, importe o perfil .conf do cliente desejado em artifacts/clients/. Cada cliente declarado gera um arquivo próprio.

Validação pós-deploy sem imprimir chaves:

ssh -i ssh/ansible_wireguard_egress_vpn_ed25519 \
  -o UserKnownHostsFile=ssh/known_hosts \
  -o StrictHostKeyChecking=yes \
  ansible@vpn.example.com 'sudo systemctl is-active wg-quick@wg0'

ssh -i ssh/ansible_wireguard_egress_vpn_ed25519 \
  -o UserKnownHostsFile=ssh/known_hosts \
  -o StrictHostKeyChecking=yes \
  ansible@vpn.example.com 'sudo wg show wg0 peers | wc -l'

Produção e publicação

Não publique alterações sem rodar make security-check. A checagem não substitui revisão humana, mas cobre os riscos locais mais comuns deste repo: arquivos sensíveis rastreados por engano, permissões abertas, Vault descriptografado e ausência da host key SSH fixada.

O perfil é dual-stack. IPv4 usa NAT; IPv6 prefere roteamento e ativa NAT66 apenas no fallback automático. Execute scripts/e2e_wireguard_check.sh --config <perfil> para validar egress IPv4/IPv6 por um cliente real.