Как автоматизировать настройку Jenkins с помощью Docker и конфигурации Jenkins в виде кода

Автор выбрал Фонд Викимедиа для получения пожертвования в рамках программы Write for DOnations.

Введение

Jenkins — один из самых популярных серверов автоматизации с открытым исходным кодом, часто используемый для организации рабочих процессов непрерывной интеграции (CI) и/или непрерывного развертывания (CD).

Настройка Jenkins обычно выполняется вручную с помощью веб-мастера настройки; это может быть медленный, подверженный ошибкам и немасштабируемый процесс. Вы можете увидеть необходимые шаги, выполнив Шаг 4 — Настройка Jenkins из руководства «Как установить Jenkins в Ubuntu 18.04». Более того, конфигурации не могут отслеживаться в системе контроля версий (VCS), такой как Git, и не подлежат тщательному контролю в рамках какого-либо процесса проверки кода.

В этом руководстве вы автоматизируете установку и настройку Jenkins с помощью Docker и метода конфигурации Jenkins как кода (JCasC).

Jenkins использует подключаемую архитектуру для обеспечения большей части своих функций. JCasC использует плагин «Конфигурация как код», который позволяет вам определить желаемое состояние вашей конфигурации Jenkins как один или несколько файлов YAML, устраняя необходимость в мастере установки. При инициализации плагин «Конфигурация как код» настроит Jenkins в соответствии с файлами конфигурации, что значительно сократит время настройки и исключит человеческие ошибки.

Docker — это фактический стандарт для создания и запуска контейнеров, который представляет собой технологию виртуализации, позволяющую последовательно запускать изолированные, автономные приложения в различных операционных системах (ОС) и аппаратных архитектурах. Вы запустите свой экземпляр Jenkins с помощью Docker, чтобы воспользоваться преимуществами этой согласованности и кроссплатформенности.

Это руководство начинается с инструкций по настройке JCasC. Затем вы постепенно добавите файл конфигурации JCasC для настройки пользователей, аутентификации и авторизации конфигурации и, наконец, для защиты вашего экземпляра Jenkins. После завершения этого руководства вы создадите собственный образ Docker, настроенный на использование плагина «Конфигурация как код» при запуске для автоматической настройки и защиты вашего экземпляра Jenkins.

Предварительные условия

Чтобы выполнить это руководство, вам понадобится:

• Доступ к серверу с минимум 2 ГБ ОЗУ и установленным Docker. Это может быть ваша локальная машина разработки, дроплет или любой другой сервер. Выполните Step 1 — Installing Docker из одного из руководств из коллекции «Как установить и использовать Docker», чтобы настроить Docker.

Шаг 1 — Отключение мастера установки

Использование JCasC избавляет от необходимости открывать мастер установки; поэтому на этом первом этапе вы создадите модифицированную версию официального образа jenkins/jenkins , в которой отключен мастер установки. Вы сделаете это, создав Dockerfile и создав на его основе собственный образ Jenkins.

Образ jenkins/jenkins позволяет включать или отключать мастер установки, передавая системное свойство с именем jenkins.install.runSetupWizard через переменную среды JAVA_OPTS . Пользователи образа могут передать переменную среды JAVA_OPTS во время выполнения, используя флаг --env для docker run . Однако при таком подходе бремя отключения мастера установки будет возложено на пользователя образа. Вместо этого вам следует отключить мастер установки во время сборки, чтобы мастер установки был отключен по умолчанию.

Этого можно добиться, создав Dockerfile и используя инструкцию ENV для установки переменной среды JAVA_OPTS .

Сначала создайте новый каталог на своем сервере для хранения файлов, которые вы будете создавать в этом руководстве:

Затем перейдите внутри этого каталога:

Затем с помощью редактора создайте новый файл с именем Dockerfile :

Затем скопируйте следующее содержимое в Dockerfile :

Здесь вы используете инструкцию FROM , чтобы указать jenkins/jenkins:latest в качестве базового образа, и инструкцию ENV , чтобы установить переменную среды JAVA_OPTS .

