Chapitre 5. Jenkins

Vous pouvez gérer l'authentification Jenkins de deux manières :

Le serveur Jenkins peut être configuré avec les variables d'environnement suivantes :

Si vous voulez exécuter Jenkins ailleurs que dans votre projet, vous devez fournir un jeton d'accès à Jenkins pour qu'il puisse accéder à votre projet.

L'image Jenkins peut être exécutée avec des volumes montés pour permettre un stockage persistant de la configuration :

Pour personnaliser l'image Jenkins officielle d'OpenShift Container Platform, vous pouvez utiliser l'image en tant que source-to-image (S2I).

Vous pouvez utiliser S2I pour copier vos définitions de tâches Jenkins personnalisées, ajouter des plugins supplémentaires ou remplacer le fichier config.xml fourni par votre propre configuration.

Pour inclure vos modifications dans l'image Jenkins, vous devez disposer d'un dépôt Git avec la structure de répertoire suivante :

pluginId:pluginVersion

pluginId:pluginVersion

Le contenu du répertoire configuration/ est copié dans le répertoire /var/lib/jenkins/, de sorte que vous pouvez également y inclure des fichiers supplémentaires, tels que credentials.xml.

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: custom-jenkins-build
spec:
  source:                       
    git:
      uri: https://github.com/custom/repository
    type: Git
  strategy:                     
    sourceStrategy:
      from:
        kind: ImageStreamTag
        name: jenkins:2
        namespace: openshift
    type: Source
  output:                       
    to:
      kind: ImageStreamTag
      name: custom-jenkins:latest

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: custom-jenkins-build
spec:
  source:                       

    git:
      uri: https://github.com/custom/repository
    type: Git
  strategy:                     

    sourceStrategy:
      from:
        kind: ImageStreamTag
        name: jenkins:2
        namespace: openshift
    type: Source
  output:                       

    to:
      kind: ImageStreamTag
      name: custom-jenkins:latest

L'image OpenShift Jenkins inclut le plugin Kubernetes préinstallé pour Jenkins afin que les agents Jenkins puissent être provisionnés dynamiquement sur plusieurs hôtes de conteneurs en utilisant Kubernetes et OpenShift Container Platform.

Pour utiliser le plugin Kubernetes, OpenShift Container Platform fournit une image OpenShift Agent Base qui peut être utilisée comme agent Jenkins.

Les images des agents Maven et Node.js sont automatiquement configurées en tant qu'images de modèle de pod Kubernetes dans la configuration d'image Jenkins de la plateforme OpenShift Container pour le plugin Kubernetes. Cette configuration comprend des étiquettes pour chaque image que vous pouvez appliquer à tous vos travaux Jenkins sous leur paramètre Restrict where this project can be run. Si le label est appliqué, les travaux s'exécutent sous un pod OpenShift Container Platform exécutant l'image d'agent correspondante.

L'image Jenkins permet également l'auto-découverte et l'auto-configuration d'images d'agents supplémentaires pour le plugin Kubernetes.

Avec le plugin de synchronisation OpenShift Container Platform, au démarrage de Jenkins, l'image Jenkins recherche dans le projet qu'elle exécute, ou dans les projets listés dans la configuration du plugin, les éléments suivants :

Lorsque l'image Jenkins trouve un flux d'images avec l'étiquette appropriée, ou une balise de flux d'images avec l'annotation appropriée, elle génère la configuration du plugin Kubernetes correspondant. De cette façon, vous pouvez affecter vos travaux Jenkins à l'exécution d'un pod utilisant l'image de conteneur fournie par le flux d'images.

Les références de nom et d'image du flux d'images ou de la balise de flux d'images sont mises en correspondance avec les champs de nom et d'image dans le modèle de pod du plugin Kubernetes. Vous pouvez contrôler le champ label du modèle de pod de plugin Kubernetes en définissant une annotation sur l'objet flux d'images ou balise de flux d'images avec la clé agent-label. Sinon, le nom est utilisé comme étiquette.

Lorsqu'elle trouve une carte de configuration avec l'étiquette appropriée, l'image Jenkins suppose que toutes les valeurs de la charge utile de données clé-valeur de la carte de configuration contiennent un langage de balisage extensible (XML) cohérent avec le format de configuration pour Jenkins et les modèles de pods du plugin Kubernetes. L'un des principaux avantages des cartes de configuration par rapport aux flux d'images et aux balises de flux d'images est que vous pouvez contrôler tous les paramètres du modèle de pod plugin Kubernetes.

