Dois minutos e quarenta e cinco: minha primeira atualização de apps do Nextcloud via Ansible (e o guard rail que adicionei logo antes)

Ilustração do artigo sobre atualizar o Nextcloud no K3s

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

Hora da confissão: o Nextcloud de produção do diário de batalha da migração roda no K3s há uma semana, o repositório tem um playbook nextcloud-update.yml há meses, e eu nunca o tinha executado de verdade. Os apps eram atualizados do jeito antigo, clicando na interface de administração, ou simplesmente não eram. Hoje isso mudou. A execução em si levou 2 minutos e 45 segundos. A parte interessante foi tudo ao redor.

Mesmo fluxo de sempre: eu decido, meu coadministrador de IA (Claude) confere, constrói e verifica. E a primeiríssima coisa que ele encontrou não foi um bug na lógica de atualização, mas uma arma carregada apontada para o pé na linha três.

Índice

🧭 Por que um playbook de atualização separado?

Primeiro, uma pergunta que eu realmente tive que fazer: se eu rodar o playbook principal, meus apps são atualizados? Resposta: não, e isso é de propósito. Há dois motivos independentes, e o playbook principal deliberadamente não cobre nenhum deles.

Motivo 1: mesma tag, imagem mais nova

Uma tag de imagem como nextcloud:34.0.4-fpm é só um nome que aponta para uma imagem. Imagens oficiais são reconstruídas com o mesmo nome sempre que algo por baixo recebe um patch: uma correção de segurança do Debian, um point release do PHP, OpenSSL. A versão do Nextcloud continua 34.0.4; o conteúdo não.

Meus pods rodam com imagePullPolicy: IfNotPresent: se uma imagem com esse nome já está no store local do containerd, o K3s nunca mais pergunta ao registry. Então, enquanto a tag no inventário não muda, o playbook principal aplica manifests idênticos, o K3s não vê nada a fazer, e o build antigo continua rodando indefinidamente. O playbook de atualização força a comparação com crictl pull e reinicia depois. O mesmo vale para o Collabora.

Motivo 2: os apps não estão na imagem

Este é o maior. O diretório de código do Nextcloud, /var/www/html, é um volume HostPath no servidor (/srv/nextcloud-www), e os apps da app store são instalados bem ali, ao lado do core. Uma imagem nova traz um core novo e os apps embarcados. Ela nunca toca em apps de terceiros como audioplayer, drawio ou Deck. Esses só se mexem com occ app:update (ou um clique na interface de administração). O playbook principal só impõe o layout dos apps: estes ligados, estes desligados, instalar o que falta. Existe um interruptor opcional (nextcloud_apps_update), padrão false.

Três camadas, três alavancas

O que muda?ExemploAlavanca
Versão do Nextcloud34.0.4 → 34.0.5, ou → 35Mudar a tag no inventário, rodar nextcloud-k3s.yml
Imagem reconstruída, mesma tagCorreção de segurança no PHP ou Debiannextcloud-update.yml (pull + restart)
Apps da app storeaudioplayer 3 → 4nextcloud-update.yml (occ app:update --all)

Por que não juntar tudo numa execução só? Porque o playbook principal deve ser idempotente e previsível: ele converge para um estado declarado, e rodá-lo duas vezes não muda nada na segunda. Atualizações são o oposto: elas buscam o que houver de novo na internet e trocam código em execução. Isso merece seu próprio momento, sua própria checagem de backup e seus próprios olhos nos logs depois. Senão cada pequena execução de configuração atualizaria apps silenciosamente de quebra, e quando algo quebrasse depois, você nunca saberia se foi sua mudança de configuração ou o release de outra pessoa.

🔫 A arma no pé: hosts: nextcloud

O play mira o grupo de inventário nextcloud. Esse grupo contém atualmente a instância de produção, um host de teste e uma segunda instância que está no meio de uma migração: o banco de dados dela é sobrescrito a cada sync até o dia do cutover, e ela está fixada na versão exata do servidor antigo. Esqueça o --limit uma vez e a atualização passa pelos três, reiniciando pods numa máquina que deveria ficar perfeitamente parada.

A correção são quatro linhas e faz o playbook se recusar a iniciar sem um limit:

- name: Update | Refuse to run without --limit
  ansible.builtin.assert:
    that: ansible_limit is defined
    fail_msg: "Run with --limit <host>, e.g. --limit cvjm - this playbook restarts Nextcloud."
  run_once: true

ansible_limit é uma variável mágica que só existe quando --limit foi passado. Barato, explícito, e transforma “ops” numa mensagem de erro. Primeira task da execução de hoje: “All assertions passed”. 🎉

