Cómo escribir scripts de administración idempotentes: comprobar antes de cambiar, archivos drop-in y comentarios marcadores

Objetivo

Hacer que un script de administración se pueda volver a ejecutar sin riesgo: aplicarlo dos veces produce el mismo estado final que aplicarlo una sola vez, sin líneas duplicadas, sin instalaciones de paquetes repetidas y sin errores en la segunda ejecución.

Requisitos previos

Acceso de lectura al estado actual de aquello que el script modifica (archivo, paquete, clave del registro, servicio) y una forma de escribir archivos de manera atómica (escribir en una ruta temporal y luego moverla o renombrarla).

Pasos

1. Comprobar antes de cambiar. Antes de añadir una línea, crear un usuario o instalar un paquete, consulta si ya existe y compáralo con el valor deseado. En bash: grep -qxF -- "$line" "$file" || printf '%s\n' "$line" >> "$file". En PowerShell: if (-not (Get-LocalUser -Name $name -ErrorAction SilentlyContinue)) { New-LocalUser $name ... }. Omite el cambio por completo cuando la comprobación ya coincide; no confíes en que el comando subyacente falle de forma controlada al repetirse.
2. Preferir un archivo drop-in a editar uno compartido. Cuando el destino lo admita (las unidades de systemd leen un directorio de drop-ins <name>.d/*.conf y combinan esos archivos, según el manual, "in the alphanumeric order" después de la unidad principal; sudoers lee /etc/sudoers.d/*; muchos demonios leen un directorio include), escribe o reemplaza tu propio archivo completo en lugar de buscar y editar el de otro. Al volver a ejecutar el script solo se sobrescribe ese archivo, y nunca se acumulan ediciones duplicadas dentro de un archivo que no es tuyo. Un drop-in de systemd solo surte efecto tras ejecutar systemctl daemon-reload; un drop-in de sudoers debe pasar visudo -cf <file> antes de moverlo a su ubicación definitiva, porque un error de sintaxis en él puede dejar sudo inutilizable para todos, y los archivos cuyo nombre contiene un punto se ignoran.
3. Cuando haya que editar un archivo compartido, delimitar la edición con comentarios marcadores. Encierra el bloque que gestionas entre marcadores reconocibles, por ejemplo # BEGIN managed-by-agent-x / # END managed-by-agent-x, y en cada ejecución reemplaza todo lo que haya entre ellos en lugar de añadir al final. Así la edición es idempotente y se puede retirar limpiamente.
4. Escribir el contenido nuevo en un archivo temporal y renombrarlo a su destino (mv en POSIX; en Windows, Move-Item -Force tras Set-Content -Path $tmp, cuya atomicidad no está garantizada) en lugar de editar in situ, de modo que una ejecución interrumpida a mitad de la escritura no deje una configuración a medias. Crea el archivo temporal en el directorio del destino (un renombrado es atómico solo dentro de un mismo sistema de archivos) y establece propietario y permisos antes de renombrar: mktemp crea los archivos con modo 0600.
5. Condicionar los pasos destructivos a la comprobación, no a la "primera ejecución". Un indicador de "primera ejecución" puede divergir del estado real (una edición manual, una ejecución que falló a medias); comprueba el propio destino.
6. Registrar qué cambió y qué ya era correcto, para que el registro de una repetición muestre claramente "0 changes made" en lugar de parecer idéntico al de una primera ejecución correcta.

Resultado esperado

Ejecutar el script N veces deja el mismo estado final que ejecutarlo una vez; el registro de una ejecución repetida muestra comprobaciones sin efecto en lugar de escrituras repetidas; una ejecución que falló parcialmente puede simplemente volver a ejecutarse.

Límites y base de verificación

La idempotencia cubre las escrituras del propio script; no protege frente a que otro proceso o administrador modifique el mismo archivo de forma concurrente: combínala con el patrón de bloqueo para ejecuciones concurrentes. La edición con comentarios marcadores solo funciona en formatos de texto donde añadir comentarios es seguro; los formatos binarios o de configuración con esquema estricto requieren, en su lugar, el enfoque de drop-in.