CLI против Groovy: выбор правильного инструмента для удаленных задач Jenkins

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

Практический выбор обычно прост: используйте Jenkins CLI для ограниченных операций с заданиями и контроллером, а Groovy — только когда вам нужен доступ к API Jenkins, который не предоставляет CLI.

Jenkins Command Line Interface (CLI)

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

Возможности и сценарии использования

Простые атомарные операции: Идеально подходит для выполнения одиночных простых команд, таких как список заданий, сборка конкретного задания или получение журналов сборки.
Скриптовые триггеры сборок: Легко интегрируйте сборки Jenkins во внешние скрипты или другие инструменты автоматизации.
Проверка статуса: Быстро запрашивайте статус контроллеров Jenkins, агентов или заданий.
Администрирование: Выполняйте основные административные задачи, такие как управление плагинами или перенастройка Jenkins.
Интеграция: Бесшовно интегрируется с shell-скриптами, cron-задачами и другими автоматизациями на основе командной строки.

Ограничения

Ограниченная сложность: Не подходит для сложной логики, условного выполнения или запутанных рабочих процессов, требующих управления состоянием.
Отсутствие постоянного состояния: Каждая команда CLI выполняется независимо; она не сохраняет контекст или состояние между несколькими вызовами.
Более крутая кривая обучения для сложных задач: Хотя простые команды интуитивно понятны, создание сложных последовательностей автоматизации только с помощью команд CLI может стать громоздким.

Начало работы с Jenkins CLI

Загрузите клиент CLI: Вы можете загрузить jenkins-cli.jar из вашего экземпляра Jenkins по адресу http://<JENKINS_URL>/jnlpJars/jenkins-cli.jar.
Аутентификация: Вам необходимо аутентифицировать ваши запросы CLI. Это можно сделать с помощью API-токенов или учетных данных (имя пользователя/пароль).
Выполнение команд: Используйте Java для запуска .jar файла с соответствующими командами и аргументами.

Пример: Список всех заданий Jenkins

java -jar jenkins-cli.jar -s http://<JENKINS_URL>/ -auth <USERNAME>:<API_TOKEN> list-jobs

Пример: Запуск сборки для конкретного задания

java -jar jenkins-cli.jar -s http://<JENKINS_URL>/ -auth <USERNAME>:<API_TOKEN> build <JOB_NAME>

Пример: Получение вывода консоли последней сборки

java -jar jenkins-cli.jar -s http://<JENKINS_URL>/ -auth <USERNAME>:<API_TOKEN> console <JOB_NAME>

Groovy Script Console

Консоль сценариев Groovy Jenkins (часто называемая Script Console или Groovy Console) предоставляет мощную интерактивную среду для выполнения произвольных сценариев Groovy непосредственно на контроллере Jenkins. Это дает вам доступ к внутреннему Java API Jenkins, что позволяет выполнять высокосложную и динамичную автоматизацию, администрирование и даже разработку пользовательских функций.

Возможности и сценарии использования

Сложная логика и рабочие процессы: Выполняйте сложные сценарии с условной логикой, циклами и пользовательской обработкой данных.
Прямой доступ к API: Взаимодействуйте напрямую с основными Java-объектами и API Jenkins для точного контроля.
Манипулирование данными: Запрашивайте данные Jenkins, изменяйте конфигурации и создавайте пользовательские отчеты.
Системное администрирование: Выполняйте расширенные административные задачи, устраняйте неполадки и автоматизируйте сложные процедуры настройки.
Разработка и тестирование плагинов: Полезно для тестирования функциональности плагинов или даже разработки новых.

Ограничения

Проблемы безопасности: Выполнение произвольных сценариев на контроллере Jenkins может представлять значительные риски безопасности, если не управлять ими осторожно. Скрипты должны быть тщательно проверены и протестированы.
Потребление ресурсов контроллера: Тяжелые или неэффективные сценарии могут потреблять значительные ресурсы контроллера, потенциально влияя на производительность Jenkins.
Удаленное выполнение требует осторожности: Вы можете запускать Groovy удаленно через команды Jenkins CLI groovy или groovysh, если это разрешено, но это все равно выполняет мощный код на контроллере.
Требует знания Groovy/Java: Требует твердого понимания Groovy и внутренних API Jenkins.

