emmetog.jenkins

Rola Ansible dla Jenkins

Instaluje i całkowicie konfiguruje Jenkins za pomocą Ansible.

Ta rola jest używana, gdy chcesz, aby cała konfiguracja Jenkins była w wersjonowaniu, aby móc wdrażać Jenkins w sposób powtarzalny i wiarygodny, traktując go jak bydło zamiast zwierzątka domowego.

Jeśli szukasz roli do zainstalowania Jenkins i chcesz konfigurować wszystko przez interfejs webowy, nie martwiąc się o powtarzalność wdrożenia, to nie potrzebujesz tej roli. Zamiast tego, zapoznaj się z rolą geerlingguy/ansible-role-jenkins.

Wymagania

Jeśli wdrażasz przy użyciu Dockera, to musisz mieć zainstalowany Docker na serwerze. Docker, apt-get i yum to jedyne obsługiwane metody na ten moment, chociaż można łatwo dodać więcej, zapraszam do przesyłania PR.

Instalacja

Zainstaluj za pomocą Ansible Galaxy:

$ ansible-galaxy install emmetog.jenkins

Zmienna Roli

Następujące zmienne wpływają na sposób instalacji Jenkins:

jenkins_install_via: Kontroluje, jak Jenkins jest instalowany. Ważne: Ta zmienna musi być zdefiniowana jako jedna z następujących wartości:
- docker: Zainstaluj w kontenerze Docker
- apt: Zainstaluj Jenkins bezpośrednio na systemach Ubuntu/Debian
- yum: Zainstaluj Jenkins bezpośrednio na systemach RedHat/CentOS
jenkins_version: Dokładna wersja Jenkin do zainstalowania

Następujące zmienne wpływają na sposób konfiguracji Jenkins:

jenkins_url: URL, pod którym będzie dostępny Jenkins
jenkins_port: Port, na którym Jenkins będzie nasłuchiwał
jenkins_home: Katalog na serwerze, w którym będą przechowywane konfiguracje Jenkins
jenkins_admin: Adres e-mail administratora dla serwera Jenkins
jenkins_java_opts: Opcje przekazywane do wykonywalnego pliku Java
jenkins_config_owner: Właściciel plików konfiguracyjnych Jenkins
jenkins_config_group: Grupa plików konfiguracyjnych Jenkins
jenkins_auth: Jak Ansible powinien się uwierzytelnić w Jenkins (zobacz sekcję "Uwierzytelnianie i bezpieczeństwo" poniżej)
jenkins_url_health_check: Jaki URL użyć do sprawdzenia stanu po uruchomieniu Jenkins (domyślnie jenkins_url)
jenkins_health_check_user: Jeśli jest zdefiniowany, używa podstawowego uwierzytelniania (zobacz sekcję API tokenów) do sprawdzenia stanu z tym użytkownikiem (przydatne, jeśli skonfigurujesz np. Google OAuth)
jenkins_health_check_password: Jeśli jest zdefiniowany, używa podstawowego uwierzytelniania (zobacz sekcję API tokenów) do sprawdzenia stanu z tym hasłem (przydatne, jeśli skonfigurujesz np. Google OAuth)

Lista zmiennych, która wpływa na zadania/plug-ins, które będą zainstalowane w Jenkins:

jenkins_jobs: Lista nazw zadań do skopiowania do Jenkins. Plik config.xml musi istnieć w jenkins_source_dir_jobs/<job_name>
jenkins_plugins: Lista identyfikatorów wtyczek do zainstalowania w Jenkins.
jenkins_custom_plugins: Lista niestandardowych wtyczek do zainstalowania w Jenkins.

Aby zobaczyć kompletną listę zmiennych, zobacz defaults/main.yml.

Przykładowy playbook

- hosts: jenkins

  vars:
    jenkins_version: "2.73.1"
    jenkins_hostname: "jenkins.example.com"
    jenkins_port: 8080
    jenkins_install_via: "docker"
    jenkins_jobs:
      - "moje-pierwsze-zadanie"
      - "inne-wspaniałe-zadanie"
    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

Zarządzanie plikami konfiguracyjnymi

Powyższy przykład będzie szukał plików konfiguracyjnych zadań w {{ playbook_dir }}/jenkins-configs/jobs/moje-pierwsze-zadanie/config.xml oraz {{ playbook_dir }}/jenkins-configs/jobs/inne-wspaniałe-zadanie/config.xml.

