emmetog.jenkins

Роль Ansible для Jenkins

Устанавливает и полностью настраивает Jenkins с использованием Ansible.

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

Если вы ищете роль для установки Jenkins и хотите настраивать всё через веб-интерфейс, и вам не важно возможность многократного развертывания этого полностью настроенного Jenkins, то вам не нужна эта роль. Вместо этого посмотрите на geerlingguy/ansible-role-jenkins.

Требования

Если вы развертываете с помощью Docker, то на сервере необходимо установить Docker. На данный момент поддерживаются только Docker, apt-get и yum, хотя можно легко добавить больше способов, PR приветствуются.

Установка

Установите с помощью Ansible Galaxy:

$ ansible-galaxy install emmetog.jenkins

Переменные роли

Следующие переменные влияют на то, как устанавливается Jenkins:

jenkins_install_via: Определяет, как устанавливается Jenkins. Важно: Эта переменная должна быть определена с одним из следующих значений:
- docker: Установить в контейнер Docker
- apt: Установить Jenkins напрямую на системах Ubuntu/Debian
- yum: Установить Jenkins напрямую на системах RedHat/CentOS
jenkins_version: Точная версия Jenkins для установки

Следующие переменные влияют на то, как настраивается Jenkins:

jenkins_url: URL, по которому будет доступен Jenkins
jenkins_port: Порт, на котором будет слушать Jenkins
jenkins_home: Директория на сервере, где будут находиться конфигурации Jenkins
jenkins_admin: Email администратора сервера Jenkins
jenkins_java_opts: Опции, передаваемые исполняемому файлу Java
jenkins_config_owner: Владелец файлов конфигурации Jenkins
jenkins_config_group: Группа файлов конфигурации Jenkins
jenkins_auth: Как Ansible должен аутентифицироваться с Jenkins (см. раздел "Аутентификация и безопасность")
jenkins_url_health_check: Какой URL использовать для проверки состояния после запуска Jenkins (по умолчанию jenkins_url)
jenkins_health_check_user: если определено, используется базовая аутентификация (см. раздел про токен API) для проверки состояния с этим именем пользователя (полезно, если вы, например, настроили Google OAuth)
jenkins_health_check_password: если определено, используется базовая аутентификация (см. раздел про токен API) для проверки состояния с этим паролем (полезно, если вы, например, настроили Google OAuth)

Следующие списковые переменные влияют на задания/плагины, которые будут установлены в Jenkins:

jenkins_jobs: Список имен заданий, которые нужно скопировать в Jenkins. Файл config.xml должен существовать в каталоге jenkins_source_dir_jobs/<job_name>
jenkins_plugins: Список ID плагинов для установки в Jenkins.
jenkins_custom_plugins: Список пользовательских плагинов для установки в Jenkins.

Для полного списка переменных см. defaults/main.yml.

Пример плейбука

- hosts: jenkins

  vars:
    jenkins_version: "2.73.1"
    jenkins_hostname: "jenkins.example.com"
    jenkins_port: 8080
    jenkins_install_via: "docker"
    jenkins_jobs:
      - "my-first-job"
      - "another-awesome-job"
    jenkins_include_secrets: true
    jenkins_include_custom_files: true
    jenkins_custom_files:
      - src: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
        dest: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
    jenkins_plugins:
      - git
      - blueocean
    jenkins_custom_plugins:
      - "openstack-cloud-plugin/openstack-cloud.jpi"

  roles:
    - emmetog.jenkins

Управление конфигурационными файлами

