Jenkins

Jenkins 認証は、以下の 2 つの方法で管理できます。

Jenkins サーバーは、以下の環境変数で設定できます。

同じプロジェクト以外で Jenkins を実行する場合は、プロジェクトにアクセスするために、Jenkins にアクセストークンを提供する必要があります。

Jenkins イメージはマウントしたボリュームで実行して、設定用に永続ストレージを有効にできます。

Red Hat OpenShift Service on AWS の公式の Jenkins イメージをカスタマイズするには、イメージを Source-to-Image (S2I) ビルダーとして使用できます。

S2I を使用して、カスタムの Jenkins ジョブ定義をコピーしたり、プラグインを追加したり、同梱の config.xml ファイルを独自のカスタムの設定に置き換えたりできます。

Jenkins イメージに変更を追加するには、以下のディレクトリー構造の Git リポジトリーが必要です。

pluginId:pluginVersion

configuration/ ディレクトリーのコンテンツは /var/lib/jenkins/ ディレクトリーにコピーされるため、このディレクトリーに credentials.xml などのファイルをさらに追加することもできます。

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

OpenShift Jenkins イメージにはプリインストールされた Jenkins 用の Kubernetes プラグイン が含まれています。そのため、Kubernetes と Red Hat OpenShift Service on AWS を使用して、複数のコンテナーホストで Jenkins エージェントを動的にプロビジョニングできます。

Kubernetes プラグインを使用するために、Red Hat OpenShift Service on AWS は、Jenkins エージェントとして使用するのに適した OpenShift Agent Base イメージを提供します。

Maven および Node.js のエージェントイメージは、Kubernetes プラグイン用の Red Hat OpenShift Service on AWS Jenkins イメージの設定内で、Kubernetes Pod テンプレートイメージとして自動的に設定されます。この設定には、Restrict where this project can be run 設定で任意の Jenkins ジョブに適用できる各イメージのラベルが含まれています。ラベルが適用されている場合、ジョブはそれぞれのエージェントイメージを実行する Red Hat OpenShift Service on AWS の Pod で実行されます。

Jenkins イメージは、Kubernetes プラグイン向けの追加エージェントイメージの自動検出および自動設定も提供します。

Red Hat OpenShift Service on AWS 同期プラグインを使用すると、Jenkins の起動時に、Jenkins イメージが実行中のプロジェクト内、またはプラグインの設定にリストされているプロジェクト内で以下の項目を検索します。

Jenkins イメージは、適切なラベルを持つイメージストリーム、または適切なアノテーションを持つイメージストリームタグを見つけると、対応する Kubernetes プラグイン設定を生成します。このようにして、イメージストリームによって提供されるコンテナーイメージを実行する Pod で実行するように Jenkins ジョブを割り当てることができます。

イメージストリームまたはイメージストリームタグの名前とイメージ参照は、Kubernetes プラグインの Pod テンプレートにある名前およびイメージフィールドにマッピングされます。Kubernetes プラグインの Pod テンプレートのラベルフィールドは、agent-label キーを使用してイメージストリームまたはイメージストリームタグオブジェクトにアノテーションを設定することで制御できます。これらを使用しない場合には、名前をラベルとして使用します。

適切なラベルを持つ config map が見つかると、Jenkins イメージは、config map のキーと値のデータペイロードの任意の値に、Jenkins および Kubernetes プラグイン Pod テンプレートの設定形式と一致する Extensible Markup Language (XML) が含まれていると想定します。イメージストリームやイメージストリームタグに対する config map の主な利点の 1 つは、すべての Kubernetes プラグイン Pod テンプレートパラメーターを制御できることです。

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>

以下の例は、openshift namespace のイメージストリームを参照する 2 つのコンテナーを示しています。1 つのコンテナーが、Pod を Jenkins エージェントとして起動するための JNLP コントラクトを処理します。もう 1 つのコンテナーは、特定のコーディング言語でコードを構築するためのツールを備えたイメージを使用します。

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>

Red Hat OpenShift Service on AWS 同期プラグインは、インストール後、Red Hat OpenShift Service on AWS の API サーバーを監視して、イメージストリーム、イメージストリームタグ、および config map の更新を確認し、Kubernetes プラグインの設定を調整します。

以下のルールが適用されます。

Jenkins エージェントとしてコンテナーイメージを使用するには、イメージが、エントリーポイントとしてエージェントを実行する必要があります。詳細は、公式の Jenkins ドキュメント を参照してください。

config map で、Pod テンプレート XML の <serviceAccount> 要素が、作成される Pod に使用される Red Hat OpenShift Service on AWS サービスアカウントである場合に、サービスアカウントの認証情報が Pod にマウントされます。パーミッションは、サービスアカウントに関連付けられ、Red Hat OpenShift Service on AWS のマスターに対して Pod から許可される操作を制御します。

