Освоение консоли скриптов Jenkins Groovy для продвинутого системного администрирования

Jenkins является основой современных CI/CD конвейеров, предлагая непревзойденную гибкость благодаря своей расширяемой архитектуре. В то время как большинство администраторов полагаются на графический пользовательский интерфейс (GUI) или декларативные скрипты конвейеров, Консоль скриптов Jenkins, основанная на Groovy, предоставляет прямой низкоуровневый интерфейс для немедленной интроспекции системы, внесения изменений в конфигурацию и продвинутой автоматизации, выходящей за рамки стандартных шагов конвейера. Эта консоль незаменима для системных администраторов, которым необходимо устранять производственные проблемы, выполнять массовые обновления или напрямую управлять основной системой Jenkins.

Это руководство поможет вам использовать консоль скриптов Groovy для выполнения мощных административных задач, превращая сложные ручные вмешательства в эффективные, автоматизируемые операции. Освоение этого инструмента является ключом к переходу от стандартного управления конвейерами к истинному системному администрированию Jenkins.

Понимание консоли скриптов Jenkins

Консоль скриптов Jenkins (Управление Jenkins -> Консоль скриптов) предоставляет прямой шлюз для взаимодействия с объектной моделью работающего мастера Jenkins с использованием Groovy, предпочтительного языка сценариев Jenkins. Она позволяет администраторам получать доступ практически к любому объекту в среде выполнения Jenkins, включая системные конфигурации, объекты заданий, записи сборок и подключенные агенты.

Зачем использовать консоль скриптов?

Немедленное выполнение: Запускайте скрипты мгновенно, не дожидаясь запуска задания или конвейера.
Отладка системы: Получайте доступ к внутреннему состоянию, журналам и деталям конфигурации, которые не доступны через GUI.
Массовые операции: Быстро изменяйте несколько заданий, перенастраивайте агентов или очищайте старые данные во всем экземпляре.
Прототипирование скриптов: Тестируйте логику Groovy перед встраиванием ее в общие библиотеки или декларативные конвейеры.

Меры предосторожности: Сила прямого доступа

ПРЕДУПРЕЖДЕНИЕ: Скрипты, выполняемые в консоли, работают с полными административными привилегиями на мастере Jenkins. Плохо написанный скрипт может повредить конфигурации, удалить сборки или вызвать сбой экземпляра Jenkins. Всегда тщательно тестируйте сложные скрипты сначала в непроизводственной среде.

Основные объекты Groovy и доступ к API

Сила консоли заключается в прямом доступе к основным объектам Jenkins. Эти объекты неявно доступны в среде выполнения Groovy:

Jenkins.instance: Основной объект-одиночка Jenkins, представляющий работающий мастер.
Hudson: Псевдоним для Jenkins.
Jenkins.instance.getItemByFullName('JobName'): Доступ к конкретному заданию.
Jenkins.instance.getComputer('AgentName'): Доступ к конкретному агенту (узлу).

Доступ к экземпляру Jenkins

Чтобы убедиться, что у вас есть доступ, самой простой командой будет вывод версии Jenkins:

println "Jenkins Version: ${Jenkins.instance.version}"
println "Running as user: ${Jenkins.instance.getAuthentication().getName()}"

Практические административные скрипты

Вот несколько действенных скриптов, демонстрирующих продвинутое административное управление через консоль скриптов.

1. Массовое обновление конфигураций заданий

Этот скрипт перебирает все существующие задания и изменяет определенный элемент конфигурации, например, изменяет описание или обновляет URL SCM для нескольких проектов одновременно. Этот пример добавляет стандартизированный суффикс к описанию всех Freestyle проектов.

import hudson.model.FreeStyleProject

final String SUFFIX = " [Automated Update]"

def count = 0

Jenkins.instance.getAllItems(FreeStyleProject.class).each { job ->
    if (!job.getDescription().endsWith(SUFFIX)) {
        job.setDescription(job.getDescription() + SUFFIX)
        job.save()
        println "Updated description for: ${job.getName()}"
        count++
    }
}
println "\nFinished. Total jobs updated: ${count}"

2. Управление агентами Jenkins (узлами)

Администраторам часто требуется временно отключать агентов для обслуживания или вручную отключать некорректно работающие узлы.

Временное отключение агента

Этот скрипт отключает агента, предотвращая запуск на нем новых сборок, но позволяя завершить выполнение текущих сборок.

import hudson.model.Computer

final String AGENT_NAME = "my-specific-agent"