Приведенный выше пример будет искать конфигурационные файлы заданий в {{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xml и {{ playbook_dir }}/jenkins-configs/jobs/another-awesome-job/config.xml.

ПРИМЕЧАНИЕ: Эти директории можно настроить, смотрите переменные роли jenkins_source_dir_configs и jenkins_source_dir_jobs.

Роль также будет искать файл {{ playbook_dir }}/jenkins-configs/config.xml Этот файл config.xml будет скопирован на сервер и использован в качестве шаблона конфигурации задания.

В приведенном выше примере также будет загружена вся директория секретов из {{ playbook_dir }}/jenkins-configs/secrets, а также будут скопированы пользовательские файлы, определенные в переменной {{ jenkins_custom_files }}. Обратите внимание, что переменные {{ jenkins_include_secrets }} и {{ jenkins_include_custom_files }} должны быть установлены в true, чтобы эти функции работали. Дополнительно, роль может установить пользовательские плагины, предоставив файлы .jpi или .hpi в списковой переменной {{ jenkins_custom_plugins }}.

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

Когда вы хотите внести изменения в конфигурационный файл или добавить новый элемент (например, задание, плагин и т. д.), нормальный рабочий процесс:

Внесите изменения в интерфейсе Jenkins
Скопируйте полученные XML файлы обратно в вашу систему управления версиями
Для вновь созданных файлов не забудьте добавить их в соответствующий список:

Для новых заданий их нужно добавить в jenkins_jobs
Для пользовательских файлов их нужно добавить в jenkins_include_custom_files
Для пользовательских плагинов их нужно добавить в jenkins_custom_plugins

Пример конфигурационного файла Jenkins

В {{ jenkins_source_dir_configs }}/config.xml вы указываете свою глобальную конфигурацию Jenkins, например:

<?xml version='1.1' encoding='UTF-8'?>
<hudson>
  <disabledAdministrativeMonitors/>
  <version>2.176.1</version>
  <installStateName>RESTART</installStateName>
  <numExecutors>1</numExecutors>
  <mode>EXCLUSIVE</mode>
  <useSecurity>true</useSecurity>
  <authorizationStrategy class="hudson.security.AuthorizationStrategy$Unsecured"/>
  <securityRealm class="hudson.security.HudsonPrivateSecurityRealm">
    <disableSignup>false</disableSignup>
    <enableCaptcha>false</enableCaptcha>
  </securityRealm>
  <disableRememberMe>false</disableRememberMe>
  <projectNamingStrategy class="jenkins.model.ProjectNamingStrategy$DefaultProjectNamingStrategy"/>
  <workspaceDir>${JENKINS_HOME}/workspace/${ITEM_FULLNAME}</workspaceDir>
  <buildsDir>${ITEM_ROOTDIR}/builds</buildsDir>
  <markupFormatter class="hudson.markup.EscapedMarkupFormatter"/>
  <jdks/>
  <viewsTabBar class="hudson.views.DefaultViewsTabBar"/>
  <myViewsTabBar class="hudson.views.DefaultMyViewsTabBar"/>
  <clouds/>
  <quietPeriod>0</quietPeriod>
  <scmCheckoutRetryCount>0</scmCheckoutRetryCount>
  <views>
    <hudson.model.AllView>
      <owner class="hudson" reference="../../.."/>
      <name>all</name>
      <filterExecutors>false</filterExecutors>
      <filterQueue>false</filterQueue>
      <properties class="hudson.model.View$PropertyList"/>
    </hudson.model.AllView>
  </views>
  <primaryView>all</primaryView>
  <slaveAgentPort>0</slaveAgentPort>
  <disabledAgentProtocols>
    <string>JNLP-connect</string>
    <string>JNLP2-connect</string>
  </disabledAgentProtocols>
  <label>master</label>
  <crumbIssuer class="hudson.security.csrf.DefaultCrumbIssuer">
    <excludeClientIPFromCrumb>false</excludeClientIPFromCrumb>
  </crumbIssuer>
  <nodeProperties/>
  <globalNodeProperties/>
</hudson>

Пример файла конфигурации задания

Вот пример того, что вы можете поместить в {{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xml:

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description>Мое первое задание, оно говорит "Привет, мир"</description>
  <keepDependencies>false</keepDependencies>
  <properties/>
  <scm class="hudson.scm.NullSCM"/>
  <canRoam>true</canRoam>
  <disabled>false</disabled>
  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
  <triggers/>
  <concurrentBuild>false</concurrentBuild>
  <builders>
    <hudson.tasks.Shell>
      <command>echo &quot;Hello World!&quot;</command>
    </hudson.tasks.Shell>
  </builders>
  <publishers/>
  <buildWrappers/>
</project>

Аутентификация и безопасность

Эта роль поддерживает следующие механизмы аутентификации для Jenkins:

Аутентификация на основе токена API (рекомендуется, требует как минимум Jenkins 2.96)
Аутентификация на основе крошки с использованием плагина Strict Crumb Issuer (требуется, если не используются токены API и Jenkins 2.176.2 или новее)
Безопасности (не рекомендуется)

Аутентификация на основе токена API

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

Чтобы создать токен API, вам нужно сделать следующее:

Все токены API должны принадлежать конкретному пользователю. Так что либо создайте специального пользователя для развертываний, либо войдите под администратором или другим аккаунтом.
На странице конфигурации пользователя нажмите кнопку "Добавить новый токен".
Сохраните значение токена, желательно в хранилище Ansible.
Определите следующие переменные в вашем плейбуке:

jenkins_auth: "api"
jenkins_api_token: "(определен в хранилище Ansible)"
jenkins_api_username: "(определен в хранилище Ansible)"

Создайте резервную копию файла $JENKINS_HOME/users/the_username/config.xml, где the_username соответствует пользователю, которому принадлежит токен API, который вы только что создали.
Добавьте этот файл на ваш контрольный хост и убедитесь, что он будет развернут в Jenkins в списке jenkins_custom_files, следующим образом:

jenkins_custom_files:
  - src: "users/the_username/config.xml"
    dest: "users/the_username/config.xml"

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

Аутентификация на основе крошки

Аутентификация на основе крошки может использоваться для предотвращения атак межсайтового подделки запросов и рекомендуется, если токены API не подходят. Примечание: аутентификация на основе крошки работает только с уровнем контроля доступа "Любой может делать что угодно". Если ваша конфигурация Jenkins требует более строгой настройки безопасности, то следует использовать токены API (документированы выше).

Аутентификацию на основе крошки может быть сложно настроить из-за недавних исправлений безопасности в Jenkins. Чтобы настроить CSRF вам нужно сделать следующее:

Если вы используете Jenkins >= 2.176.2, вам нужно установить плагин Strict Crumb Issuer. Это можно сделать с помощью этой роли, добавив ID strict-crumb-issuer в список jenkins_plugins.
В Jenkins нажмите на "Управлять Jenkins" -> "Настроить глобальную безопасность"
В разделе "Защита CSRF" включите "Предотвратить атаки межсайтового подделки запросов", а затем выберите "Strict Crumb Issuer", если используете Jenkins >= 2.176.2, или в противном случае "Default Crumb Issuer". Обратите внимание, что для того, чтобы увидеть эту опцию, вам необходимо установить плагин Strict Crumb Issuer. После этого вам также нужно создать резервную копию основного файла конфигурации Jenkins config.xml на контрольный хост.

Аналогично, чтобы вышеуказанное работало, вам потребуется как минимум Ansible 2.9.0pre5 или 2.10 (которые в момент написания этого текста оба находятся в разработке. Смотрите этот вопрос Ansible для получения дополнительных деталей).

HTTPS

Если вы хотите включить HTTPS на Jenkins, это можно сделать следующим образом:

Определите jenkins_port_https для порта, на котором Jenkins должен слушать
Определите переменные либо для JKS хранилища ключей, либо для сертификата, подписанного ЦС:
- Для JKS хранилища ключей, вам нужно определить:
  - jenkins_https_keystore: Путь к файлу хранилища ключей на контрольном хосте, который будет скопирован на сервер Jenkins этой ролью.
  - jenkins_https_keystore_password: Пароль для указанного JKS хранилища ключей. Рекомендуется использовать хранилище Ansible для этого. ВАЖНО: Эта строка будет записываться в открытом виде в файл конфигурации Jenkins на сервере. Она также будет видна в списке процессов на сервере. Рассмотрите возможность перевода вашего сертификата в файл подписанного сертификата (см. ниже).
- Для файла сертификата, подписанного ЦС, вам нужно определить:
  - jenkins_https_certificate: Путь к файлу сертификата, который будет скопирован на сервер Jenkins этой ролью. Рекомендуется использовать хранилище Ansible для этого файла.
  - jenkins_https_private_key: Приватный ключ для указанного сертификата. Рекомендуется использовать хранилище Ansible для этого файла.
Необязательно, jenkins_https_validate_certs следует установить в false, если вы используете самоподписанный сертификат.

Если вы развертываете Jenkins с помощью Docker, то рекомендуется использовать обратный прокси, такой как jwilder/nginx-proxy или traefik вместо настройки самого Jenkins. Это дает немного больше гибкости и позволяет разделить обязанности. Смотрите документацию в этих проектах для дополнительной информации о том, как развернуть прокси и настроить HTTPS.

Если вы используете обратный прокси перед инстансом Jenkins и развертываете с помощью Docker, вы, вероятно, захотите установить переменную jenkins_docker_expose_port в false, чтобы порт не был открыт на хосте, а только для обратного прокси.