Recargar Configuraciones de Jenkins de Forma Segura Sin Necesidad de Reiniciar
Recargue la configuración de Jenkins desde el disco de forma segura, sepa cuándo es mejor un reinicio seguro y evite los atajos riesgosos de la Consola de Scripts.
Recargar Configuraciones de Jenkins de Forma Segura Sin Necesidad de Reiniciar
Recargar la configuración de Jenkins suena inofensivo hasta que lo haces en un controlador ocupado y descubres que no todos los cambios se pueden aplicar limpiamente mientras los trabajos están en ejecución. El comando correcto depende de lo que haya cambiado.
Si editaste archivos XML en JENKINS_HOME, restauraste trabajos desde una copia de seguridad o cambiaste archivos fuera de la interfaz web, Jenkins puede recargar la configuración desde el disco. Si instalaste o actualizaste complementos, cambiaste opciones de Java o necesitas actualizar el estado en tiempo de ejecución, un reinicio seguro suele ser la herramienta más adecuada. Son operaciones diferentes.
El atajo engañoso que debes evitar es System.exit(10) en la Consola de Scripts. Puede hacer que un supervisor de procesos, un contenedor de servlets o un envoltorio de servicio reinicien Jenkins dependiendo de cómo se inicie Jenkins, pero no es un comando limpio de "recargar configuración". Puede interrumpir el trabajo y oculta la intención. Utiliza la CLI de Jenkins o las acciones de gestión integradas en su lugar.
Recargar configuración desde el disco con la CLI
El comando más claro es reload-configuration:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration
Esto le indica a Jenkins que descarte la configuración cargada y la lea nuevamente desde el disco. Es útil después de cambios controlados en archivos, como restaurar una configuración de trabajo o aplicar configuración generada por automatización.
Antes de ejecutarlo, verifica tres cosas:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null
La cuenta necesita permiso administrativo para la recarga de configuración. No uses un token de administrador personal de la computadora portátil de alguien para la automatización rutinaria. Utiliza una cuenta de administrador gestionada, guarda el token en un almacén de secretos y gíralo según tu política.
Si prefieres la interfaz web, usa Manage Jenkins y la opción de recarga cuando esté disponible en tu versión de Jenkins y componentes instalados. La CLI es más fácil de auditar porque el comando puede estar en un runbook.
Cuándo el reinicio seguro es la mejor opción
Un reinicio seguro espera a que las compilaciones en ejecución terminen y luego reinicia Jenkins. Es más lento que una recarga, pero es más honesto cuando el estado en tiempo de ejecución debe reconstruirse.
Usa el reinicio seguro después de la instalación o actualización de complementos, cambios en opciones de Java, actualizaciones del núcleo de Jenkins o comportamientos que solo aparecen después de un reinicio completo del controlador.
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" safe-restart
También puedes usar el endpoint /safeRestart si tu entorno lo permite, pero la forma CLI es más fácil de estandarizar.
No prometas cero tiempo de inactividad. Una recarga puede afectar brevemente la interfaz de usuario, y un reinicio seguro reinicia intencionalmente el controlador después de que los trabajos se drenen. Si los agentes se desconectan o los complementos se comportan mal, los usuarios pueden notarlo. Programa la operación cuando el radio de explosión sea aceptable.
Un runbook de recarga más seguro
Primero, anuncia la ventana de mantenimiento, aunque sea corta. Luego verifica qué está en ejecución:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs
Para una verificación rápida de la cola, usa Groovy a través de la CLI:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
println "En cola: ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
computer.executors.findAll { it.isBusy() }.each { executor ->
println "Ejecutando en ${computer.displayName}: ${executor.currentExecutable}"
}
}
EOF
Haz una copia de seguridad de la configuración que estás a punto de usar. Como mínimo, ten una copia de seguridad reciente de JENKINS_HOME, especialmente config.xml, directorios de trabajos, metadatos de credenciales y estado de complementos. Ten cuidado con los archivos de credenciales; protege las copias de seguridad como secretos.
Ejecuta la recarga:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration
Luego verifica que el controlador esté respondiendo:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null
Revisa el registro del sistema y un trabajo representativo antes de dar por terminado el trabajo. Una recarga que se completa con éxito aún puede exponer un XML de trabajo defectuoso, un complemento faltante o un problema de permisos.
Acerca de los scripts de recarga en Groovy
La Consola de Scripts es poderosa porque se ejecuta dentro del controlador de Jenkins. Esa es también la razón por la que merece precaución. Cualquier usuario de la consola de scripts puede leer secretos, modificar trabajos, deshabilitar controles de seguridad o romper el controlador.
Si necesitas Groovy para inspección, mantenlo de solo lectura y breve. Por ejemplo:
println Jenkins.instance.version
println Jenkins.instance.items.size()
println Jenkins.instance.queue.items.size()
Evita llamadas de recarga internas no documentadas a menos que las hayas probado con tu versión de Jenkins y complementos. Las API internas pueden cambiar, y los métodos de recarga específicos de complementos pueden no recargar el estado que te importa.
Para configuraciones de Configuration as Code, usa el mecanismo de recarga documentado del complemento en lugar de una recarga genérica de Jenkins. JCasC tiene su propio modelo y comportamiento de validación, y un archivo de configuración que parece correcto en el disco aún puede fallar al aplicarse.
Qué hacer si la recarga sale mal
Si Jenkins regresa con trabajos faltantes, vistas rotas o errores de complementos, no sigas haciendo clic en recargar. Captura el registro del sistema, anota la hora y compara los archivos modificados con la copia de seguridad. Las causas comunes son XML mal formado, una configuración de trabajo que hace referencia a un complemento que ya no está instalado o ediciones manuales realizadas mientras Jenkins aún escribía archivos.
Si la interfaz de usuario es inestable pero el proceso se está ejecutando, un reinicio seguro puede limpiar el estado transitorio. Si la configuración es realmente incorrecta, restaura los archivos anteriores primero, luego recarga o reinicia.
El patrón más seguro es simple: usa reload-configuration para cambios de configuración en disco, usa safe-restart para cambios en tiempo de ejecución y complementos, y reserva la Consola de Scripts para scripts administrativos deliberados que puedas explicar línea por línea.