def agent = Computer.instance.get(AGENT_NAME)

if (agent) {
    // Set temporarily offline
    agent.setTemporarilyOffline(true, "Maintenance started by Admin Script.")
    println "Agent '${AGENT_NAME}' set to temporarily offline."
} else {
    println "Agent '${AGENT_NAME}' not found."
}

Принудительное отключение агента и остановка выполняющихся задач

Если агент необходимо немедленно отключить, вы можете принудительно отключить его и остановить все выполняющиеся сборки, которые будут помечены как неудачные или отмененные в зависимости от конфигурации.

import hudson.model.Computer

final String AGENT_NAME = "unresponsive-node-01"

def agent = Computer.instance.get(AGENT_NAME)

if (agent) {
    // Force offline and disconnect running tasks immediately
    agent.doDoDisconnect()
    println "Agent '${AGENT_NAME}' forcefully disconnected."
} else {
    println "Agent '${AGENT_NAME}' not found."
}

3. Манипулирование выполняющимися сборками

Когда критически важная сборка зависает или требует немедленной отмены, консоль скриптов предоставляет самый быстрый путь.

Отмена конкретной выполняющейся сборки

Чтобы отменить сборку, идентифицированную по ее полному пути (например, PipelineJob/BuildNumber):

// Example: Aborting build #5 of the job named 'CriticalDeploy'
final String JOB_NAME = "CriticalDeploy"
final int BUILD_NUMBER = 5

def job = Jenkins.instance.getItemByFullName(JOB_NAME)

def build = job.getBuild(BUILD_NUMBER)

if (build && build.isBuilding()) {
    build.doCancel()
    println "Build ${JOB_NAME}#${BUILD_NUMBER} has been cancelled."
} else {
    println "Build ${JOB_NAME}#${BUILD_NUMBER} is not running or does not exist."
}

4. Очистка старых записей сборок

Управление дисковым пространством часто требует агрессивной очистки старых сборок. Этот скрипт идентифицирует и удаляет все сборки старше 30 дней для указанного задания.

import hudson.model.Job
import java.util.concurrent.TimeUnit

final String TARGET_JOB = "LegacyArchivingJob"
final int DAYS_TO_KEEP = 30

def job = Jenkins.instance.getItemByFullName(TARGET_JOB)

if (job instanceof Job) {
    long cutoffTime = System.currentTimeMillis() - TimeUnit.DAYS.toMillis(DAYS_TO_KEEP)
    int deletedCount = 0

    job.getBuilds().each { build ->
        if (build.getTimeInMillis() < cutoffTime) {
            println "Deleting old build: ${build.getDisplayName()}"
            build.delete()
            deletedCount++
        }
    }
    println "\nCleanup complete. Deleted ${deletedCount} builds for ${TARGET_JOB}."
} else {
    println "Job '${TARGET_JOB}' not found or is not a standard Job type."
}

Лучшие практики написания скриптов для консоли

При выполнении системных изменений соблюдайте следующие лучшие практики для поддержания стабильности:

Используйте .save(): Всякий раз, когда вы изменяете объект конфигурации (например, Задание или Представление), вы должны вызвать .save() для этого объекта, чтобы изменение сохранилось после перезапуска Jenkins. Конфигурации хранятся в памяти до сохранения.
Проверяйте существование объектов: Всегда оборачивайте вызовы API проверками (if (object) или try-catch), чтобы предотвратить сбой консоли, если вы ошиблись в названии задания или агента.
Избегайте бесконечных циклов: Скрипты выполняются синхронно. Не запускайте длительные циклы или процессы напрямую в консоли, если вы не уверены, что они завершатся быстро, так как это блокирует UI консоли.
Используйте встроенные методы: Объекты Groovy Jenkins часто имеют специальные вспомогательные методы (например, doCancel() или doDoDisconnect()). Используйте их вместо попыток вручную манипулировать внутренним состоянием, где это возможно.
Используйте тихий режим (если применимо): При выполнении массовых операций, генерирующих избыточные обновления статуса сборки, рассмотрите, оправдано ли временное отключение функций уведомлений о событиях, хотя это обычно требует более глубокого системного доступа, чем стандартное администрирование.

Освоение консоли скриптов Jenkins Groovy позволяет перейти от простого использования Jenkins к активному администрированию и оптимизации его ядра. Практикуя эти методы, вы получаете детальный контроль над своим сервером автоматизации, значительно повышая его отзывчивость во время сложных периодов обслуживания или в чрезвычайных ситуациях.