emmetog.jenkins

Ansible-Rolle für Jenkins

Installiert und konfiguriert Jenkins vollständig mit Ansible.

Diese Rolle wird verwendet, wenn Sie alle Ihre Jenkins-Konfigurationen unter Versionskontrolle haben möchten, damit Sie Jenkins wiederholbar und zuverlässig bereitstellen können. Sie können Jenkins mehr wie eine Kuh als ein Haustier behandeln.

Wenn Sie nach einer Rolle suchen, um Jenkins zu installieren, alles über die Webschnittstelle zu konfigurieren und es Ihnen nicht wichtig ist, Jenkins in dieser vollständig konfigurierten Form wiederholt bereitzustellen, benötigen Sie diese Rolle nicht. Schauen Sie sich stattdessen die Rolle geerlingguy/ansible-role-jenkins an.

Anforderungen

Wenn Sie mit Docker bereitstellen, müssen Sie Docker auf dem Server installiert haben. Docker, apt-get und yum sind die einzigen unterstützten Methoden momentan, obwohl weitere Methoden leicht hinzugefügt werden können – PRs sind willkommen.

Installation

Installieren Sie die Rolle mit Ansible Galaxy:

$ ansible-galaxy install emmetog.jenkins

Rollen-Variablen

Die folgenden Variablen beeinflussen, wie Jenkins installiert wird:

jenkins_install_via: Steuert, wie Jenkins installiert wird. Wichtig: Diese Variable muss auf einen der folgenden Werte gesetzt sein:
- docker: Installation in einem Docker-Container
- apt: Installation von Jenkins direkt auf Ubuntu/Debian-Linux-Systemen
- yum: Installation von Jenkins direkt auf RedHat/CentOS-Linux-Systemen
jenkins_version: Die genaue Version von Jenkins, die installiert werden soll.

Die folgenden Variablen beeinflussen, wie Jenkins konfiguriert wird:

jenkins_url: Die URL, unter der Jenkins erreichbar ist.
jenkins_port: Der Port, auf dem Jenkins lauschen wird.
jenkins_home: Das Verzeichnis auf dem Server, in dem die Jenkins-Konfigurationen gespeichert werden.
jenkins_admin: Die E-Mail-Adresse des Administrators für den Jenkins-Server.
jenkins_java_opts: Optionen, die an die Java-Ausführungsdatei übergeben werden.
jenkins_config_owner: Eigentümer der Jenkins-Konfigurationsdateien.
jenkins_config_group: Gruppe der Jenkins-Konfigurationsdateien.
jenkins_auth: Wie Ansible sich bei Jenkins authentifizieren soll (siehe den Abschnitt „Authentifizierung und Sicherheit“ weiter unten).
jenkins_url_health_check: Welche URL für die Gesundheitsprüfung nach dem Start von Jenkins verwendet werden soll (standardmäßig jenkins_url).
jenkins_health_check_user: Wenn definiert, wird die Basisautorisierung (siehe Abschnitt zum API-Token) für die Gesundheitsprüfung mit diesem Benutzernamen verwendet (nützlich, wenn Sie z.B. Google OAuth eingerichtet haben).
jenkins_health_check_password: Wenn definiert, wird die Basisautorisierung (siehe Abschnitt zum API-Token) für die Gesundheitsprüfung mit diesem Passwort verwendet (nützlich, wenn Sie z.B. Google OAuth eingerichtet haben).

Die folgenden Listvariablen beeinflussen die Jobs/Plugins, die in Jenkins installiert werden:

jenkins_jobs: Liste der Namen der Jobs, die nach Jenkins kopiert werden sollen. Die Datei config.xml muss unter jenkins_source_dir_jobs/<job_name> existieren.
jenkins_plugins: Liste der Plugin-IDs, die in Jenkins installiert werden sollen.
jenkins_custom_plugins: Liste der benutzerdefinierten Plugins, die in Jenkins installiert werden sollen.

Für eine vollständige Liste der Variablen siehe defaults/main.yml.

Beispiel-Playbook

- hosts: jenkins

  vars:
    jenkins_version: "2.73.1"
    jenkins_hostname: "jenkins.example.com"
    jenkins_port: 8080
    jenkins_install_via: "docker"
    jenkins_jobs:
      - "mein-erster-job"
      - "ein-weiterer-genialer-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

Verwalten von Konfigurationsdateien

Das obige Beispiel sucht nach Jobkonfigurationsdateien in {{ playbook_dir }}/jenkins-configs/jobs/mein-erster-job/config.xml und {{ playbook_dir }}/jenkins-configs/jobs/ein-weiterer-genialer-job/config.xml.

