Безопасная перезагрузка конфигураций Jenkins без перезапуска
Перезагрузите конфигурацию Jenkins с диска безопасно, узнайте, когда безопасный перезапуск лучше, и избегайте рискованных сокращений через Script Console.
Безопасная перезагрузка конфигураций Jenkins без перезапуска
Перезагрузка конфигурации Jenkins звучит безобидно, пока вы не сделаете это на загруженном контроллере и не обнаружите, что не каждое изменение можно применить чисто, пока выполняются задания. Правильная команда зависит от того, что изменилось.
Если вы редактировали XML-файлы в JENKINS_HOME, восстановили задания из резервной копии или изменили файлы вне веб-интерфейса, Jenkins может перезагрузить конфигурацию с диска. Если вы установили или обновили плагины, изменили параметры Java или вам нужно обновить состояние выполнения, безопасный перезапуск обычно является лучшим инструментом. Это разные операции.
Вводящее в заблуждение сокращение, которого следует избегать, — это System.exit(10) в Script Console. Это может заставить супервизор процессов, сервлет-контейнер или обёртку службы перезапустить Jenkins в зависимости от того, как запущен Jenkins, но это не чистая команда "перезагрузить конфигурацию". Это может прервать работу и скрывает намерение. Вместо этого используйте Jenkins CLI или встроенные действия управления.
Перезагрузка конфигурации с диска с помощью CLI
Самая понятная команда — reload-configuration:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration
Это заставляет Jenkins отбросить загруженную конфигурацию и прочитать её заново с диска. Это полезно после контролируемых изменений файлов, таких как восстановление конфигурации задания или применение конфигурации, сгенерированной автоматизацией.
Перед выполнением проверьте три вещи:
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
Учётная запись должна иметь административные права для перезагрузки конфигурации. Не используйте личный административный токен с чьего-то ноутбука для рутинной автоматизации. Используйте управляемую учётную запись администратора, храните токен в секретном хранилище и меняйте его в соответствии с вашей политикой.
Если вы предпочитаете веб-интерфейс, используйте Manage Jenkins и опцию перезагрузки, если она доступна в вашей версии Jenkins и установленных компонентах. CLI проще для аудита, потому что команда может быть в runbook.
Когда безопасный перезапуск — лучший выбор
Безопасный перезапуск ожидает завершения выполняющихся сборок, а затем перезапускает Jenkins. Это медленнее, чем перезагрузка, но более честно, когда состояние выполнения должно быть перестроено.
Используйте безопасный перезапуск после установки или обновления плагинов, изменений параметров Java, обновления ядра Jenkins или поведения, которое проявляется только после полного перезапуска контроллера.
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" safe-restart
Вы также можете использовать конечную точку /safeRestart, если ваше окружение это позволяет, но форма CLI проще для стандартизации.
Не обещайте нулевого времени простоя. Перезагрузка может кратковременно повлиять на интерфейс, а безопасный перезапуск намеренно перезапускает контроллер после завершения сборок. Если агенты отключаются или плагины ведут себя плохо, пользователи могут заметить. Планируйте операцию, когда радиус поражения приемлем.
Более безопасный runbook перезагрузки
Сначала объявите окно обслуживания, даже если оно короткое. Затем проверьте, что выполняется:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs
Для быстрой проверки очереди используйте Groovy через CLI:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
println "Queued: ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
computer.executors.findAll { it.isBusy() }.each { executor ->
println "Running on ${computer.displayName}: ${executor.currentExecutable}"
}
}
EOF
Сделайте резервную копию конфигурации, которую вы собираетесь использовать. Как минимум, имейте свежую резервную копию JENKINS_HOME, особенно config.xml, каталогов заданий, метаданных учётных данных и состояния плагинов. Будьте осторожны с файлами учётных данных; защищайте резервные копии как секреты.
Выполните перезагрузку:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration
Затем проверьте, что контроллер отвечает:
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
Проверьте системный журнал и репрезентативное задание, прежде чем считать работу завершённой. Успешная перезагрузка всё ещё может выявить плохой XML задания, отсутствующий плагин или проблему с правами.
О скриптах Groovy для перезагрузки
Script Console мощный, потому что он выполняется внутри контроллера Jenkins. Это также причина, по которой он требует осторожности. Любой пользователь консоли скриптов может читать секреты, изменять задания, отключать средства безопасности или сломать контроллер.
Если вам нужен Groovy для проверки, оставьте его только для чтения и коротким. Например:
println Jenkins.instance.version
println Jenkins.instance.items.size()
println Jenkins.instance.queue.items.size()
Избегайте недокументированных внутренних вызовов перезагрузки, если вы не протестировали их на своей версии Jenkins и плагинах. Внутренние API могут меняться, и специфичные для плагинов методы перезагрузки могут не перезагрузить то состояние, которое вас интересует.
Для настроек Configuration as Code используйте документированный механизм перезагрузки плагина, а не общую перезагрузку Jenkins. У JCasC есть своя модель и поведение валидации, и файл конфигурации, который выглядит корректным на диске, всё равно может не примениться.
Что делать, если перезагрузка пошла не так
Если Jenkins возвращается с отсутствующими заданиями, сломанными представлениями или ошибками плагинов, не продолжайте нажимать перезагрузку. Захватите системный журнал, запишите время и сравните изменённые файлы с резервной копией. Распространённые причины: неправильно сформированный XML, конфигурация задания, ссылающаяся на плагин, который больше не установлен, или ручные правки, сделанные, пока Jenkins всё ещё записывал файлы.
Если интерфейс нестабилен, но процесс работает, безопасный перезапуск может очистить временное состояние. Если конфигурация действительно плохая, сначала восстановите предыдущие файлы, затем перезагрузите или перезапустите.
Самый безопасный шаблон прост: используйте reload-configuration для изменений конфигурации на диске, используйте safe-restart для изменений выполнения и плагинов, и оставляйте Script Console для продуманных административных скриптов, которые вы можете объяснить построчно.