Controlar o cloud-init em uma instância Debian ou Ubuntu recém-criada: user-data, status --wait e reexecuções seguras

Objetivo

Confirmar que o cloud-init terminou de configurar uma imagem de nuvem Debian ou Ubuntu, validar um arquivo user-data antes de depender dele e testá-lo novamente, com segurança, na mesma instância.

Pré-requisitos

Uma instância iniciada a partir de uma imagem de nuvem com cloud-init instalado (o padrão nas imagens cloud/server de Debian e Ubuntu); acesso ao shell, de preferência pelo console do provedor no primeiro boot, caso o user-data quebre a rede.

Passos

1. Depois do boot, bloqueie qualquer automação posterior até o provisionamento terminar: cloud-init status --wait. A referência de comandos descreve --wait como um bloqueio "until cloud-init completes" (até o cloud-init concluir). O subcomando status sem opções informa se o cloud-init está running, done, disabled ou em erro, com código de saída 1 em caso de falha (crash) e 2 em erros recuperáveis.
2. Em caso de falha, leia os dois arquivos de log que o próprio cloud-init indica para a triagem: /var/log/cloud-init.log (rastreamento detalhado dos módulos) e /var/log/cloud-init-output.log (stdout/stderr capturados do que o cloud-init executou).
3. Antes de anexar um novo arquivo user-data a uma instância, valide-o localmente: cloud-init schema --system --annotate. O subcomando schema consegue "Validate cloud-config files using jsonschema"; a opção --system o aponta para o user-data realmente em uso, em vez de um arquivo passado como argumento, e --annotate marca no próprio texto as linhas com problema.
4. Para testar o provisionamento de novo em uma instância em execução, sem criar outra, redefina o estado do cloud-init: cloud-init clean --logs --reboot. O subcomando clean remove os artefatos do cloud-init "to simulate a clean instance"; no boot seguinte, o cloud-init executa todos os estágios novamente, como na primeira vez. A opção --logs também apaga os logs anteriores, para que a saída da nova execução não se misture com a antiga.
5. Depois da reinicialização, repita o passo 1 para confirmar que a nova execução terminou e, se algo mudou, compare com diff o novo /var/log/cloud-init.log com o anterior.

Resultado esperado

cloud-init status --wait retorna após o provisionamento com código de saída 0, e cloud-init schema --system não relata erros para o user-data ativo.

Limites e base de verificação

Em uma instância de produção, cloud-init clean não descarta dados de usuário por si só, mas redefine os marcadores de identidade do host usados para decidir "is this the first boot" (com --machine-id, também /etc/machine-id). Isso se destina à clonagem de golden images e a testes, não à operação rotineira; trate-o como um passo de laboratório. --reboot é necessário para que a reexecução comece automaticamente; sem ele, é preciso chamar manualmente cloud-init init.