kind: ConfigMap
apiVersion: v1
metadata:
  name: jenkins-agent
  labels:
    role: jenkins-agent
data:
  template1: |-
    <org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
      <inheritFrom></inheritFrom>
      <name>template1</name>
      <instanceCap>2147483647</instanceCap>
      <idleMinutes>0</idleMinutes>
      <label>template1</label>
      <serviceAccount>jenkins</serviceAccount>
      <nodeSelector></nodeSelector>
      <volumes/>
      <containers>
        <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
          <name>jnlp</name>
          <image>openshift/jenkins-agent-maven-35-centos7:v3.10</image>
          <privileged>false</privileged>
          <alwaysPullImage>true</alwaysPullImage>
          <workingDir>/tmp</workingDir>
          <command></command>
          <args>${computer.jnlpmac} ${computer.name}</args>
          <ttyEnabled>false</ttyEnabled>
          <resourceRequestCpu></resourceRequestCpu>
          <resourceRequestMemory></resourceRequestMemory>
          <resourceLimitCpu></resourceLimitCpu>
          <resourceLimitMemory></resourceLimitMemory>
          <envVars/>
        </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
      </containers>
      <envVars/>
      <annotations/>
      <imagePullSecrets/>
      <nodeProperties/>
    </org.csanchez.jenkins.plugins.kubernetes.PodTemplate>

kind: ConfigMap
apiVersion: v1
metadata:
  name: jenkins-agent
  labels:
    role: jenkins-agent
data:
  template1: |-
    <org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
      <inheritFrom></inheritFrom>
      <name>template1</name>
      <instanceCap>2147483647</instanceCap>
      <idleMinutes>0</idleMinutes>
      <label>template1</label>
      <serviceAccount>jenkins</serviceAccount>
      <nodeSelector></nodeSelector>
      <volumes/>
      <containers>
        <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
          <name>jnlp</name>
          <image>openshift/jenkins-agent-maven-35-centos7:v3.10</image>
          <privileged>false</privileged>
          <alwaysPullImage>true</alwaysPullImage>
          <workingDir>/tmp</workingDir>
          <command></command>
          <args>${computer.jnlpmac} ${computer.name}</args>
          <ttyEnabled>false</ttyEnabled>
          <resourceRequestCpu></resourceRequestCpu>
          <resourceRequestMemory></resourceRequestMemory>
          <resourceLimitCpu></resourceLimitCpu>
          <resourceLimitMemory></resourceLimitMemory>
          <envVars/>
        </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
      </containers>
      <envVars/>
      <annotations/>
      <imagePullSecrets/>
      <nodeProperties/>
    </org.csanchez.jenkins.plugins.kubernetes.PodTemplate>

L'exemple suivant montre deux conteneurs qui référencent des flux d'images dans l'espace de noms openshift. L'un des conteneurs gère le contrat JNLP pour lancer des pods en tant qu'agents Jenkins. L'autre conteneur utilise une image contenant des outils de construction de code dans un langage de codage particulier :

kind: ConfigMap
apiVersion: v1
metadata:
  name: jenkins-agent
  labels:
    role: jenkins-agent
data:
  template2: |-
        <org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
          <inheritFrom></inheritFrom>
          <name>template2</name>
          <instanceCap>2147483647</instanceCap>
          <idleMinutes>0</idleMinutes>
          <label>template2</label>
          <serviceAccount>jenkins</serviceAccount>
          <nodeSelector></nodeSelector>
          <volumes/>
          <containers>
            <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
              <name>jnlp</name>
              <image>image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base-rhel8:latest</image>
              <privileged>false</privileged>
              <alwaysPullImage>true</alwaysPullImage>
              <workingDir>/home/jenkins/agent</workingDir>
              <command></command>
              <args>\$(JENKINS_SECRET) \$(JENKINS_NAME)</args>
              <ttyEnabled>false</ttyEnabled>
              <resourceRequestCpu></resourceRequestCpu>
              <resourceRequestMemory></resourceRequestMemory>
              <resourceLimitCpu></resourceLimitCpu>
              <resourceLimitMemory></resourceLimitMemory>
              <envVars/>
            </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
            <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
              <name>java</name>
              <image>image-registry.openshift-image-registry.svc:5000/openshift/java:latest</image>
              <privileged>false</privileged>
              <alwaysPullImage>true</alwaysPullImage>
              <workingDir>/home/jenkins/agent</workingDir>
              <command>cat</command>
              <args></args>
              <ttyEnabled>true</ttyEnabled>
              <resourceRequestCpu></resourceRequestCpu>
              <resourceRequestMemory></resourceRequestMemory>
              <resourceLimitCpu></resourceLimitCpu>
              <resourceLimitMemory></resourceLimitMemory>
              <envVars/>
            </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
          </containers>
          <envVars/>
          <annotations/>
          <imagePullSecrets/>
          <nodeProperties/>
        </org.csanchez.jenkins.plugins.kubernetes.PodTemplate>

