O tour pelo Ansible, parte 1: um repositório, três servidores – como o código está organizado e o que acontece durante uma execução

Parte 1 de um tour pelo meu código Ansible: como um repositório e 34 roles mantêm um blog e dois Nextclouds, e o que acontece durante a execução de um playbook.

Ilustração da série O tour pelo Ansible

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski

Primeira parte de uma série sobre o código Ansible por trás deste blog e de dois servidores Nextcloud. O código é público: github.com/aptupgrademe/www_k3s; a série descreve o release v3.3.0. A parte 1 explica a estrutura e o que acontece durante uma execução, as partes 2 a 6 os roles, os deep dives a tecnologia por baixo.

Três servidores, 34 roles, quatro playbooks, cerca de 22.000 linhas de YAML e templates. Quem abre o repositório pela primeira vez vê sobretudo arquivos. Esta parte explica três coisas que vale a pena saber antes: como um único conjunto de roles atende duas aplicações muito diferentes, de onde vem cada valor e o que de fato acontece entre ansible-playbook e o resumo final.

Índice

🧩 Um repositório para duas aplicações

O blog (WordPress) e os dois servidores Nextcloud têm pouco em comum à primeira vista. Por baixo, porém, precisam das mesmas coisas: um AlmaLinux endurecido, um firewall, SSH só com chave, K3s, certificados TLS, monitoramento, logs, proteção contra ataques de força bruta. Por isso os roles levam o nome de onde são usados:

  • common_* roda em todo servidor: firewall, SSH, K3s, Grafana, fail2ban e mais uns bons vinte.
  • blog_* existe só para o WordPress, next_* só para o Nextcloud.

Dois terços do código são compartilhados. Uma correção no firewall chega aos três servidores na próxima execução, e uma brecha que um Nextcloud revela também é fechada no blog.

O preço é uma regra que nunca tira folga: toda mudança num role compartilhado precisa funcionar nas duas stacks. Como fica quando isso só é verdade no papel mostrou um bug encontrado em 26 de outubro de 2026: o filtro do fail2ban para logins no Nextcloud só verificava POST /login. O Nextcloud, porém, envia seu formulário de login para /index.php/login. O filtro rodava nos dois servidores Nextcloud desde julho e nunca contou uma única tentativa; o rate limit na frente dele também não via as requisições. Só veio à tona quando um teste alimentou os filtros com uma linha de log real em vez de só verificar se o fail2ban estava rodando.

A lição: código compartilhado economiza trabalho, mas precisa de testes que verifiquem o resultado. Um serviço configurado e rodando não prova que ele faz o que deveria.

📒 De onde vem cada valor

Os roles descrevem o que fazer. O inventário decide com o quê: quais servidores existem, quais valores valem para todos e quais só para um.

  • hosts.yml contém apenas a atribuição: qual servidor pertence ao grupo blog, qual ao nextcloud.
  • group_vars/all/ contém o que é igual em todo lugar. O arquivo mais importante ali é o versions.yml: toda versão que um playbook instala (K3s, Helm, imagens de contêiner, exporters) está exatamente nesse arquivo, até o nível de patch. Nunca latest, nunca uma tag como 10.11. Uma tag dessas tinha deixado o blog com uma imagem MariaDB desatualizada em agosto, ainda em cache no nó, embora o Docker Hub já tivesse havia muito uma mais nova com o mesmo nome.
  • host_vars/<host>/ contém dois arquivos por servidor: vars.yml com endereços, tamanhos e chaves de configuração, vault.yml com as senhas, criptografadas com Ansible Vault. Nenhum dos dois está no repositório público. O que é público é um arquivo .example ao lado deles, que mostra de quais chaves um host precisa.

Quando um valor é definido em vários lugares, decide a precedência do Ansible: os defaults do role são o ponto de partida, group_vars os sobrescrevem, host_vars sobrescrevem os dois. Um exemplo é o filtro de país do SSH: ele vem desligado no role, e um servidor o liga com uma única linha no seu vars.yml.

Para que um valor faltando não apareça no meio de uma execução como um erro obscuro de template, 23 roles declaram suas entradas em meta/argument_specs.yml. O Ansible as verifica antes de o role rodar sua primeira task.

A lição: uma versão que não está fixada com exatidão, na realidade, está fixada pelo cache.

🔀 Como um role compartilhado diferencia as stacks

Um role common_* às vezes precisa saber onde está rodando. O Nextcloud tem MariaDB e Redis no host, o blog tem os dois em contêineres; por isso o firewall precisa de duas regras a mais no Nextcloud. Há três padrões para isso, em ordem de preferência:

  1. O playbook diz. Todo playbook completo define uma variável stack: wordpress ou stack: nextcloud. Esse é o único lugar em que a decisão é tomada; os roles só leem essa variável.
  2. Um perfil por stack. Roles que fazem o mesmo tipo de trabalho nas duas stacks com caminhos diferentes – os rótulos do SELinux para os diretórios montados, por exemplo – mantêm as duas listas nos seus defaults e escolhem uma pelo stack.
  3. Perguntar ao servidor. Se um servidor recebe seu endereço via DHCP não está em nenhuma variável; o firewall pergunta ao NetworkManager. Sem as regras de DHCP, o endereço sumiria na próxima renovação do lease.

Até a versão 3.2, os roles decidiam pelos nomes de grupo do inventário. Isso quebrou no servidor de teste, que está nos dois grupos: durante uma instalação do blog, o firewall abriu as portas do banco de dados do Nextcloud, e o Prometheus tentou coletar exporters do Nextcloud que ali não existiam.

A lição: a decisão pertence a um único lugar – onde se sabe o que é instalado, no playbook, não no inventário.

