Como escrever scripts de administração idempotentes: verificar antes de alterar, arquivos drop-in e comentários marcadores

Objetivo

Tornar um script de administração seguro para reexecução: aplicá-lo duas vezes leva ao mesmo estado final que aplicá-lo uma vez, sem linhas duplicadas, sem instalações repetidas de pacotes e sem erro na segunda execução.

Pré-requisitos

Acesso de leitura ao estado atual de tudo o que o script altera (arquivo, pacote, chave de registro, serviço); uma forma de gravar arquivos de modo atômico (gravar em um caminho temporário e depois mover/renomear).

Passos

1. Verifique antes de alterar. Antes de adicionar uma linha, criar um usuário ou instalar um pacote, consulte se isso já existe e compare com o valor desejado. Em bash: grep -qxF -- "$line" "$file" || printf '%s\n' "$line" >> "$file". Em PowerShell: if (-not (Get-LocalUser -Name $name -ErrorAction SilentlyContinue)) { New-LocalUser $name ... }. Pule a alteração por completo quando a verificação já coincidir; não conte com o comando subjacente falhar de forma tolerável numa repetição.
2. Prefira um arquivo drop-in a editar um arquivo compartilhado. Quando o alvo permite (as units do systemd leem um diretório drop-in <name>.d/*.conf e mesclam esses arquivos, nas palavras do manual, "in the alphanumeric order" (em ordem alfanumérica) depois da unit principal; o sudoers lê /etc/sudoers.d/*; muitos daemons leem um diretório de include), grave ou substitua um arquivo inteiro seu, em vez de procurar e editar o arquivo de outra pessoa. Reexecutar o script sobrescreve apenas esse arquivo, sem acumular edições duplicadas dentro de um arquivo que não é seu. Um drop-in do systemd só passa a valer depois de systemctl daemon-reload; um drop-in do sudoers deve passar por visudo -cf <file> antes de ser movido para o lugar, pois um erro de sintaxe ali pode quebrar o sudo para todos, e arquivos cujo nome contém um ponto são ignorados.
3. Se for preciso editar um arquivo compartilhado, delimite sua edição com comentários marcadores. Envolva o bloco que você controla entre marcadores reconhecíveis, por exemplo # BEGIN managed-by-agent-x / # END managed-by-agent-x, e a cada execução substitua tudo o que está entre os marcadores em vez de acrescentar. Assim a edição continua idempotente e pode ser removida de forma limpa.
4. Grave o novo conteúdo em um arquivo temporário e renomeie-o para o destino (mv em POSIX; no Windows, Move-Item -Force depois de Set-Content -Path $tmp, o que não tem garantia de atomicidade) em vez de editar no próprio arquivo, para que uma execução interrompida no meio da gravação não deixe uma configuração pela metade. Crie o arquivo temporário no diretório do destino (a renomeação só é atômica dentro de um único sistema de arquivos) e defina dono e permissões antes de renomear: o mktemp cria arquivos com modo 0600.
5. Condicione as etapas destrutivas à verificação, não a uma "primeira execução". Um marcador de "primeira execução" pode divergir do estado real (uma edição manual, uma execução que falhou parcialmente); teste o próprio alvo.
6. Registre no log o que mudou e o que já estava correto, para que o log de uma reexecução mostre claramente "0 changes made" (nenhuma alteração feita) em vez de parecer idêntico ao de uma primeira execução bem-sucedida.

Resultado esperado

Executar o script N vezes deixa o mesmo estado final que executá-lo uma vez; o log de uma repetição mostra verificações sem efeito (no-op) em vez de gravações repetidas; uma execução com falha parcial pode simplesmente ser repetida.

Limites e base de verificação

A idempotência cobre as gravações do próprio script; ela não protege contra outro processo ou administrador alterando o mesmo arquivo ao mesmo tempo. Combine-a com o padrão de locking para execuções concorrentes. A edição com comentários marcadores só funciona em formatos de texto nos quais é seguro adicionar comentários; formatos binários ou de configuração com esquema rígido exigem, em vez disso, a abordagem drop-in.