✅ Pre-flight: quatro checagens, dois minutos

  • Backup recente? O pull diário da máquina de backup tinha terminado às 12:30 com dump do banco e dados. Uma atualização sem ponto de restauração recente é aposta, não manutenção.
  • O que vai mudar de fato? occ app:update --all --showonly é o dry run. Resultado: exatamente um app, audioplayer, pulando para 4.0.0.
  • Linha de base saudável? occ status: sem modo de manutenção, sem upgrade de banco pendente, todos os pods rodando, 190 GB livres. Coisas que você quer saber antes, para depois conseguir dizer se você quebrou algo ou se já estava quebrado.
  • Quem está online? Cinco usuários ativos nos últimos 15 minutos. Dois restarts do Nextcloud e um restart do Collabora significam que documentos do Office abertos são desconectados. Anotado, aceito, é uma terça-feira tranquila na hora do almoço.

⚙️ Anatomia da execução

PassoTempoPor que está ali
crictl pull Nextcloud + Collabora51 sOs pods usam imagePullPolicy: IfNotPresent, então o K3s nunca puxa uma tag de novo por conta própria. Aqui a tag está fixada num patch release exato, então isso basicamente confirmou que a imagem fixada ainda é a imagem fixada.
Reiniciar o Nextcloud42 sPega uma imagem nova se houver uma. O deployment usa a estratégia Recreate: só um pod pode tocar nos volumes HostPath, então há uma pequena lacuna em vez de uma passagem gradual.
Reiniciar o Collabora20 sMesma ideia para o servidor do Office.
occ upgrade2 sO entrypoint do container já o executa na inicialização; esta é a rede de segurança.
occ app:update --all2 saudioplayer → 4.0.0. A app store só oferece releases compatíveis com a versão major em execução, então isso não consegue trazer algo que quebre o Nextcloud 34.
Reiniciar o Nextcloud de novo43 sO interessante, veja abaixo.

🧠 Por que reiniciar duas vezes? OPcache e uma configuração que não perdoa

A configuração do PHP roda com opcache.validate_timestamps=0. É uma configuração de desempenho: o PHP compila cada arquivo uma vez e nunca mais confere o arquivo no disco durante a vida do processo. Ótimo para velocidade, mas tem uma consequência chata para atualizações.

O primeiro restart acontece antes de o occ escrever qualquer coisa; ele existe para pegar imagens. Depois o app:update sobrescreve os arquivos PHP do app no volume persistente, mas o PHP-FPM em execução continua servindo o bytecode antigo do seu cache. A atualização parece concluída, o app:list mostra o novo número de versão, e o código antigo continua rodando até o próximo restart sem relação nenhuma. Para uma correção de segurança, esse é o pior tipo de “pronto”. Daí o segundo restart, e só quando algo realmente mudou.

Detalhe curioso: isso só pega apps atualizados. Um app recém-instalado nunca esteve no cache, então ele é compilado do zero. São especificamente as atualizações que silenciosamente não fazem efeito.

🐛 Bug nº 2: uma task que sempre dizia “changed”

A task occ upgrade reportava changed embora não houvesse nada a atualizar. O changed_when dela procurava a ausência da frase “already at the latest version”, e o Nextcloud 34 não imprime mais essa frase. Numa execução sem mudanças ele agora só imprime uma nota apontando para a documentação de upgrade. A ausência de uma string que não existe mais é sempre verdadeira, então a task sempre alegava uma mudança.

# before: true forever on NC 34
changed_when: "'already at the latest version' not in occ_upgrade.stdout"
# after: only a real upgrade prints this
changed_when: "'Update successful' in occ_upgrade.stdout"

Inofensivo hoje, já que a atualização do app disparou o segundo restart de qualquer jeito. Mas um playbook que mente sobre mudanças te treina a ignorar a saída dele, e um dia essa saída importa. Lição: procure o sinal positivo, não a ausência de um antigo.

🔍 Post-flight: confie, mas verifique

  • audioplayer 4.0.0 ativado; a lista de apps desativados inalterada, então nada foi ligado ou desligado pelas minhas costas.
  • nextcloud.log desde a execução: zero warnings, zero erros. Nenhum erro de PHP no container.
  • Collabora: o discovery responde, o lado Nextcloud da conexão está intacto.
  • Autoteste do notify_push: as três checagens verdes. O push server se reconectou sozinho depois dos restarts.
  • 5xx no ingress: cinco requisições, todas de celulares e clientes de sync durante os segundos em que o pod estava reiniciando. Esperado com Recreate; os clientes tentam de novo automaticamente.

🎯 Conclusão

A atualização em si foi a parte menos empolgante: um app, menos de três minutos, logs limpos. O valor estava nas bordas. Um guard rail que torna impossível o padrão perigoso, um restart que existe por causa de uma única configuração de cache, e uma checagem de status que mentia silenciosamente desde a última versão major. Infrastructure as code não torna atualizações mágicas. Ela as torna chatas, e chato é exatamente o que você quer da coisa que mexe em produção. 🧰


📚 Mais nesta série: Nextcloud do bare metal ao K3s

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