UWAGA: Te katalogi są konfigurowalne, sprawdź zmienne roli jenkins_source_dir_configs oraz jenkins_source_dir_jobs.

Rola również będzie szukać {{ playbook_dir }}/jenkins-configs/config.xml Ten plik config.xml zostanie skopiowany na serwer i użyty jako szablon konfiguracji zadań.

Powyższy przykład będzie również przesyłał cały katalog sekretnych danych pod {{ playbook_dir }}/jenkins-configs/secrets, a także skopiuje niestandardowe pliki zdefiniowane w zmiennej {{ jenkins_custom_files }}. Zauważ, że {{ jenkins_include_secrets }} oraz {{ jenkins_include_custom_files }} powinny być ustawione na true, aby te funkcje działały. Dodatkowo, rola może zainstalować niestandardowe wtyczki, dostarczając pliki .jpi lub .hpi w zmiennej listy {{ jenkins_custom_plugins }}.

Pliki config.xml i niestandardowe pliki są traktowane jako szablony, więc możesz umieszczać w nich zmienne, w tym dane wrażliwe z sejfu Ansible.

Kiedy chcesz wprowadzić zmianę w pliku konfiguracyjnym lub dodać nowy element (taki jak zadanie, wtyczka itd.) standardowy proces roboczy to:

Wprowadź zmianę w interfejsie użytkownika Jenkins
Skopiuj powstałe pliki XML z powrotem do swojego systemu kontroli wersji
Dla nowo utworzonych plików, nie zapomnij dodać ich do odpowiedniej listy:
- Dla nowych zadań muszą być dodane do jenkins_jobs
- Dla niestandardowych plików muszą być dodane do jenkins_include_custom_files
- Dla niestandardowych wtyczek muszą być dodane do jenkins_custom_plugins

Przykładowy plik konfiguracyjny Jenkins

W {{ jenkins_source_dir_configs }}/config.xml wprowadź swoją globalną konfigurację Jenkins, na przykład:

<?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>

Przykładowy plik konfiguracyjny zadania

Oto przykład, co możesz umieścić w {{ playbook_dir }}/jenkins-configs/jobs/moje-pierwsze-zadanie/config.xml:

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description>Moje pierwsze zadanie, wyświetla "hello world"</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>

Uwierzytelnianie i bezpieczeństwo

Ta rola obsługuje następujące mechanizmy uwierzytelniania dla Jenkins:

Uwierzytelnianie za pomocą tokenów API (zalecane, wymaga przynajmniej Jenkins 2.96)
Uwierzytelnianie oparte na crumbach z wtyczką Strict Crumb Issuer (wymagane, jeśli nie używasz tokenów API i Jenkins 2.176.2 lub nowszego)
Brak bezpieczeństwa (niezalecane)

Uwierzytelnianie za pomocą tokenów API

