emmetog.jenkins

Rôle Ansible pour Jenkins

Installe et configure complètement Jenkins en utilisant Ansible.

Ce rôle est utilisé lorsque vous souhaitez que toute votre configuration Jenkins soit sous contrôle de version, afin de déployer Jenkins de manière répétée et fiable, et de traiter Jenkins comme une vache plutôt qu'un animal de compagnie.

Si vous cherchez un rôle pour installer Jenkins et que vous souhaitez configurer tout via l'interface web sans vous soucier de déployer cette même instance de Jenkins entièrement configurée de manière répétée, alors ce rôle n'est pas nécessaire. Regardez plutôt le rôle geerlingguy/ansible-role-jenkins.

Exigences

Si vous déployez avec Docker, vous devez avoir Docker installé sur le serveur. Docker, apt-get et yum sont les seules méthodes supportées pour le moment, bien que d'autres méthodes puissent être ajoutées facilement, les contributions (PRs) sont les bienvenues.

Installation

Installez via Ansible Galaxy :

$ ansible-galaxy install emmetog.jenkins

Variables de rôle

Les variables suivantes influencent la manière dont Jenkins est installé :

jenkins_install_via: Contrôle la méthode d'installation de Jenkins. Important : Cette variable doit être définie sur une des valeurs suivantes :
- docker: Installer dans un conteneur Docker
- apt: Installer Jenkins directement sur les systèmes Linux Ubuntu/Debian
- yum: Installer Jenkins directement sur les systèmes Linux RedHat/CentOS
jenkins_version: La version exacte de Jenkins à installer

Les variables suivantes influencent la configuration de Jenkins :

jenkins_url: L'URL par laquelle Jenkins sera accessible
jenkins_port: Le port sur lequel Jenkins écoutera
jenkins_home: Le répertoire sur le serveur où les configurations de Jenkins seront stockées
jenkins_admin: L'adresse e-mail de l'administrateur du serveur Jenkins
jenkins_java_opts: Options passées à l'exécutable Java
jenkins_config_owner: Propriétaire des fichiers de configuration de Jenkins
jenkins_config_group: Groupe des fichiers de configuration de Jenkins
jenkins_auth: Comment Ansible doit s'authentifier auprès de Jenkins (voir la section "Authentification et Sécurité" ci-dessous)
jenkins_url_health_check: Quelle URL utiliser pour la vérification de santé après le démarrage de Jenkins (par défaut jenkins_url)
jenkins_health_check_user: si défini, utilise l'authentification basique (voir la section sur les tokens API) pour la vérification de santé avec ce nom d'utilisateur (utile si vous avez configuré par exemple Google OAuth)
jenkins_health_check_password: si défini, utilise l'authentification basique (voir la section sur les tokens API) pour la vérification de santé avec ce mot de passe (utile si vous avez configuré par exemple Google OAuth)

Les variables de liste suivantes influencent les tâches/plugins qui seront installés dans Jenkins :

jenkins_jobs: Liste des noms des tâches à copier dans Jenkins. Le fichier config.xml doit exister sous jenkins_source_dir_jobs/<job_name>
jenkins_plugins: Liste des ID de plugins à installer sur Jenkins.
jenkins_custom_plugins: Liste des plugins personnalisés à installer sur Jenkins.

Pour une liste complète des variables, consultez defaults/main.yml.

Exemple de Playbook

- 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

Gestion des fichiers de configuration

L'exemple ci-dessus recherchera les fichiers de configuration des tâches dans {{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xml et {{ playbook_dir }}/jenkins-configs/jobs/another-awesome-job/config.xml.

REMARQUE : Ces répertoires sont personnalisables, consultez les variables de rôle jenkins_source_dir_configs et jenkins_source_dir_jobs.

Le rôle recherchera également {{ playbook_dir }}/jenkins-configs/config.xml Ce fichier config.xml sera copié sur le serveur et utilisé comme modèle de configuration pour les tâches.

