Основные команды Jenkins CLI для управления заданиями и контроля

Jenkins, являясь ведущим сервером автоматизации с открытым исходным кодом, предоставляет мощные механизмы для управления конвейерами CI/CD. Хотя веб-интерфейс отлично подходит для визуального контроля, административная эффективность часто требует автоматизации, особенно при работе с сотнями заданий или повторяющимися задачами настройки. Именно здесь Интерфейс командной строки Jenkins (CLI) становится незаменимым.

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

Настройка Jenkins CLI

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

1. Загрузка jenkins-cli.jar

Клиент CLI обычно находится непосредственно на вашем сервере Jenkins по определенному конечный точке. Вы можете загрузить его с помощью wget или curl:

wget http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar
# ИЛИ с помощью curl
curl -O http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar

2. Методы аутентификации

Соединения Jenkins CLI требуют аутентификации. Самым безопасным и рекомендуемым методом является использование API-токена, а не простого пароля пользователя.

Чтобы сгенерировать API-токен, перейдите в User Settings > Configure > API Token в веб-интерфейсе Jenkins.

Все последующие команды будут требовать флагов аутентификации, обычно с использованием флагов -s (URL сервера) и -auth (учетные данные аутентификации):

java -jar jenkins-cli.jar -s http://your-jenkins-url:8080 -auth USERNAME:API_TOKEN <command>

Совет: В целях безопасности храните свой API-токен в защищенной переменной среды или используйте метод аутентификации по SSH-ключу, если он настроен, вместо того, чтобы вводить его непосредственно в скрипты.

Основные команды для поиска заданий

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

Вывод списка всех заданий: list-jobs

Эта команда отображает имена всех заданий, настроенных на сервере Jenkins master.

java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH list-jobs

Получение конфигурации задания: get-job

Задания Jenkins определяются XML-файлами конфигурации. Команда get-job позволяет получить это XML-определение, что важно для создания новых заданий на основе шаблонов.

# Получить конфигурацию для 'my-template-job' и сохранить ее в файл
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job my-template-job > template-config.xml

Основные команды управления заданиями

Эти команды обрабатывают фундаментальные операции жизненного цикла заданий Jenkins.

1. Создание нового задания: create-job

Команда create-job требует имя нового задания и XML-файл конфигурации, определяющий его параметры, шаги сборки и триггеры.

Предварительные условия: У вас должен быть действительный XML-файл конфигурации (например, new-config.xml), обычно полученный путем изменения шаблона, полученного с помощью get-job.

# Пример: Создать новое задание с именем 'project-feature-branch', используя локальный XML-файл
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job project-feature-branch < new-config.xml

2. Копирование существующего задания: copy-job

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

# Синтаксис: copy-job ИМЯ_ИСХОДНОГО_ЗАДАНИЯ ИМЯ_ЦЕЛЕВОГО_ЗАДАНИЯ
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job original-pipeline new-dev-pipeline

3. Включение и отключение заданий: enable-job и disable-job

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

# Команда для прекращения дальнейших запланированных или запущенных сборок для обслуживания
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job legacy-project-build

# Команда для повторной активации задания
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job legacy-project-build

4. Удаление задания: delete-job

Эта команда навсегда удаляет задание из экземпляра Jenkins, включая его историю сборок и конфигурацию. Используйте эту команду с осторожностью.

# Окончательное удаление задания
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job obsolete-test-job

Предупреждение: Команда delete-job выполняется немедленно без дополнительного подтверждения в среде CLI. Убедитесь, что ваши скрипты включают соответствующие шаги проверки перед выполнением этой команды.

Запуск и мониторинг сборок

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

Запуск сборки: build

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

# Запуск простой, непараметризованной сборки
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build nightly-deploy

# Запуск параметризованного задания с передачей параметров
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build integration-test -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

Примечание: Если вы используете флаг -s с build, CLI будет ждать завершения сборки и сообщит код выхода. В противном случае команда возвращается немедленно после постановки сборки в очередь.

Просмотр статуса сборки: get-job и console

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

Чтобы просмотреть вывод консоли для определенной сборки с номером:

# Получить вывод консоли для сборки №55 задания 'my-job'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console my-job 55

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

Эффективное использование Jenkins CLI требует принятия определенных лучших практик для обеспечения стабильности и безопасности:

1. Скриптинг и автоматизация

Истинная мощь CLI заключается в сценариях оболочки (shell scripting). Используйте такие команды, как get-job, изменяйте полученный XML с помощью таких инструментов, как sed или awk, а затем возвращайте измененную конфигурацию с помощью create-job или reload-job.

**Пример рабочего процесса (Копирование, Изменение и Создание):
**
1. Получить шаблон: get-job template-job > tmp.xml
2. Используйте sed для замены заполнителей (например, имени проекта, URL репозитория) в tmp.xml.
3. Создать новое задание: create-job new-job < tmp.xml

2. Обработка обновлений конфигурации

Чтобы обновить конфигурацию существующего задания с помощью XML-файла, используйте команду reload-job. Это безопаснее, чем удалять и пересоздавать задание, поскольку это сохраняет историю сборок.

# Обновить 'project-a', используя локально измененный файл конфигурации
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH reload-job project-a < updated-config.xml

3. Обработка ошибок

Всегда проверяйте код выхода ($?) после выполнения команды CLI в ваших скриптах. Код возврата 0 означает успех; любой ненулевой код указывает на ошибку. Это жизненно важно для надежной автоматизации и отладки.

Резюме

Jenkins CLI предоставляет надежный, скриптируемый интерфейс для управления заданиями, позволяя администраторам автоматизировать повторяющиеся задачи, управлять миграцией конфигураций и интегрировать администрирование Jenkins в более крупные скрипты развертывания CI/CD. Используя такие команды, как copy-job, create-job, delete-job и build, вы можете добиться значительной эффективности и поддерживать согласованность в ваших средах Jenkins.