kind: ConfigMap
apiVersion: v1
metadata:
  name: jenkins-agent
  labels:
    role: jenkins-agent
data:
  template2: |-
        <org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
          <inheritFrom></inheritFrom>
          <name>template2</name>
          <instanceCap>2147483647</instanceCap>
          <idleMinutes>0</idleMinutes>
          <label>template2</label>
          <serviceAccount>jenkins</serviceAccount>
          <nodeSelector></nodeSelector>
          <volumes/>
          <containers>
            <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
              <name>jnlp</name>
              <image>image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base-rhel8:latest</image>
              <privileged>false</privileged>
              <alwaysPullImage>true</alwaysPullImage>
              <workingDir>/home/jenkins/agent</workingDir>
              <command></command>
              <args>\$(JENKINS_SECRET) \$(JENKINS_NAME)</args>
              <ttyEnabled>false</ttyEnabled>
              <resourceRequestCpu></resourceRequestCpu>
              <resourceRequestMemory></resourceRequestMemory>
              <resourceLimitCpu></resourceLimitCpu>
              <resourceLimitMemory></resourceLimitMemory>
              <envVars/>
            </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
            <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
              <name>java</name>
              <image>image-registry.openshift-image-registry.svc:5000/openshift/java:latest</image>
              <privileged>false</privileged>
              <alwaysPullImage>true</alwaysPullImage>
              <workingDir>/home/jenkins/agent</workingDir>
              <command>cat</command>
              <args></args>
              <ttyEnabled>true</ttyEnabled>
              <resourceRequestCpu></resourceRequestCpu>
              <resourceRequestMemory></resourceRequestMemory>
              <resourceLimitCpu></resourceLimitCpu>
              <resourceLimitMemory></resourceLimitMemory>
              <envVars/>
            </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
          </containers>
          <envVars/>
          <annotations/>
          <imagePullSecrets/>
          <nodeProperties/>
        </org.csanchez.jenkins.plugins.kubernetes.PodTemplate>

Une fois installé, le plugin OpenShift Container Platform Sync surveille le serveur API d'OpenShift Container Platform pour les mises à jour des flux d'images, des balises de flux d'images et des cartes de configuration et ajuste la configuration du plugin Kubernetes.

Les règles suivantes s'appliquent :

Pour utiliser une image de conteneur comme agent Jenkins, l'image doit exécuter l'agent comme point d'entrée. Pour plus de détails, voir la documentation officielle de Jenkins.

Si, dans la carte de configuration, l'élément <serviceAccount> du modèle XML de pod est le compte de service OpenShift Container Platform utilisé pour le pod résultant, les informations d'identification du compte de service sont montées dans le pod. Les permissions sont associées au compte de service et contrôlent quelles opérations contre le maître OpenShift Container Platform sont autorisées à partir du pod.

Considérons le scénario suivant avec des comptes de service utilisés pour le pod, qui est lancé par le plugin Kubernetes qui s'exécute dans l'image Jenkins d'OpenShift Container Platform.

Si vous utilisez le modèle d'exemple pour Jenkins fourni par OpenShift Container Platform, le compte de service jenkins est défini avec le rôle edit pour le projet dans lequel Jenkins s'exécute, et le pod Jenkins maître a ce compte de service monté.

Les deux modèles de pods Maven et NodeJS par défaut qui sont injectés dans la configuration Jenkins sont également configurés pour utiliser le même compte de service que le maître Jenkins.

Les modèles fournissent des champs de paramètres pour définir toutes les variables d'environnement avec des valeurs par défaut prédéfinies. OpenShift Container Platform fournit des modèles pour faciliter la création d'un nouveau service Jenkins. Les modèles Jenkins doivent être enregistrés dans le projet par défaut openshift par votre administrateur de cluster lors de la configuration initiale du cluster.