HINWEIS: Diese Verzeichnisse sind anpassbar. Siehe die Rollenvariablen jenkins_source_dir_configs und jenkins_source_dir_jobs.

Die Rolle sucht auch nach {{ playbook_dir }}/jenkins-configs/config.xml Diese config.xml-Datei wird auf den Server kopiert und als Jobkonfigurationstemplate verwendet.

Das obige Beispiel lädt auch das gesamte Geheimnisse-Verzeichnis unter {{ playbook_dir }}/jenkins-configs/secrets hoch und kopiert auch benutzerdefinierte Dateien, die in der Variablen {{ jenkins_custom_files }} definiert sind. Beachten Sie, dass die Variablen {{ jenkins_include_secrets }} und {{ jenkins_include_custom_files }} auf true gesetzt werden sollten, damit diese Funktionen funktionieren. Darüber hinaus kann die Rolle benutzerdefinierte Plugins installieren, indem die .jpi oder .hpi-Dateien in der Listvariablen {{ jenkins_custom_plugins }} bereitgestellt werden.

Die config.xml- und benutzerdefinierten Dateien werden als Vorlagen behandelt, sodass Sie Variablen darin verwenden können, einschließlich sensibler Daten aus dem Ansible Vault.

Wenn Sie eine Änderung in einer Konfigurationsdatei vornehmen möchten oder ein neues Element (z.B. einen Job, ein Plugin usw.) hinzufügen möchten, ist der normale Workflow:

Ändern Sie die Einstellung in der Jenkins-Benutzeroberfläche.
Kopieren Sie die resultierenden XML-Dateien zurück in Ihre VCS.
Vergessen Sie nicht, neue Dateien der jeweiligen Liste hinzuzufügen:

Für neue Jobs müssen diese zu jenkins_jobs hinzugefügt werden.
Für benutzerdefinierte Dateien müssen diese zu jenkins_include_custom_files hinzugefügt werden.
Für benutzerdefinierte Plugins müssen diese zu jenkins_custom_plugins hinzugefügt werden.

Beispiel für eine Jenkins-Konfigurationsdatei

In {{ jenkins_source_dir_configs }}/config.xml fügen Sie Ihre globale Jenkins-Konfiguration ein, zum Beispiel:

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

Beispiel für eine Jobkonfigurationsdatei

Hier ist ein Beispiel dafür, was Sie in {{ playbook_dir }}/jenkins-configs/jobs/mein-erster-job/config.xml eingeben könnten:

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description>Mein erster Job, er sagt "Hallo Welt"</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;Hallo Welt!&quot;</command>
    </hudson.tasks.Shell>
  </builders>
  <publishers/>
  <buildWrappers/>
</project>

Authentifizierung und Sicherheit

Diese Rolle unterstützt die folgenden Authentifizierungsmechanismen für Jenkins:

Authentifizierung auf Basis von API-Token (empfohlen, erfordert mindestens Jenkins 2.96)
Authentifizierung auf Basis von Cookies mit dem Strict Crumb Issuer Plugin (notwendig, wenn keine API-Token verwendet werden und Jenkins 2.176.2 oder neuer ist)
Keine Sicherheit (nicht empfohlen)

API-Token-basierte Authentifizierung