L'exemple ci-dessus téléchargera également l'intégralité du répertoire des secrets sous {{ playbook_dir }}/jenkins-configs/secrets, et copiera également les fichiers personnalisés définis dans la variable {{ jenkins_custom_files }}. Notez que les variables {{ jenkins_include_secrets }} et {{ jenkins_include_custom_files }} doivent être définies sur true pour que ces fonctionnalités fonctionnent. De plus, le rôle peut installer des plugins personnalisés en fournissant les fichiers .jpi ou .hpi dans la variable de liste {{ jenkins_custom_plugins }}.

Le fichier config.xml et les fichiers personnalisés sont traités comme des modèles, vous pouvez donc y mettre des variables, y compris des données sensibles provenant du coffre-fort Ansible.

Lorsque vous souhaitez apporter une modification dans un fichier de configuration, ou ajouter un nouvel élément (comme une tâche, un plugin, etc.), le flux de travail normal est :

Faites le changement dans l'interface utilisateur de Jenkins
Copiez les fichiers XML résultants dans votre VCS
Pour les fichiers nouvellement créés, n'oubliez pas de les ajouter à la liste correspondante :

Pour les nouvelles tâches, elles doivent être ajoutées à jenkins_jobs
Pour les fichiers personnalisés, ils doivent être ajoutés à jenkins_include_custom_files
Pour les plugins personnalisés, ils doivent être ajoutés à jenkins_custom_plugins

Exemple de fichier de configuration Jenkins

Dans {{ jenkins_source_dir_configs }}/config.xml, vous mettez votre configuration globale de Jenkins, par exemple :

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

Exemple de fichier de configuration de tâche