Les deux modèles disponibles définissent tous deux une configuration de déploiement et un service. Les modèles diffèrent par leur stratégie de stockage, qui détermine si le contenu de Jenkins persiste après le redémarrage d'un pod.

Pour utiliser un magasin PV, l'administrateur du cluster doit définir un pool PV dans le déploiement d'OpenShift Container Platform.

Après avoir sélectionné le modèle que vous souhaitez, vous devez l'instancier pour pouvoir utiliser Jenkins.

Avec les deux modèles, vous pouvez lancer oc describe sur eux pour voir tous les paramètres disponibles pour la surcharge.

Par exemple :

oc describe jenkins-ephemeral

$ oc describe jenkins-ephemeral

Dans l'exemple suivant, l'objet openshift-jee-sample BuildConfig provoque le provisionnement dynamique d'un pod d'agent Maven Jenkins. Le pod clone du code source Java, construit un fichier WAR et provoque l'exécution d'un second BuildConfig, openshift-jee-sample-docker. Le second BuildConfig place le nouveau fichier WAR dans une image de conteneur.

kind: List
apiVersion: v1
items:
- kind: ImageStream
  apiVersion: image.openshift.io/v1
  metadata:
    name: openshift-jee-sample
- kind: BuildConfig
  apiVersion: build.openshift.io/v1
  metadata:
    name: openshift-jee-sample-docker
  spec:
    strategy:
      type: Docker
    source:
      type: Docker
      dockerfile: |-
        FROM openshift/wildfly-101-centos7:latest
        COPY ROOT.war /wildfly/standalone/deployments/ROOT.war
        CMD $STI_SCRIPTS_PATH/run
      binary:
        asFile: ROOT.war
    output:
      to:
        kind: ImageStreamTag
        name: openshift-jee-sample:latest
- kind: BuildConfig
  apiVersion: build.openshift.io/v1
  metadata:
    name: openshift-jee-sample
  spec:
    strategy:
      type: JenkinsPipeline
      jenkinsPipelineStrategy:
        jenkinsfile: |-
          node("maven") {
            sh "git clone https://github.com/openshift/openshift-jee-sample.git ."
            sh "mvn -B -Popenshift package"
            sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war"
          }
    triggers:
    - type: ConfigChange

kind: List
apiVersion: v1
items:
- kind: ImageStream
  apiVersion: image.openshift.io/v1
  metadata:
    name: openshift-jee-sample
- kind: BuildConfig
  apiVersion: build.openshift.io/v1
  metadata:
    name: openshift-jee-sample-docker
  spec:
    strategy:
      type: Docker
    source:
      type: Docker
      dockerfile: |-
        FROM openshift/wildfly-101-centos7:latest
        COPY ROOT.war /wildfly/standalone/deployments/ROOT.war
        CMD $STI_SCRIPTS_PATH/run
      binary:
        asFile: ROOT.war
    output:
      to:
        kind: ImageStreamTag
        name: openshift-jee-sample:latest
- kind: BuildConfig
  apiVersion: build.openshift.io/v1
  metadata:
    name: openshift-jee-sample
  spec:
    strategy:
      type: JenkinsPipeline
      jenkinsPipelineStrategy:
        jenkinsfile: |-
          node("maven") {
            sh "git clone https://github.com/openshift/openshift-jee-sample.git ."
            sh "mvn -B -Popenshift package"
            sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war"
          }
    triggers:
    - type: ConfigChange

Il est également possible d'outrepasser la spécification du pod de l'agent Jenkins créé dynamiquement. L'exemple suivant est une modification de l'exemple précédent, qui surcharge la mémoire du conteneur et spécifie une variable d'environnement.

kind: BuildConfig
apiVersion: build.openshift.io/v1
metadata:
  name: openshift-jee-sample
spec:
  strategy:
    type: JenkinsPipeline
    jenkinsPipelineStrategy:
      jenkinsfile: |-
        podTemplate(label: "mypod", 
                    cloud: "openshift", 
                    inheritFrom: "maven", 
                    containers: [
            containerTemplate(name: "jnlp", 
                              image: "openshift/jenkins-agent-maven-35-centos7:v3.10", 
                              resourceRequestMemory: "512Mi", 
                              resourceLimitMemory: "512Mi", 
                              envVars: [
              envVar(key: "CONTAINER_HEAP_PERCENT", value: "0.25") 
            ])
          ]) {
          node("mypod") { 
            sh "git clone https://github.com/openshift/openshift-jee-sample.git ."
            sh "mvn -B -Popenshift package"
            sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war"
          }
        }
  triggers:
  - type: ConfigChange

