Dez pontos, um branch: levando meu código Ansible de “funciona” para “está limpo”
Dez melhorias no meu código Ansible, testadas sem tocar a produção: kubernetes.core, dry run de verdade, lint, secret scan, rescue e Renovate.

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski
Tudo começou com uma pergunta um pouco vaidosa. Meu repositório Ansible roda este blog e dois servidores Nextcloud: 34 roles, quatro playbooks, cerca de 9.000 linhas de YAML, quase 200 commits. A maior parte dessas linhas não fui eu que escrevi – foi meu co-admin de IA (Claude), enquanto eu decidia, testava e rodava os playbooks. Então perguntei: se eu entendo a maior parte desse código, sou um usuário avançado de Ansible?
A resposta foi honesta e um pouco desconfortável: avançado em ler e operar, sim. Avançado em escrever do zero, ainda não comprovado. E aí veio uma lista de dez coisas que deixariam o próprio código melhor. Eu disse: faça as dez. Teste direito. Depois escreva sobre isso. Este é esse post.
Regras básicas, como sempre: tudo acontece num branch Git separado, nada encosta num servidor de produção até eu rodar, e cada afirmação é testada. “Testado” acabou sendo a parte interessante.
Índice
📋 Os dez pontos
| # | Melhoria | Por quê |
|---|---|---|
| 1 | Objetos Kubernetes via kubernetes.core.k8s em vez de kubectl apply via shell | idempotente, diffs reais, funciona em check mode |
| 2 | Tornar o --check realmente útil | um dry run antes de cada execução em produção |
| 3 | ansible-lint, yamllint e um secret scanner como hook de pre-commit e GitHub Action | pegar erros e segredos vazados antes de entrarem |
| 4 | Teste automatizado de idempotência | a segunda execução tem que reportar changed=0 |
| 5 | Caminhos de rescue nos playbooks de update | uma reação definida quando um update falha no meio |
| 6 | Dividir os arquivos de tasks grandes | um arquivo de 912 linhas não é amigo de ninguém |
| 7 | meta/argument_specs.yml para as roles | uma variável faltando falha no início, não no meio |
| 8 | Unificar roles duplicadas | uma role de ClamAV em vez de duas quase idênticas |
| 9 | Fixar versões de collections exatamente | >= deixa passar um major release com breaking changes sem ninguém notar |
| 10 | Renovate para os pins de versão | propostas de update como pull requests em vez de pesquisa manual |
No meio do caminho acrescentei um décimo primeiro desejo: todos os pins de versão num só lugar, para eu ver de relance o que roda onde. Mais sobre isso no ponto 10.
🧪 Primeiro problema: como testar código Kubernetes sem tocar a produção?
Antigamente havia um servidor de teste no inventário. Quando o Claude tentou alcançá-lo, o SSH recusou: host key verification failed. O IP provavelmente já pertence a outra pessoa, então ele deliberadamente não se conectou. E eu não entrego minha senha do vault num chat, então nenhum playbook podia rodar contra os servidores reais também.
A solução foi elegante: um K3s descartável em podman rootless no meu jump host. Um K3s completo falhou na hora (failed to find cpuset cgroup – containers rootless não recebem esse controller delegado). Mas para testar se manifests são aplicados de forma idempotente, você nem precisa de pods rodando, só do API server. O K3s tem uma flag exatamente para isso:
podman run -d --name k3s-test --privileged -p 127.0.0.1:16443:6443 \
docker.io/rancher/k3s:v1.36.5-k3s1 server --disable-agent \
--disable traefik --disable servicelb --disable metrics-server
Um pequeno script substituto faz o papel de k3s kubectl: ele repassa tudo para o container e responde “tudo certo” aos comandos que precisariam de pods rodando (exec, rollout status, wait). O teste então faz o que importa: aplica tudo com o código antigo do main (é o estado em que os servidores estão) e depois roda o código novo por cima – dry run, execução real, execução real de novo, dry run de novo.
1️⃣ kubernetes.core em vez de kubectl apply
O padrão antigo aparecia 29 vezes: renderizar um template em /tmp, kubectl apply -f, apagar o arquivo e adivinhar “changed” procurando a palavra configured na saída. O padrão novo renderiza em memória e fala direto com a API:
- name: Redis | Apply Deployment + Service
kubernetes.core.k8s:
kubeconfig: "{{ k3s_kubeconfig }}"
state: present
apply: true
definition: "{{ item }}"
loop: "{{ lookup('ansible.builtin.template', 'redis-deployment.yml.j2') | ansible.builtin.from_yaml_all | select | list }}"
loop_control:
label: "{{ item.kind }}/{{ item.metadata.name }}"
Três coisas só apareceram por causa do teste:
- O primeiro dry run disse “changed” para quase tudo – sem diff. Acontece que o módulo não mostra diff quando você entrega uma lista de objetos. Uma iteração de loop por objeto resolveu, e agora o diff diz exatamente
image: redis:7.4.11-alpine → redis:7.4.12-alpine. - A migração única só reescreve a annotation
last-applied-configuration(o kubectl escreve um"annotations":{}vazio nela, o módulo não). Spec e pod template continuam idênticos, então nenhum pod reinicia – conferido pelas revisões dos ReplicaSets, todas ainda em 1. - Helm:
helm upgrade --installrodava em todo play e empilhava uma revisão nova a cada vez.kubernetes.core.helmcompara versão do chart e values e não faz nada se baterem. Pegadinha: o Helm 4 só é suportado a partir da versão 6.5.0 da collection; o pacote da distro trazia a 6.1.0.
Efeito colateral de que gosto muito: Secrets do Kubernetes não passam mais por um arquivo em /tmp no servidor.
2️⃣ Um dry run que significa alguma coisa
Em check mode, o Ansible pula toda task shell/command – inclusive as inofensivas que só leem algo. Tasks posteriores que avaliam esses resultados então falham ou decidem com base em nada. 94 consultas puras (checagens de versão, occ config:system:get, systemctl is-active …) agora levam check_mode: false. Tudo que escreve continua pulado – e onde isso esconderia uma mudança pendente, uma pequena task extra a reporta.
3️⃣ Lint, secret scan, hooks
A primeira execução do ansible-lint reportou 811 achados. Uns 600 eram regras de estilo que contradizem escolhas deliberadas (colunas alinhadas, nomes de variáveis compartilhados sem prefixo de role) – essas foram desligadas com uma justificativa por escrito. O resto foi corrigido. Dois achados reais:
ansible.builtin.ini_filenão existe. Só funcionava por um redirect legado paracommunity.general– uma collection que nem estava norequirements.yml. Num controller com ansible-core puro, o playbook do Nextcloud teria parado bem ali.- 27 pipes de shell sem
pipefail. Quase todos inofensivos, mas na checagem de versão,k3s --version | awk … || echo 'not installed'nunca conseguiria imprimir “not installed”: sempipefailsó conta o exit code doawk.
O gitleaks varreu todos os 191 commits do histórico: um acerto, um placeholder PASTE_CONTENT_OF_id_rsa_HERE entre dois marcadores de chave num arquivo de exemplo antigo. Aceito de propósito, documentado. Os hooks agora rodam em todo commit – e o primeiro commit que eles bloquearam foi do próprio Claude, algumas horas depois (indentação YAML errada em arquivos gerados). Exatamente para isso que servem.
4️⃣ Idempotência, testada
O teste com podman agora faz parte do repo (tests/k8s/run.sh). Ele falha se a segunda execução ainda mudar alguma coisa, se um pod fosse ser recriado, se um release do Helm ganhar revisão nova – ou se uma tag de imagem alterada de propósito não for detectada. Esse último importa: um teste que nunca pode falhar não prova nada.
Para os servidores reais existe scripts/check-drift.sh <playbook> <host>: um dry run que imprime só o que mudaria, com um diff legível. Logo depois de uma execução real ele tem que dizer NO DRIFT.
No caminho, algumas tasks que reportavam “changed” em toda execução foram corrigidas (download de assinatura, um usuário de banco, um módulo do dnf). O achado mais traiçoeiro foi o contrário: as nove configurações de SMTP do Nextcloud eram reescritas em toda execução e sempre reportavam “ok”. Uma senha de e-mail alterada nunca teria aparecido como mudança. Agora elas são lidas primeiro, comparadas, e só os valores diferentes são escritos – passados via argv, para que uma aspa numa senha não quebre o comando.
5️⃣ Quando um update falha no meio
A primeira sugestão do Claude foi “sair do modo de manutenção de forma limpa no rescue”. Pensando melhor, ele se corrigiu: depois de um occ upgrade abortado, desligar o modo de manutenção coloca os usuários numa instância atualizada pela metade. A lógica agora:
- Uma checagem prévia fora do block: instalado, fora do modo de manutenção, nenhum upgrade de banco pendente – senão o playbook se recusa a começar. Fora de propósito: o rescue só deve lidar com estados que a própria execução causou.
- O rescue coleta status do occ, pods, events e as últimas linhas do
nextcloud.log, e desliga o modo de manutenção só seneedsDbUpgradefor false. Depois para, para que nenhum segundo servidor seja tocado. - Bônus: os playbooks de update reiniciavam Nextcloud e Collabora em toda execução. Uma pequena role nova compara o digest de cada imagem recém-baixada com o que os pods estão rodando e reinicia só o que foi realmente reconstruído – exporters e notify_push incluídos.
Testado com kubectl/crictl falsos em 14 cenários. E aí a parte importante: quebrar o rescue de propósito (sempre desligar a manutenção) e rodar o teste de novo. Ele ficou vermelho exatamente no cenário certo. Antes disso, o mesmo teste uma vez tinha mostrado “tudo verde” pelo motivo errado – dois cenários com o mesmo nome compartilhavam um diretório e misturavam os logs. Verde não significa muita coisa até você ter visto o teste falhar.
6️⃣ a 9️⃣ Os mais discretos
- 6 – dividir: a role do WordPress (912 linhas) agora são sete arquivos temáticos, a do Grafana três, as roles de verificação dois cada. Prova de que nada mudou:
--list-tasks --list-tagsantes e depois, idênticos. - 7 – argument specs: 23 roles declaram seus inputs. “Obrigatório” é calculado por tipo de host: roles compartilhadas leem
blog_hostnamenum servidor enextcloud_hostnameno outro, então nenhuma das duas pode ser obrigatória. Conferido contra as variáveis reais dos três servidores. Valores do vault sãono_log– verificado que não aparecem nem com-vvvnem num erro de validação. - 8 – unificar: uma role de ClamAV e uma de SELinux com um perfil por stack, mais 16 smoke checks compartilhados. Armadilha evitada: o Ansible identifica entradas de cron pelo nome, então os nomes tinham que continuar exatamente iguais – senão o job antigo teria continuado rodando ao lado do novo.
- 9 – pins:
>=3.0.0virou3.15.0. O dry run do Renovate mostrou por que isso importa: majors 5.x e 13.x estavam esperando.
🔟 Renovate, e todas as versões num arquivo só
Todos os pins de versão agora moram em inventory/group_vars/all/versions.yml: os valores compactos em cima, os motivos e o histórico embaixo. O Renovate recebe regex managers exatamente para essas linhas e propõe updates como pull requests – semanalmente, nunca com merge automático. Um dry run local com o container do Renovate achou todos os 21 pins rastreados e prontamente sugeriu nginx 1.31. Esse é o branch mainline; eu uso o stable (minor par). Então agora há guard rails:
- O nginx fica em versões minor pares.
- Majors (Nextcloud 35, MariaDB, Redis 8) e minors de K3s/Calico só depois de aprovação no dependency dashboard, com uma nota sobre o que fazer.
- PRs do WP-CLI me lembram de atualizar também o checksum SHA-512 – o Renovate não consegue calculá-lo, e sem ele o init container do blog rejeitaria o download.
📚 E a documentação
Novo no repo: “Como o código Ansible funciona” em alemão, inglês e francês – variáveis e sua precedência, o que acontece durante uma execução, como os módulos Kubernetes funcionam, padrões de idempotência, tratamento de erros, os testes e uma trilha de aprendizado. Atualizar os guias existentes revelou de bônus alguns fatos desatualizados: uma versão antiga de imagem, uma descrição do Calico que ainda dizia “só Nextcloud”, uma tabela de variáveis apontando para o arquivo errado.
🚀 O rollout
Os testes locais estavam verdes. Então dei ao Claude o arquivo de senha do vault (criado por mim no terminal, nunca no chat) e ele rodou o drift check contra os servidores reais. A primeiríssima execução contra o blog caiu – o próprio script do Claude tropeçou no módulo dnf, que devolve seus resultados como lista de strings em vez de objetos. Corrigido, rodado de novo, e aí vieram os achados reais. A maioria estava em código que rodava havia meses.
O que só os servidores reais mostraram
- A role do Grafana não conseguia fazer dry run nenhum. Ela pergunta à API “o datasource existe?” via módulo
uri– que o Ansible pula em check mode – e a task seguinte então avaliava um resultado que não existia. Inofensivo em execuções reais, fatal para--check. - Minha própria correção do ponto 4 estava incompleta. Eu tinha adicionado
creates:para que ofreshclamsó rodasse uma vez – mas deixeichanged_when: trueno lugar, o que sobrescreve o resultado “skipped, file exists”. Continuava reportando “changed” toda vez sem fazer nada. - Um pingue-pongue de ownership: o playbook colocava
publickey.asccomo root, outra coisa voltava para www-data – em toda execução, despercebido por meses. - Os binários de monitoramento do Nextcloud eram baixados de novo após cada reboot. Os arquivos ficam em
/tmp, um reboot o esvazia, e a task de download não tinha condição. Agora ela confere primeiro a versão instalada. - Um privilégio renomeado: o usuário do exporter do MariaDB recebia o grant de novo em toda execução. O código pedia
REPLICATION CLIENT, o MariaDB 10.11 reporta o mesmo privilégio comoBINLOG MONITOR, e o módulo via uma diferença que não era diferença. - 46 avisos de depreciação para variáveis de fact no nível de topo (
ansible_kernelem vez deansible_facts['kernel']) – ok hoje, quebrado num futuro release do Ansible.
Uma pergunta exigiu mais do que um log: o Deployment do Nextcloud mudaria? A task dele é no_log porque carrega segredos, então o diff fica escondido. Um restart significa uma queda curta (estratégia Recreate). O Claude comparou o objeto ao vivo com um dry run server-side do apply e imprimiu só os nomes dos campos diferentes, nunca valores: idêntico, tirando a annotation last-applied. Sem restart.
Mais rápido, já que estávamos nisso
Perguntei se as roles poderiam rodar em paralelo para acelerar. Resposta honesta: não num único host – o Ansible trabalha as tasks de um host uma depois da outra, e as race conditions reais seriam locks do dnf e AIDE/rkhunter precisando do estado final. Os ganhos seguros estavam em outro lugar: o AIDE agora compara e escreve sua baseline em um scan em vez de dois (de 30 segundos a 3 minutos por execução no blog), e os objetos Kubernetes de um template vão para a API numa chamada só em execuções normais – por objeto só com --diff, onde o diff legível importa. Só o Calico caiu de uns 30 segundos para menos de 2.
As execuções reais
- Blog: MariaDB e Redis intocados, WordPress reiniciado uma vez – conferi por quê: a única diferença entre o pod template antigo e o novo era o carimbo
restartedAtdo restart proposital após updates de plugins. Os releases do Helm ficaram na revisão 87 (cert-manager) e 72 (ingress-nginx). Esses números dizem tudo: o código antigo adicionava uma revisão por execução. Drift check depois: NO DRIFT. - sofie: nenhum pod reiniciado, revisões do Helm inalteradas, self-test do notify_push verde, NO DRIFT.
- cvjm (o Nextcloud grande): mesmo quadro – nenhum pod reiniciado, revisões do Helm inalteradas, o usuário do exporter agora tem
BINLOG MONITORe não recebe mais grant de novo, NO DRIFT.
🎯 Conclusão
Em números: 16 commits, 165 arquivos tocados, 0 falhas de lint, duas suítes de teste novas, três servidores convertidos – cada um terminando com NO DRIFT. Mas os números não são o ponto. A maioria dos achados reais veio de testes que tinham permissão para falhar: a dependência de collection escondida, a senha de e-mail que nunca aparecia como mudança, o diff que faltava, o teste que estava verde pelo motivo errado – e, quando os servidores reais entraram na jogada, meia dúzia de pequenas mentiras em código que rodava quietinho havia meses.
E minha pergunta inicial? O repositório agora tem uma trilha de aprendizado. O passo três diz: escreva uma role você mesmo, sem template. Essa é comigo.