📜 A ordem no playbook é uma cadeia de dependências

São quatro playbooks: por aplicação, um para a execução completa e um para atualizações. Um playbook completo é uma lista de cerca de 25 roles, e a ordem segue as dependências, não o alfabeto:

  • SELinux antes do deployment. Os pods montam diretórios do host. Se eles ainda não tiverem o rótulo container_file_t, o SELinux bloqueia toda escrita, e o MariaDB não sobe.
  • Monitoramento depois do deployment. O Prometheus coleta os exporters nos pods, e o fail2ban lê os logs do ingress; os dois só existem depois do deployment.
  • AIDE sempre por último. O AIDE compara os arquivos do sistema com uma baseline toda noite. Uma execução altera arquivos monitorados de propósito, então o último role renova a baseline.

Todo role tem uma tag com o próprio nome. Isso transforma o playbook completo numa ferramenta precisa: --tags blog_k3s_deploy atualiza só os objetos do Kubernetes. Justamente ali havia uma armadilha que virou regra fixa: uma execução com --tags pula o último role, a baseline do AIDE fica velha, e à noite chega um e-mail sobre arquivos alterados. Desde então, toda execução com tags é seguida de uma segunda com --tags common_rkhunter,common_aide_refresh.

Os playbooks de atualização reiniciam a aplicação e por isso são escritos de forma defensiva: recusam-se a rodar sem --limit, não atualizam uma instância que já está presa em modo de manutenção, e fazem o trabalho num block com um rescue que mostra, se algo falhar, em que estado a instância ficou.

A lição: mover um role move uma dependência. A ordem faz parte do código.

⚙️ O que acontece durante uma execução

Conexão. O Ansible faz login como root via SSH com uma chave; o SSH não aceita senha. Depois coleta só os poucos facts de que os roles precisam: distribuição, kernel, hostname.

Primeiro, um relatório. O primeiro role não muda nada. Para K3s, Helm, o ingress e o cert-manager, ele compara o que está instalado, o que o versions.yml fixa e qual é o release mais recente. Quem inicia a execução vê se algo está desatualizado antes de qualquer mudança.

Task por task. O Ansible roda a task 1 em todos os hosts da execução, depois a task 2, e assim por diante. Cada task reporta ok (nada a fazer), changed ou failed. Aqui está a propriedade mais importante dos roles: idempotência. Uma segunda execução logo após a primeira tem que reportar changed=0. Isso transforma o playbook numa ferramenta de verificação: se ele reporta uma mudança num servidor que deveria corresponder ao código, isso é drift – alguém mudou algo à mão – ou um bug na task. Para isso, as tasks leem o estado primeiro e mudam só o que diverge. Os serviços não são reiniciados a cada oportunidade, e sim por handlers que rodam uma vez no fim, e só se a configuração deles mudou de verdade.

O dry run. Com --check --diff, o Ansible passa por todas as tasks, não muda nada e mostra o que mudaria. O script scripts/check-drift.sh filtra apenas as tasks que mudariam algo. Código de saída 0 significa: o servidor é exatamente o que o código descreve.

O veredito. Uma execução que termina com ok só diz que cada task fez o que foi mandada fazer. Se a aplicação funciona depois disso, quem verifica no fim são os roles de verify: 30 a 38 checagens por servidor, um relatório colorido, um e-mail, e a execução falha se uma checagem crítica não passar. Desde 26 de outubro de 2026, isso inclui testes de efeito: cada filtro do fail2ban recebe uma linha de log real, e cada jail bane brevemente um endereço de teste que precisa chegar ao kernel.

E sempre um host depois do outro: duas execuções paralelas no mesmo servidor colidiram no lock do banco de dados de pacotes em outubro.

A lição: changed=0 na segunda execução não é detalhe cosmético. É o que faz cada desvio real saltar aos olhos.

🧪 Como uma mudança chega a um servidor

Os servidores são produção: arquivos de outras pessoas e um blog com leitores. Por isso uma mudança sempre passa pelas mesmas etapas, do rápido e local ao lento e real:

  1. Mudança: o role, o template ou o versions.yml.
  2. Linting: ansible-lint e yamllint sobre o repositório inteiro; no commit, o gitleaks também procura senhas e chaves.
  3. Teste sem servidor, onde existir um teste (roles do Kubernetes, playbooks de atualização).
  4. Dry run com check-drift.sh e a pergunta: é exatamente isso que eu queria? Qualquer outra coisa na lista é uma surpresa a entender primeiro.
  5. Execução real em um servidor, limitada com --tags ao que a mudança toca.
  6. A checagem de drift de novo: agora ela tem que dizer “no drift”.
  7. Commit e push; o CI verifica o repositório inteiro mais uma vez.

Nenhuma dessas etapas depende de alguém se lembrar de algo. A única regra que continua manual: execuções reais são iniciadas por uma pessoa, um host depois do outro, depois que o dry run foi lido.

🎯 As cinco lições da parte 1

  • Roles compartilhados economizam trabalho, mas só com testes que verifiquem o efeito em vez do estado.
  • Fixe toda versão com exatidão, num único lugar.
  • A decisão “blog ou Nextcloud” pertence ao playbook.
  • A ordem dos roles é uma cadeia de dependências.
  • A idempotência transforma um playbook numa ferramenta de verificação.

🧭 Para onde o tour vai agora

Cada parte segue a mesma grade: o que um role faz, por que foi construído assim e o que deu errado pelo caminho. O último ponto costuma ser o mais instrutivo.

Alguns textos e imagens deste site foram criados com a ajuda de IA ou gerados por IA. Detalhes