Red Hat OpenShift Service on AWS で動作する Kubernetes プラグインによって起動される Pod に使用するサービスアカウントについては、以下の手順を使用することを検討してください。

Red Hat OpenShift Service on AWS が備えている Jenkins のサンプルテンプレートを使用する場合は、Jenkins が実行されるプロジェクトの edit ロールで jenkins サービスアカウントを定義して、マスターの Jenkins Pod にそのサービスアカウントをマウントします。

Jenkins 設定に挿入される 2 つのデフォルトの Maven および NodeJS Pod テンプレートも、Jenkins マスターと同じサービスアカウントを使用するように設定します。

テンプレートには各種パラメーターフィールドがあり、事前定義されたデフォルト値ですべての環境変数を定義できます。Red Hat OpenShift Service on AWS は、新しい Jenkins サービスを簡単に作成するためのテンプレートを備えています。Jenkins テンプレートは、クラスター管理者が、クラスターの初期設定時に、デフォルトの openshift プロジェクトに登録する必要があります。

使用可能な 2 つのテンプレートは共にデプロイメント設定とサービスを定義します。テンプレートはストレージストラテジーに応じて異なります。これは、Jenkins コンテンツが Pod の再起動時に永続するかどうかに影響を与えます。

PV ストアを使用するには、クラスター管理者が Red Hat OpenShift Service on AWS デプロイメントで PV プールを定義する必要があります。

必要なテンプレートを選択したら、テンプレートをインスタンス化して Jenkins を使用できるようにする必要があります。

両方のテンプレートで、それらに対して oc describe を実行して、オーバーライドに使用できるすべてのパラメーターを確認できます。

以下に例を示します。

$ oc describe jenkins-ephemeral

以下の例では、openshift-jee-sample BuildConfig オブジェクトにより、Jenkins Maven エージェント Pod が動的にプロビジョニングされます。Pod は Java ソースコードをクローンし、WAR ファイルを作成して、2 番目の BuildConfig、openshift-jee-sample-docker を実行します。2 番目の BuildConfig は、新しい WAR ファイルをコンテナーイメージに階層化します。

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

動的に作成された Jenkins エージェント Pod の仕様を上書きすることも可能です。以下は、コンテナーメモリーを上書きして、環境変数を指定するように先の例を変更しています。

kind: BuildConfig
apiVersion: build.openshift.io/v1
metadata:
  name: openshift-jee-sample
spec:
  strategy:
    type: JenkinsPipeline
    jenkinsPipelineStrategy:
      jenkinsfile: |-
        podTemplate(label: "mypod", 1
                    cloud: "openshift", 2
                    inheritFrom: "maven", 3
                    containers: [
            containerTemplate(name: "jnlp", 4
                              image: "openshift/jenkins-agent-maven-35-centos7:v3.10", 5
                              resourceRequestMemory: "512Mi", 6
                              resourceLimitMemory: "512Mi", 7
                              envVars: [
              envVar(key: "CONTAINER_HEAP_PERCENT", value: "0.25") 8
            ])
          ]) {
          node("mypod") { 9
            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

デフォルトで、Pod はビルドの完了時に削除されます。この動作は、プラグインを使用して、またはパイプライン Jenkinsfile 内で変更できます。

アップストリームの Jenkins では少し前に、パイプラインとインラインで podTemplate パイプライン DSL を定義するための YAML 宣言型フォーマットが導入されました。このフォーマットの例を次に示します。Red Hat OpenShift Service on AWS の Jenkins イメージで定義されているサンプル java-builder Pod テンプレートを使用しています。

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"
        }
     }
    }
  }
}

提供される Jenkins の一時また永続テンプレートでデプロイする場合、デフォルトのメモリー制限は 1 Gi になります。

デフォルトで、Jenkins コンテナーで実行する他のすべてのプロセスは、合計の 512 MiB を超えるメモリーを使用することができません。メモリーがさらに必要になると、コンテナーは停止します。そのため、パイプラインが可能な場合に、エージェントコンテナーで外部コマンドを実行することが強く推奨されます。

また、Project クォータがこれを許可する場合は、Jenkins マスターがメモリーの観点から必要とするものについて、Jenkins ドキュメントの推奨事項を参照してください。この推奨事項では、Jenkins マスターにさらにメモリーを割り当てることを禁止しています。

Jenkins Kubernetes プラグインによって作成されるエージェントコンテナーで、メモリー要求および制限の値を指定することが推奨されます。管理者ユーザーは、Jenkins 設定を使用して、エージェントのイメージごとにデフォルト値を設定できます。メモリー要求および制限パラメーターは、コンテナーごとに上書きすることもできます。

Jenkins で利用可能なメモリー量を増やすには、Jenkins の一時テンプレートまたは永続テンプレートをインスタンス化する際に MEMORY_LIMIT パラメーターを上書きします。