Начало работы с Groovy Script Console

Доступ к консоли: Перейдите по адресу http://<JENKINS_URL>/script в вашем браузере.
Написание сценариев: Введите или вставьте ваш сценарий Groovy в предоставленную текстовую область.
Выполнение: Нажмите кнопку "Run".
Просмотр результатов: Вывод вашего сценария будет отображен под редактором.

Пример: Получение списка всех заданий и статуса их последней сборки

Jenkins.instance.getAllItems(Job.class).each {
    job -> println "Job: ${job.name}, Last Build Status: ${job.lastBuild?.result ?: 'No builds yet'}"
}

Пример: Обновление описания задания

def jobName = "YourJobName"
def newDescription = "This is an automated description."
def job = Jenkins.instance.getItemByFullName(jobName)

if (job) {
    job.setDescription(newDescription)
    job.save()
    println "Successfully updated description for job: ${jobName}"
} else {
    println "Job '${jobName}' not found."
}

Пример: Отключение задания

def jobName = "JobToDisable"
def job = Jenkins.instance.getItemByFullName(jobName)

if (job instanceof hudson.model.Job) {
    job.setDisabled(true)
    job.save()
    println "Job '${jobName}' has been disabled."
} else {
    println "Job '${jobName}' not found or is not a job type."
}

CLI против Groovy: когда что использовать

Выбор между Jenkins CLI и Groovy Script Console в значительной степени зависит от сложности, объема и характера задачи, которую необходимо выполнить.

Используйте Jenkins CLI, когда:

Вам нужно выполнить быстрые одноразовые действия с вашего локального компьютера или из скрипта.
Ваша задача включает запуск сборок, проверку статуса заданий или получение базовой информации.
Вы интегрируете операции Jenkins во внешние shell-скрипты или инструменты CI/CD, которые ожидают аргументы командной строки.
Вы хотите избежать выполнения сложного кода непосредственно на контроллере Jenkins по соображениям безопасности или ресурсов.
Вам нужно выполнять основные административные задачи, которые напрямую доступны как команды CLI.

Используйте Groovy Script Console, когда:

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

Лучшие практики и соображения

Для Jenkins CLI:

Безопасная аутентификация: Всегда используйте API-токены для аутентификации вместо пароля. Храните токены безопасно.
Параметризация: Сделайте ваши CLI-скрипты надежными, параметризуя URL, учетные данные и имена заданий.
Обработка ошибок: Реализуйте проверки успешности/неудачи выполнения команд в ваших вызывающих скриптах.

Для Groovy Script Console:

Безопасность прежде всего: Никогда не запускайте непроверенные скрипты. Тщательно проверяйте любой скрипт перед выполнением. Рассмотрите возможность ограничения доступа к Script Console.
Тщательное тестирование: Всегда сначала тестируйте свои скрипты в непроизводственной среде.
Управление ресурсами: Помните о влиянии ваших скриптов на производительность контроллера Jenkins. Избегайте длительных, ресурсоемких операций непосредственно в консоли без надлежащей оптимизации или фонового выполнения.
Используйте поддерживаемый доступ к API: В текущем коде Jenkins предпочитайте Jenkins.get() из jenkins.model.Jenkins при написании переиспользуемого Groovy. Многие старые фрагменты все еще используют Jenkins.instance; проверьте вашу версию Jenkins и импорты.

Вывод

Используйте Jenkins CLI, когда задача соответствует существующей команде, такой как сборка задания, список заданий или чтение вывода консоли. Используйте Groovy, когда вам нужны прямые изменения на уровне объектов внутри Jenkins, и рассматривайте каждый скрипт как административный код уровня контроллера. Сначала тестируйте Groovy на непроизводственном контроллере, держите скрипты небольшими и сохраняйте финальную версию в системе контроля версий.