Uwierzytelnianie za pomocą tokenów API jest zalecane, ale wymaga trochę dodatkowego wysiłku w konfiguracji. Zaletą tokenów API jest to, że mogą być łatwo unieważnione w Jenkins, a ich użycie jest również śledzone. Tokeny API nie wymagają również uzyskania tokena crumb, co stało się trudniejsze od wersji Jenkins 2.172.2 (zobacz to ogłoszenie o bezpieczeństwie.

Aby utworzyć token API, należy wykonać następujące kroki:

Wszystkie tokeny API muszą należeć do konkretnego użytkownika. Więc albo utwórz specjalnego użytkownika do wdrożeń, albo zaloguj się jako administrator lub inne konto.
Na stronie konfiguracyjnej użytkownika kliknij przycisk "Dodaj nowy token".
Zapisz wartość tokena, najlepiej w sejfie Ansible.
Zdefiniuj następujące zmienne w swoim playbooku:

jenkins_auth: "api"
jenkins_api_token: "(zdefiniowane w sejfie Ansible)"
jenkins_api_username: "(zdefiniowane w sejfie Ansible)"

Utwórz kopię zapasową pliku $JENKINS_HOME/users/the_username/config.xml, gdzie the_username odpowiada użytkownikowi, który jest właścicielem tokena API, który właśnie utworzyłeś.
Dodaj ten plik do swojego hosta kontrolnego i upewnij się, że jest wdrażany do Jenkins w liście jenkins_custom_files, w ten sposób:

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

Zauważ, że może być konieczne zmienienie wartości src, w zależności od tego, gdzie zapisujesz plik na maszynie kontrolnej w stosunku do playbooka.

Uwierzytelnianie oparte na crumbach

Uwierzytelnianie oparte na crumbach może być używane w celu zapobiegania atakom CSRF i jest zalecane, jeśli tokeny API są niepraktyczne. Uwaga: uwierzytelnianie oparte na crumbach działa tylko z ustawieniem kontroli dostępu "Każdy może zrobić wszystko". Jeśli Twoja konfiguracja Jenkins wymaga ściślejszego ustawienia bezpieczeństwa, powinieneś korzystać z tokenów API (dokumentowane powyżej).

Konfigurowanie CSRF może być nieco skomplikowane ze względu na ostatnie poprawki bezpieczeństwa w Jenkins. Aby skonfigurować CSRF, musisz wykonać następujące kroki:

Jeśli używasz Jenkins >= 2.176.2, musisz zainstalować wtyczkę Strict Crumb Issuer. Można to zrobić za pomocą tej roli, dodając strict-crumb-issuer do listy jenkins_plugins.
W Jenkins, kliknij "Zarządzaj Jenkins" -> "Skonfiguruj globalne bezpieczeństwo".
W sekcji "Ochrona CSRF" włącz "Zapobiegaj eksploitom Cross Site Request Forgery" i wybierz "Strict Crumb Issuer", jeśli używasz Jenkins >= 2.176.2, lub w przeciwnym razie "Default Crumb Issuer". Zauważ, że aby zobaczyć tę opcję, musisz mieć zainstalowaną wtyczkę Strict Crumb Issuer. Następnie będziesz także musiał wykonać kopię zapasową głównego pliku konfiguracyjnego Jenkins config.xml na hosta kontrolnego.

Aby to wszystko zadziałało, będziesz potrzebować przynajmniej Ansible 2.9.0pre5 lub 2.10 (które, w momencie pisania, są w rozwoju. Zobacz to zagadnienie Ansible po więcej szczegółów).

HTTPS

Jeśli chcesz włączyć HTTPS w Jenkins, możesz to zrobić w następujący sposób:

Zdefiniuj jenkins_port_https jako port, na którym Jenkins powinien nasłuchiwać
Zdefiniuj zmienne albo dla magazynu JKS, albo dla certyfikatu podpisanego przez CA:
- Dla magazynu JKS musisz zdefiniować:
  - jenkins_https_keystore: Ścieżka do pliku magazynu na kontrolującym hoście, który będzie skopiowany na serwer Jenkins przez tę rolę.
  - jenkins_https_keystore_password: Hasło dla wspomnianego magazynu JKS. Zaleca się użycie sejfu Ansible. WAŻNE: Ten ciąg zostanie zapisany w formie niezaszyfrowanej w pliku konfiguracyjnym Jenkins na serwerze. Będzie również widoczny na liście procesów serwera. Rozważ migrację swojego certyfikatu do pliku podpisanego certyfikatu (zobacz poniżej).
- Dla pliku certyfikatu podpisanego przez CA, musisz zdefiniować:
  - jenkins_https_certificate: Ścieżka do pliku certyfikatu, który będzie skopiowany na serwer Jenkins przez tę rolę. Zaleca się użycie sejfu Ansible dla tego pliku.
  - jenkins_https_private_key: Klucz prywatny dla wspomnianego certyfikatu podpisanego przez CA. Zaleca się użycie sejfu Ansible dla tego pliku.
Opcjonalnie, powinna być zdefiniowana zmienna jenkins_https_validate_certs jako false, jeśli używasz certyfikatu samopodpisanego.

Jeśli wdrażasz Jenkins z Dockerem, to zaleca się użycie odwrotnego proxy, takiego jak jwilder/nginx-proxy lub traefik zamiast konfigurowania samego Jenkins. To daje nieco większą elastyczność i pozwala na podział odpowiedzialności. Zobacz dokumentację w tych projektach po więcej szczegółów na temat wdrażania proxy i konfigurowania HTTPS.

Jeżeli używasz odwrotnego proxy przed instancją Jenkins i wdrażasz z Dockerem, prawdopodobnie chcesz ustawić zmienną jenkins_docker_expose_port na fałsz, aby port nie był eksponowany na hoście, tylko dla odwrotnego proxy.