Red Hat OpenShift Service on AWS の Jenkins エージェントイメージは、Quay.io または registry.redhat.io で入手できます。

Jenkins イメージは、Red Hat レジストリーから入手できます。

$ docker pull registry.redhat.io/ocp-tools-4/jenkins-rhel8:<image_tag>

$ docker pull registry.redhat.io/ocp-tools-4/jenkins-agent-base-rhel8:<image_tag>

Jenkins イメージを使用するには、Quay.io または registry.redhat.io から直接アクセスするか、イメージを Red Hat OpenShift Service on AWS のコンテナーイメージレジストリーにプッシュします。

各 Jenkins エージェントコンテナーは、以下の環境変数で設定できます。

JVM はすべての Jenkins エージェントで使用され、Jenkins JNLP エージェントをホストし、javac、Maven、Gradle などの Java アプリケーションを実行します。

デフォルトで、Jenkins JNLP エージェントの JVM はヒープにコンテナーメモリー制限の 50% を使用します。この値は、CONTAINER_HEAP_PERCENT の環境変数で変更可能です。上限を指定することも、すべて上書きすることも可能です。

デフォルトでは、シェルスクリプトや oc コマンドをパイプラインから実行するなど、Jenkins エージェントコンテナーで実行される他のプロセスはすべて、OOM kill を呼び出さずに残りの 50% メモリー制限を超えるメモリーを使用することはできません。

デフォルトでは、Jenkins エージェントコンテナーで実行される他の各 JVM プロセスは、最大でコンテナーメモリー制限の 25% をヒープに使用します。多くのビルドワークロードにおいて、この制限の調整が必要になる場合があります。

Red Hat OpenShift Service on AWS 上の Jenkins エージェントで Gradle ビルドをホストすると、Jenkins JNLP エージェントの JVM と Gradle の JVM に加えて、テストが指定されている場合に Gradle が 3 つ目の JVM を生成してテストを実行するため、さらに複雑になります。

以下の設定は、Red Hat OpenShift Service on AWS でメモリーに制約がある Jenkins エージェントの Gradle ビルドを実行する場合の開始点として推奨されます。必要に応じて、これらの設定を変更することができます。

Jenkins エージェント Pod は、ビルドが完了するか、停止された後にデフォルトで削除されます。この動作は、Kubernetes プラグイン Pod の保持設定で変更できます。Pod の保持は、すべての Jenkins ビルドについて各 Pod テンプレートの上書きで設定できます。以下の動作がサポートされます。

Pod の保持はパイプライン Jenkinsfile で上書きできます。

podTemplate(label: "mypod",
  cloud: "openshift",
  inheritFrom: "maven",
  podRetention: onFailure(), 1
  containers: [
    ...
  ]) {
  node("mypod") {
    ...
  }
}

Red Hat OpenShift Service on AWS 4.11 で、特定の OpenShift Jenkins イメージの場所と利用方法が大幅に変更されました。また、これらのイメージを更新するタイミングと方法を設定できるようになりました。

以前は、各 Jenkins イメージがサポートするバージョンは、Red Hat OpenShift Service on AWS の 1 つのバージョンだけでした。Red Hat は時間の経過とともに各イメージを順次更新する可能性がありました。

新規イメージストリームタグについて以下を実行します。

ただし、Cluster Samples Operator は、以前のリリースで作成された jenkins-agent-maven および jenkins-agent-nodejs イメージストリームを削除しません。これらのイメージストリームは、registry.redhat.io 上のそれぞれの Red Hat OpenShift Service on AWS のペイロードイメージのタグを参照します。したがって、次のコマンドを実行して、これらのイメージの更新をプルできます。

$ oc import-image jenkins-agent-nodejs -n openshift

$ oc import-image jenkins-agent-maven -n openshift

デフォルトのアップグレード動作をオーバーライドし、Jenkins イメージのアップグレード方法を制御するには、Jenkins デプロイメント設定で使用するイメージストリームタグの値を設定します。

デフォルトのアップグレード動作は、Jenkins イメージがインストールペイロードの一部であったときに存在した動作です。jenkins-rhel.json イメージストリームファイル内のイメージストリームタグ名 2 および ocp-upgrade-redeploy は、SHA 固有のイメージ参照を使用します。したがって、これらのタグが新しい SHA で更新されると、Red Hat OpenShift Service on AWS のイメージ変更コントローラーが、jenkins-ephemeral.json や jenkins-persistent.json などの関連テンプレートから Jenkins デプロイメント設定を自動的に再デプロイします。

新しいデプロイメントの場合、そのデフォルト値をオーバーライドするには、jenkins-ephemeral.json Jenkins テンプレートの JENKINS_IMAGE_STREAM_TAG の値を変更します。たとえば、"value": "jenkins:2" の 2 を次のイメージストリームタグのいずれかに置き換えます。