Die Authentifizierung auf Basis von API-Token wird empfohlen, erfordert jedoch etwas mehr Aufwand zur Konfiguration. Der Vorteil von API-Token ist, dass sie in Jenkins leicht widerrufbar sind und ihre Verwendung auch nachverfolgt wird. API-Token erfordern auch nicht das Abrufen eines Crumb-Tokens, was seit Jenkins-Version 2.172.2 schwieriger geworden ist (siehe diese Sicherheitswarnung.

Um ein API-Token zu erstellen, müssen Sie Folgendes tun:

Alle API-Token müssen zu einem bestimmten Benutzer gehören. Erstellen Sie entweder einen speziellen Benutzer für Bereitstellungen oder melden Sie sich als Administrator oder ein anderes Konto an.
Klicken Sie in der Konfigurationsseite des Benutzers auf die Schaltfläche „Neues Token hinzufügen“.
Speichern Sie den Token-Wert, vorzugsweise in einem Ansible-Vault.
Definieren Sie die folgenden Variablen in Ihrem Playbook:

jenkins_auth: "api"
jenkins_api_token: "(im Ansible Vault definiert)"
jenkins_api_username: "(im Ansible Vault definiert)"

Erstellen Sie ein Backup der Datei $JENKINS_HOME/users/the_username/config.xml, wobei the_username dem Benutzer entspricht, der das API-Token besitzt, das Sie gerade erstellt haben.
Fügen Sie diese Datei Ihrem Kontrollhost hinzu und stellen Sie sicher, dass sie im jenkins_custom_files-Verzeichnis an Jenkins bereitgestellt wird, wie folgt:

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

Beachten Sie, dass Sie den src-Wert möglicherweise ändern müssen, je nachdem, wo Sie die Datei auf der Steuerungsmaschine im Verhältnis zum Playbook speichern.

Crumb-basierte Authentifizierung

Die crumb-basierte Authentifizierung kann verwendet werden, um Angriffe durch Cross-Site-Request-Forgery zu verhindern und wird empfohlen, wenn API-Token nicht praktikabel sind. HINWEIS: Die crumb-basierte Authentifizierung funktioniert nur mit der Zugriffskontrolle „Jeder kann alles tun“. Wenn Ihre Jenkins-Konfiguration eine strengere Sicherheitskonfiguration erfordert, sollten Sie API-Token verwenden (siehe oben).

Die crumb-basierte Authentifizierung kann auch etwas knifflig sein, da es in Jenkins kürzlich Sicherheitsupdates gegeben hat. Um CSRF zu konfigurieren, müssen Sie Folgendes tun:

Wenn Sie Jenkins >= 2.176.2 verwenden, müssen Sie das Strict Crumb Issuer Plugin installieren. Dies kann durch diese Rolle geschehen, indem die ID strict-crumb-issuer zur Liste jenkins_plugins hinzugefügt wird.
Klicken Sie in Jenkins auf „Jenkins verwalten“ -> „Globale Sicherheit konfigurieren“.
Aktivieren Sie im Abschnitt „CSRF-Schutz“ die Option „Cross-Site-Request-Forgery-Ausnutzungen verhindern“ und wählen Sie dann „Strict Crumb Issuer“, wenn Sie Jenkins >= 2.176.2 verwenden, oder andernfalls „Standard Crumb Issuer“. Beachten Sie, dass Sie diese Option nur sehen, wenn das Strict Crumb Issuer Plugin installiert ist. Danach müssen Sie auch die Haupt-Jenkins-Datei config.xml auf den Kontrollhost sichern.

Damit dies funktioniert, benötigen Sie mindestens Ansible 2.9.0pre5 oder 2.10 (die, zum Zeitpunkt dieses Schreibens, beide in der Entwicklung sind. Siehe diesen Ansible-Fehler für weitere Details).

HTTPS

Wenn Sie HTTPS in Jenkins aktivieren möchten, können Sie dies wie folgt tun:

Definieren Sie jenkins_port_https auf den Port, auf dem Jenkins lauschen soll.
Definieren Sie Variablen entweder für den JKS-KeyStore oder das von einer CA signierte Zertifikat:
- Für JKS-KeyStore müssen Sie definieren:
  - jenkins_https_keystore: Pfad zur Keystore-Datei auf dem Kontrollhost, die von dieser Rolle auf den Jenkins-Server kopiert wird.
  - jenkins_https_keystore_password: Passwort für den entsprechenden JKS-KeyStore. Die Verwendung des Ansible-Vault wird empfohlen. WICHTIG: Dieser String wird im Klartext in die Jenkins-Konfigurationsdatei auf dem Server geschrieben. Er wird auch in der Prozessliste des Servers sichtbar sein. Ziehen Sie in Erwägung, Ihr Zertifikat in eine signierte Zertifikatdatei zu migrieren (siehe unten).
- Für eine von einer CA signierte Zertifikatdatei müssen Sie definieren:
  - jenkins_https_certificate: Pfad zur Zertifikatdatei, die von dieser Rolle auf den Jenkins-Server kopiert wird. Die Verwendung des Ansible-Vault wird für diese Datei empfohlen.
  - jenkins_https_private_key: Privater Schlüssel für das signierte Zertifikat. Die Verwendung des Ansible-Vault wird für diese Datei empfohlen.
Optional sollte jenkins_https_validate_certs auf false gesetzt werden, wenn Sie ein selbstsigniertes Zertifikat verwenden.

Wenn Sie Jenkins mit Docker bereitstellen, wird empfohlen, stattdessen einen Reverse-Proxy wie jwilder/nginx-proxy oder traefik zu verwenden, anstatt Jenkins selbst zu konfigurieren. Dies bietet etwas mehr Flexibilität und ermöglicht eine Trennung der Verantwortlichkeiten. Weitere Informationen zur Bereitstellung der Proxys und zur Konfiguration von HTTPS finden Sie in der Dokumentation zu diesen Projekten.

Wenn Sie einen Reverse-Proxy vor der Jenkins-Instanz verwenden und mit Docker bereitstellen, möchten Sie wahrscheinlich die Variable jenkins_docker_expose_port auf false setzen, damit der Port nicht auf dem Host freigegeben wird, sondern nur an den Reverse-Proxy.