kind: BuildConfig
apiVersion: build.openshift.io/v1
metadata:
  name: openshift-jee-sample
spec:
  strategy:
    type: JenkinsPipeline
    jenkinsPipelineStrategy:
      jenkinsfile: |-
        podTemplate(label: "mypod", 

                    cloud: "openshift", 

                    inheritFrom: "maven", 

                    containers: [
            containerTemplate(name: "jnlp", 

                              image: "openshift/jenkins-agent-maven-35-centos7:v3.10", 

                              resourceRequestMemory: "512Mi", 

                              resourceLimitMemory: "512Mi", 

                              envVars: [
              envVar(key: "CONTAINER_HEAP_PERCENT", value: "0.25") 

            ])
          ]) {
          node("mypod") { 

            sh "git clone https://github.com/openshift/openshift-jee-sample.git ."
            sh "mvn -B -Popenshift package"
            sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war"
          }
        }
  triggers:
  - type: ConfigChange

Par défaut, le pod est supprimé lorsque la construction est terminée. Ce comportement peut être modifié avec le plugin ou dans un fichier Jenkins du pipeline.

Upstream Jenkins a récemment introduit un format déclaratif YAML pour définir un DSL de pipeline podTemplate en ligne avec vos pipelines. Un exemple de ce format, utilisant le modèle de pod java-builder défini dans l'image Jenkins de OpenShift Container Platform :

def nodeLabel = 'java-buidler'

pipeline {
  agent {
    kubernetes {
      cloud 'openshift'
      label nodeLabel
      yaml """
apiVersion: v1
kind: Pod
metadata:
  labels:
    worker: ${nodeLabel}
spec:
  containers:
  - name: jnlp
    image: image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base-rhel8:latest
    args: ['\$(JENKINS_SECRET)', '\$(JENKINS_NAME)']
  - name: java
    image: image-registry.openshift-image-registry.svc:5000/openshift/java:latest
    command:
    - cat
    tty: true
"""
    }
  }

  options {
    timeout(time: 20, unit: 'MINUTES')
  }

  stages {
    stage('Build App') {
      steps {
        container("java") {
          sh "mvn --version"
        }
     }
    }
  }
}

def nodeLabel = 'java-buidler'

pipeline {
  agent {
    kubernetes {
      cloud 'openshift'
      label nodeLabel
      yaml """
apiVersion: v1
kind: Pod
metadata:
  labels:
    worker: ${nodeLabel}
spec:
  containers:
  - name: jnlp
    image: image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base-rhel8:latest
    args: ['\$(JENKINS_SECRET)', '\$(JENKINS_NAME)']
  - name: java
    image: image-registry.openshift-image-registry.svc:5000/openshift/java:latest
    command:
    - cat
    tty: true
"""
    }
  }

  options {
    timeout(time: 20, unit: 'MINUTES')
  }

  stages {
    stage('Build App') {
      steps {
        container("java") {
          sh "mvn --version"
        }
     }
    }
  }
}

Lorsqu'il est déployé par les modèles Jenkins Ephemeral ou Jenkins Persistent fournis, la limite de mémoire par défaut est de 1 Gi.

Par défaut, tous les autres processus qui s'exécutent dans le conteneur Jenkins ne peuvent pas utiliser plus de 512 MiB de mémoire. S'ils ont besoin de plus de mémoire, le conteneur s'arrête. Il est donc fortement recommandé que les pipelines exécutent des commandes externes dans un conteneur d'agent dans la mesure du possible.

Et si les quotas de Project le permettent, voir les recommandations de la documentation Jenkins sur ce qu'un maître Jenkins devrait avoir du point de vue de la mémoire. Ces recommandations préconisent d'allouer encore plus de mémoire au maître Jenkins.

Il est recommandé de spécifier les valeurs de demande et de limite de mémoire sur les conteneurs d'agents créés par le plugin Jenkins Kubernetes. Les administrateurs peuvent définir des valeurs par défaut pour chaque image d'agent via la configuration de Jenkins. Les paramètres de demande et de limite de mémoire peuvent également être modifiés pour chaque conteneur.

Vous pouvez augmenter la quantité de mémoire disponible pour Jenkins en remplaçant le paramètre MEMORY_LIMIT lors de l'instanciation du modèle Jenkins Ephemeral ou Jenkins Persistent.