Skip to Content
Building OsScripts de arranque

Scripts de arranque

os.startup_scripts crea trabajo one-shot systemd acotado para la imagen resultante. Cada entrada declara un comando shell, paquetes requeridos, usuario de ejecución y unidad de orden.

Los scripts de arranque son código con capacidad root salvo que run_as indique lo contrario. Deben recibir la misma revisión que cualquier script de instalación.

Forma canónica

{
  "os": {
    "startup_scripts": [
      {
        "name": "write-build-marker",
        "description": "Create a local readiness marker after networking is available.",
        "command": "set -Eeuo pipefail\ninstall -d -m 0755 /var/lib/example\nprintf '%s\\n' ready > /var/lib/example/build-ready",
        "packages": [],
        "run_as": "root",
        "after": "network-online.target"
      }
    ]
  }
}

Los campos son description y command, no el campo legacy script. run_as y after también usan snake_case. after es una cadena de unidad systemd, no un array.

El esquema acepta como máximo 32 entradas y un tamaño de comando acotado. La validación rechaza comandos vacíos y bytes NUL, pero no hace seguro ni idempotente el contenido shell.

Diseña para reintentos y fallo parcial

Un arranque puede interrumpirse después de que algunos efectos secundarios ya ocurrieron. Escribe scripts para que otra invocación complete con seguridad o salga con un estado claro e inspeccionable.

Patrones buenos incluyen:

  • escribir en un archivo temporal, verificarlo y renombrar de forma atómica;
  • comprobar si usuarios, directorios o entradas de configuración ya existen;
  • usar install para owner y modo explícitos;
  • aplicar set -Eeuo pipefail y manejar resultados distintos de cero esperados de forma deliberada;
  • usar timeouts de red acotados y un recuento finito de reintentos; y
  • escribir un marcador de readiness solo después de que todos los pasos requeridos tengan éxito.

No confíes en sleep como comprobación de readiness. Sondea la dependencia real.

Descargas externas

Evita curl ... | sh. Si el first boot debe obtener un artefacto:

  1. usa HTTPS con verificación de certificado;
  2. fija la versión esperada del artefacto o fuente;
  3. verifica un digest criptográfico o firma aprobada antes de ejecutar;
  4. establece timeouts de conexión y total;
  5. falla cerrado si la verificación falla; y
  6. evita registrar credenciales o URL firmadas.

Para comportamiento verdaderamente offline o reproducible, incluye contenido revisado en la imagen o un repositorio de paquetes aprobado en lugar de descargar en first boot.

Secretos

Nunca incrustes credenciales en texto plano en la receta, comando, URL o marcador generado. El JSON de receta y los logs de compilación son evidencia retenida y pueden ser visibles para operadores. Usa un mecanismo aprobado de inscripción o entrega de secretos en tiempo de despliegue y acota la credencial resultante al destino.

Identidad de ejecución

Prefiere una cuenta de servicio sin privilegios. Si se requiere root, reduce el comando al paso privilegiado más pequeño y establece propiedad explícita de archivos. Confirma que run_as nombra una cuenta creada antes de que arranque la unidad.

Verificación

Prueba resultados y no solo el código de salida de la unidad:

{
  "type": "file_contains",
  "description": "The startup unit wrote its readiness marker.",
  "params": {
    "path": "/var/lib/example/build-ready",
    "content": "ready"
  }
}

Prueba también un segundo arranque, una dependencia no disponible y recuperación tras un first run interrumpido. Inspecciona systemctl status y el journal de la unidad en caso de fallo.

ServiciosUsuarios locales en la imagen