Сохраните файл и выйдите из редактора, нажав CTRL+X а затем Y

С этими изменениями создайте новый пользовательский образ Docker и присвойте ему уникальный тег (здесь мы будем использовать jcasc ):

Вы увидите вывод, аналогичный следующему:

После создания запустите свой собственный образ, запустив docker run :

Вы использовали опцию --name jenkins , чтобы дать контейнеру легко запоминающееся имя; в противном случае вместо него будет использоваться случайный шестнадцатеричный идентификатор (например, f1d701324553 ). Вы также указали флаг --rm , чтобы контейнер автоматически удалялся после остановки процесса контейнера. Наконец, вы настроили порт 8080 хоста вашего сервера для прокси-сервера на порт 8080 контейнера, используя флаг -p ; 8080 — это порт по умолчанию, через который обслуживается веб-интерфейс Jenkins.

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

Теперь откройте в браузере server_ip :8080 . Вам сразу же будет показана панель мониторинга без мастера настройки.

Вы только что подтвердили, что мастер установки отключен. Чтобы очистить контейнер, остановите его, нажав CTRL+C . Если вы ранее указали флаг --rm , остановленный контейнер будет автоматически удален.

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

Первое предупреждение сообщает вам, что вы не настроили URL-адрес Jenkins. Второй сообщает вам, что вы не настроили никаких схем аутентификации и авторизации и что анонимные пользователи имеют полные разрешения на выполнение всех действий на вашем экземпляре Jenkins. Ранее мастер установки помогал вам решить эти проблемы. Теперь, когда вы его отключили, вам нужно воспроизвести те же функции с помощью JCasC. Оставшаяся часть этого руководства будет включать в себя изменение конфигурации Dockerfile и JCasC до тех пор, пока проблемы не исчезнут (то есть пока не исчезнет красный значок уведомления).

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

Шаг 2 — Установка плагинов Jenkins

Чтобы использовать JCasC, вам необходимо установить плагин «Конфигурация как код». На данный момент плагины не установлены. Вы можете убедиться в этом, перейдя по адресу http:// server_ip :8080/pluginManager/installed .

На этом этапе вы собираетесь изменить свой Dockerfile , чтобы предварительно установить набор плагинов, включая плагин «Конфигурация как код».

Чтобы автоматизировать процесс установки плагина, вы можете использовать сценарий установки, который поставляется с образом jenkins/jenkins Docker. Вы можете найти его внутри контейнера по адресу /usr/local/bin/install-plugins.sh . Чтобы использовать его, вам необходимо:

• Создайте текстовый файл, содержащий список плагинов для установки.
• Скопируйте его в образ Docker.
• Запустите скрипт install-plugins.sh для установки плагинов.

Сначала с помощью редактора создайте новый файл с именем plugins.txt :

Затем добавьте следующий список имен и версий плагинов, разделенных символами новой строки (используя формат : ):

Сохраните файл и выйдите из редактора.

Список содержит плагин «Конфигурация как код», а также все плагины, предложенные мастером установки (верно, начиная с Jenkins v2.251). Например, у вас есть плагин Git, который позволяет Дженкинсу работать с репозиториями Git; у вас также есть плагин Pipeline, который на самом деле представляет собой набор плагинов, позволяющий определять задания Jenkins как код.

Затем откройте файл Dockerfile :

Добавьте в него инструкцию COPY , чтобы скопировать файл plugins.txt в каталог /usr/share/jenkins/ref/ внутри образа; здесь Дженкинс обычно ищет плагины. Затем добавьте дополнительную инструкцию RUN для запуска сценария install-plugins.sh :

Сохраните файл и выйдите из редактора. Затем создайте новый образ, используя обновленный Dockerfile :

Этот шаг включает в себя загрузку и установку множества плагинов в образ. Его запуск может занять некоторое время в зависимости от вашего интернет-соединения. После завершения установки плагинов запустите новый образ Jenkins:

После того, как сообщение Jenkins is fully up and running на stdout , перейдите к server_ip :8080/pluginManager/installed , чтобы просмотреть список установленных плагинов. Вы увидите сплошной флажок рядом со всеми плагинами, которые вы указали в файле plugins.txt , а также затемненный флажок рядом с плагинами, которые являются зависимостями этих плагинов.

Убедившись, что плагин Configuration As Code установлен, завершите процесс контейнера, нажав CTRL+C .

На этом этапе вы установили все предложенные плагины Jenkins и плагин «Конфигурация как код». Теперь вы готовы использовать JCasC для решения проблем, перечисленных в окне уведомления. На следующем шаге вы исправите первую проблему, которая предупреждает вас о том, что Jenkins root URL is empty .

Шаг 3 — Указание URL-адреса Jenkins

URL-адрес Jenkins — это URL-адрес экземпляра Jenkins, который можно маршрутизировать с устройств, которым необходим доступ к нему. Например, если вы развертываете Jenkins в качестве узла внутри частной сети, URL-адрес Jenkins может быть частным IP-адресом или DNS-именем, которое можно разрешить с помощью частного DNS-сервера. В этом руководстве достаточно использовать IP-адрес сервера (или 127.0.0.1 для локальных хостов) для формирования URL-адреса Jenkins.

Вы можете установить URL-адрес Jenkins в веб-интерфейсе, перейдя по адресу server_ip :8080/configure и введя значение в поле Jenkins URL под заголовком Jenkins Location . Вот как добиться того же с помощью плагина «Конфигурация как код»:

1. Определите желаемую конфигурацию вашего экземпляра Jenkins внутри файла декларативной конфигурации (который мы назовем casc.yaml ).
2. Скопируйте файл конфигурации в образ Docker (так же, как вы это делали для файла plugins.txt ).
3. Установите для переменной среды CASC_JENKINS_CONFIG путь к файлу конфигурации, чтобы дать указание подключаемому модулю «Конфигурация как код» прочитать его.

Сначала создайте новый файл с именем casc.yaml :

Затем добавьте следующие строки:

unclassified.location.url — это путь для установки URL-адреса Jenkins. Это лишь одно из множества свойств, которые можно установить с помощью JCasC. Допустимые свойства определяются установленными плагинами. Например, свойство jenkins.authorizationStrategy.globalMatrix.permissions будет действительным только в том случае, если установлен подключаемый модуль Matrix Authorization Strategy. Чтобы узнать, какие свойства доступны, перейдите по адресу server_ip :8080/configuration-as-code/reference , и вы найдете страницу документации, настроенную для вашей конкретной установки Jenkins.

Сохраните файл casc.yaml , выйдите из редактора и откройте файл Dockerfile :

Добавьте в конец вашего Dockerfile инструкцию COPY , которая копирует файл casc.yaml в образ /var/jenkins_home/casc.yaml . Вы выбрали /var/jenkins_home/ потому что это каталог по умолчанию, в котором Jenkins хранит все свои данные:

Затем добавьте еще одну инструкцию ENV , которая устанавливает переменную среды CASC_JENKINS_CONFIG :

Сохраните файл и выйдите из редактора. Далее создайте образ:

И запустите обновленный образ Jenkins:

Как только появится строка журнала Jenkins is fully up and running , перейдите к server_ip :8080 , чтобы просмотреть панель мониторинга. На этот раз вы, возможно, заметили, что количество уведомлений уменьшилось на единицу, а предупреждение об URL-адресе Jenkins исчезло.

Теперь перейдите к server_ip :8080/configure и прокрутите вниз до поля Jenkins URL . Убедитесь, что для URL-адреса Jenkins установлено то же значение, которое указано в файле casc.yaml .

Наконец, остановите процесс контейнера, нажав CTRL+C .

На этом этапе вы использовали плагин «Конфигурация как код», чтобы установить URL-адрес Jenkins. На следующем шаге вы решите вторую проблему из списка уведомлений (сообщение Jenkins is currently unsecured ).

Шаг 4 — Создание пользователя

До сих пор в вашей установке не реализованы какие-либо механизмы аутентификации и авторизации. На этом этапе вы настроите базовую схему аутентификации на основе пароля и создадите нового пользователя с именем admin .