Voici un exemple de ce que vous pourriez mettre dans {{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xml :

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description>Ma première tâche, elle dit "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>

Authentification et Sécurité

Ce rôle prend en charge les mécanismes d'authentification suivants pour Jenkins :

Authentification basée sur token API (recommandée, nécessite au moins Jenkins 2.96)
Authentification basée sur un jeton de contrôle avec le plugin Strict Crumb Issuer (nécessaire si vous n'utilisez pas de tokens API et Jenkins 2.176.2 ou plus récent)
Aucune sécurité (non recommandé)

Authentification basée sur token API

L'authentification basée sur token API est recommandée, mais nécessite un peu plus d'efforts pour la configuration. L'avantage des tokens API est qu'ils peuvent être facilement révoqués dans Jenkins, et leur utilisation est également suivie. Les tokens API ne nécessitent également pas d'obtenir un jeton de contrôle, ce qui est devenu plus difficile depuis la version 2.172.2 de Jenkins (voir cet avis de sécurité.

Pour créer un token API, vous devrez suivre les étapes suivantes :

Tous les tokens API doivent appartenir à un utilisateur spécifique. Créez donc un utilisateur spécial pour les déploiements, ou connectez-vous en tant qu'administrateur ou autre compte.
Dans la page de configuration de l'utilisateur, cliquez sur le bouton "Ajouter un nouveau Token".
Enregistrez la valeur du token, de préférence dans un coffre-fort Ansible.
Définissez les variables suivantes dans votre playbook :

jenkins_auth: "api"
jenkins_api_token: "(défini dans le coffre-fort Ansible)"
jenkins_api_username: "(défini dans le coffre-fort Ansible)"

Créez une sauvegarde du fichier $JENKINS_HOME/users/the_username/config.xml, où the_username correspond à l'utilisateur qui possède le token API que vous avez créé.
Ajoutez ce fichier à votre hôte de contrôle, et assurez-vous qu'il soit déployé sur Jenkins dans la liste jenkins_custom_files, comme ceci :

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

Notez que vous devrez peut-être changer la valeur src, selon l'endroit où vous sauvegardez le fichier sur la machine de contrôle par rapport au playbook.

Authentification basée sur un jeton de contrôle

L'authentification basée sur un jeton de contrôle peut être utilisée pour prévenir les attaques par contournement de site (CSRF) et est recommandée si les tokens API ne sont pas pratiques. Remarque : l'authentification basée sur un jeton de contrôle ne fonctionne qu'avec le paramètre de contrôle d'accès "Tout le monde peut tout faire". Si votre configuration Jenkins nécessite une mise en place de sécurité plus stricte, vous devez utiliser des tokens API (documentés ci-dessus).

L'authentification basée sur un jeton de contrôle peut également être un peu délicate à configurer en raison des récentes correctifs de sécurité dans Jenkins. Pour configurer CSRF, vous devez faire ce qui suit :

Si vous utilisez Jenkins >= 2.176.2, vous devez installer le plugin Strict Crumb Issuer. Cela peut être fait par ce rôle en ajoutant l'ID strict-crumb-issuer à la liste jenkins_plugins.
Dans Jenkins, cliquez sur "Gérer Jenkins" -> "Configurer la sécurité globale"
Dans la section "Protection CSRF", activez "Prévenir les attaques CSRF", puis sélectionnez "Strict Crumb Issuer" si vous utilisez Jenkins >= 2.176.2, ou sinon "Default Crumb Issuer". Notez que pour voir cette option, vous devez avoir installé le plugin Strict Crumb Issuer. Par la suite, vous devrez également sauvegarder le fichier principal config.xml de Jenkins sur l'hôte de contrôle.

De même, pour que cela fonctionne, vous aurez besoin d'Ansible version 2.9.0pre5 ou 2.10 au moins (qui sont, au moment de la rédaction, tous deux en développement. Voir ce problème Ansible pour plus de détails).

HTTPS

Si vous souhaitez activer HTTPS sur Jenkins, cela peut être fait comme suit :

Définissez jenkins_port_https sur le port sur lequel Jenkins doit écouter
Définissez des variables soit pour le magasin de clés JKS, soit pour le certificat signé par une autorité de certification :
- Pour le magasin de clés JKS, vous devez définir :
  - jenkins_https_keystore: Chemin d'accès au fichier de magasin de clés sur l'hôte de contrôle, qui sera copié sur le serveur Jenkins par ce rôle.
  - jenkins_https_keystore_password: Mot de passe pour le magasin de clés JKS. L'utilisation d'un coffre-fort Ansible est recommandée pour cela. IMPORTANT : Cette chaîne sera écrite en texte clair dans le fichier de configuration de Jenkins sur le serveur. Elle sera également visible dans la liste des processus du serveur. Envisagez de migrer votre certificat vers un fichier de certificat signé (voir ci-dessous).
- Pour un fichier de certificat signé par une autorité, vous devez définir :
  - jenkins_https_certificate: Chemin d'accès au fichier de certificat, qui sera copié sur le serveur Jenkins par ce rôle. L'utilisation d'un coffre-fort Ansible est recommandée pour ce fichier.
  - jenkins_https_private_key: Clé privée pour le certificat signé par l'autorité. L'utilisation d'un coffre-fort Ansible est recommandée pour ce fichier.
En option, jenkins_https_validate_certs doit être défini sur false si vous utilisez un certificat auto-signé.

Si vous déployez Jenkins avec Docker, l'utilisation d'un proxy inverse tel que jwilder/nginx-proxy ou traefik est recommandée au lieu de configurer Jenkins lui-même. Cela offre un peu plus de flexibilité et permet de séparer les responsabilités. Consultez la documentation de ces projets pour plus de détails sur la façon de déployer les proxys et configurer HTTPS.

Si vous utilisez un proxy inverse devant l'instance Jenkins et déployez avec Docker, vous voudrez probablement définir la variable jenkins_docker_expose_port sur false pour que le port ne soit pas exposé sur l'hôte, mais uniquement au proxy inverse.