Начните с открытия файла casc.yaml :

Затем добавьте выделенный фрагмент:

В контексте Jenkins область безопасности — это просто механизм аутентификации; локальная область безопасности означает использование базовой аутентификации, при которой пользователи должны указать свой идентификатор/имя пользователя и пароль. Существуют и другие области безопасности, которые обеспечиваются плагинами. Например, плагин LDAP позволяет использовать существующую службу каталогов LDAP в качестве механизма аутентификации. Плагин GitHub Authentication позволяет вам использовать ваши учетные данные GitHub для аутентификации через OAuth.

Обратите внимание, что вы также указали allowsSignup: false , что запрещает анонимным пользователям создавать учетные записи через веб-интерфейс.

Наконец, вместо жесткого кодирования идентификатора пользователя и пароля вы используете переменные, значения которых могут быть заполнены во время выполнения. Это важно, поскольку одним из преимуществ использования JCasC является то, что файл casc.yaml можно зафиксировать в системе контроля версий; если бы вы хранили пароли пользователей в виде открытого текста внутри файла конфигурации, вы бы фактически скомпрометировали учетные данные. Вместо этого переменные определяются с использованием синтаксиса ${VARIABLE_NAME} , и их значение может быть заполнено с использованием переменной среды с тем же именем или файла с тем же именем, который находится в каталоге /run/secrets/ внутри образа контейнера. .

Затем создайте новый образ, включив в него изменения, внесенные в файл casc.yaml :

Затем запустите обновленный образ Jenkins, передав переменные среды JENKINS_ADMIN_ID и JENKINS_ADMIN_PASSWORD с помощью параметра --env (замените паролем по вашему выбору):

Теперь вы можете перейти по server_ip :8080/login и войти в систему, используя указанные учетные данные.

После успешного входа в систему вы будете перенаправлены на панель управления.

Завершите этот шаг, нажав CTRL+C чтобы остановить контейнер.

На этом этапе вы использовали JCasC для создания нового пользователя с именем admin . Вы также узнали, как хранить конфиденциальные данные, например пароли, в файлах, отслеживаемых системами VCS. Однако до сих пор вы настроили только аутентификацию пользователя; вы не реализовали какие-либо механизмы авторизации. На следующем шаге вы будете использовать JCasC, чтобы предоставить admin права администратора.

Шаг 5 — Настройка авторизации

После настройки области безопасности вам необходимо настроить стратегию авторизации. На этом этапе вы будете использовать плагин Matrix Authorization Strategy для настройки разрешений для вашего admin .

По умолчанию основная установка Jenkins предоставляет нам три стратегии авторизации:

• unsecured : каждый пользователь, включая анонимных, имеет полные права на все действия.
• legacy : эмулирует устаревший Jenkins (до версии 1.164), где всем пользователям с ролью admin предоставляются полные разрешения, в то время как другим пользователям, включая анонимных пользователей, предоставляется доступ для чтения.

• loggedInUsersCanDoAnything : анонимным пользователям не предоставляется доступ или доступ только для чтения. Аутентифицированные пользователи имеют полные права на все действия. Разрешая действия только для прошедших проверку подлинности пользователей, вы можете отслеживать, какие пользователи выполнили какие действия.

Все эти стратегии авторизации очень грубы и не обеспечивают детального контроля над тем, как устанавливаются разрешения для разных пользователей. Вместо этого вы можете использовать плагин Matrix Authorization Strategy, который уже включен в ваш список plugins.txt . Этот плагин предоставляет вам более детальную стратегию авторизации и позволяет устанавливать права пользователя как глобально, так и для каждого проекта/задания.

Плагин Matrix Authorization Strategy позволяет вам использовать свойство JCasC jenkins.authorizationStrategy.globalMatrix.permissions для установки глобальных разрешений. Чтобы использовать его, откройте файл casc.yaml :

И добавьте выделенный фрагмент:

Свойство globalMatrix устанавливает глобальные разрешения (в отличие от разрешений для каждого проекта). Свойство permissions представляет собой список строк в формате /: . Здесь вы предоставляете права Overall/Administer admin . Вы также предоставляете разрешения Overall/Read для authenticated — специальной роли, представляющей всех прошедших проверку подлинности пользователей. Есть еще одна специальная роль, называемая anonymous , которая группирует всех неаутентифицированных пользователей вместе. Но поскольку разрешения по умолчанию запрещены, если вы не хотите предоставлять анонимным пользователям какие-либо разрешения, вам не нужно явно включать запись для этого.

Сохраните файл casc.yaml , выйдите из редактора и создайте новый образ:

Затем запустите обновленный образ Jenkins:

Подождите, пока строка журнала Jenkins is fully up and running , а затем перейдите к server_ip :8080 . Вы будете перенаправлены на страницу входа. Введите свои учетные данные, и вы будете перенаправлены на главную панель управления.

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

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

Прежде чем продолжить, остановите контейнер, нажав CTRL+C .

Шаг 6 — Настройка авторизации сборки

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

Вместо этого задания следует запускать с использованием того же пользователя Jenkins, который настроил или инициировал их. Для этого вам необходимо установить дополнительный плагин под названием Authorize Project.

Откройте plugins.txt :

И добавьте выделенную строку:

Плагин предоставляет новую стратегию авторизации сборки, которую вам необходимо указать в конфигурации JCasC. Выйдите из файла plugins.txt и откройте файл casc.yaml :

Добавьте выделенный блок в файл casc.yaml :

Сохраните файл и выйдите из редактора. Затем создайте новый образ, используя измененные файлы plugins.txt и casc.yaml :

Затем запустите обновленный образ Jenkins:

Подождите, пока строка журнала Jenkins is fully up and running , затем перейдите к server_ip :8080/login , введите свои учетные данные и перейдите на главную панель мониторинга. Откройте меню уведомлений, и вы увидите, что проблема, связанная с аутентификацией сборки, больше не появляется.

Прежде чем продолжить, остановите контейнер, нажав клавиши CTRL+C .

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

Шаг 7. Включение контроля доступа агента к контроллеру

В этом руководстве вы развернули только один экземпляр Jenkins, который запускает все сборки. Однако Jenkins поддерживает распределенные сборки с использованием конфигурации агента/контроллера. Контроллер отвечает за предоставление веб-интерфейса, предоставление клиентам API для отправки запросов и координацию сборок. Агенты — это экземпляры, выполняющие задания.

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

Однако могут быть случаи, когда контроллер не может доверять агентам. Например, команда OPS может управлять контроллером Jenkins, в то время как внешний подрядчик управляет собственным специально настроенным агентом Jenkins. Без подсистемы безопасности «агент-контроллер» агент может дать указание контроллеру выполнить любые запрашиваемые им действия, что может быть нежелательным. Включив контроль доступа агента к контроллеру, вы можете контролировать, к каким командам и файлам агенты имеют доступ.

Чтобы включить контроль доступа агента к контроллеру, откройте файл casc.yaml :

Затем добавьте следующие выделенные строки:

Сохраните файл и создайте новый образ:

Запустите обновленный образ Jenkins:

Перейдите к server_ip :8080/login и выполните аутентификацию, как и раньше. Когда вы перейдете на главную панель управления, в меню уведомлений больше не будет отображаться никаких проблем.

Заключение

Теперь вы успешно настроили простой сервер Jenkins с помощью JCasC. Точно так же, как плагин Pipeline позволяет разработчикам определять свои задания внутри Jenkinsfile , плагин Configuration as Code позволяет администраторам определять конфигурацию Jenkins внутри файла YAML. Оба этих плагина приближают Jenkins к парадигме «Все как код» (EaC).

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

Хотя вы настроили основные параметры Jenkins с помощью JCasC, новый экземпляр не содержит никаких проектов или заданий. Чтобы пойти еще дальше, изучите плагин Job DSL, который позволяет нам определять проекты и задания как код. Более того, вы можете включить код Job DSL в файл конфигурации JCasC и создавать проекты и задания в рамках процесса настройки.