4.2. Jenkins

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

$ oc new-app -e \
    JENKINS_PASSWORD=<password> \
    openshift/jenkins-2-centos7

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

同じプロジェクト内のデプロイメントとしてではなく、別の場所で Jenkins を実行する場合には、プロジェクトにアクセスするために、Jenkins にアクセストークンを提供する必要があります。

トークンフィールドには、Jenkins がプロジェクトへのアクセスに必要とするトークンの値が含まれます。

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

正式な OpenShift Online Jenkins イメージをカスタマイズするには、以下の 2 つのオプションがあります。

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

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

pluginId:pluginVersion

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

以下は、OpenShift Online で Jenkins イメージをカスタマイズするビルド設定例です。

apiVersion: 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:latest
        namespace: openshift
    type: Source
  output:                       3
    to:
      kind: ImageStreamTag
      name: custom-jenkins:latest

OpenShift Online Jenkins イメージには、事前にインストール済みの Kubernetes プラグインが含まれ、Kubernetes および OpenShift Online を使用して、Jenkins スレーブを複数のコンテナーホストで動的にプロビジョニングできるようにします。

OpenShift Online では、Jenkins スレーブとして使用するのに適したイメージを 3 つ (Base、Maven および Node.js) 提供します。 詳細は、「Jenkins エージェント」を参照してください。

Maven および Node.js のスレーブイメージは、Kubernetes プラグイン用の OpenShift Online Jenkins イメージの設定内で、Kubernetes Pod テンプレートイメージとして自動的に設定されます。この設定には、イメージごとのラベルが含まれており、"Restrict where this project can be run" に設定されている Jenkins ジョブのいずれかに適用できます。ラベルが適用されると、適切なスレーブイメージを実行する OpenShift Online Pod で指定のジョブが実行されます。

Jenkins イメージは、Kubernetes プラグインの追加のスレーブイメージの自動検出および自動設定を実行します。OpenShift 同期プラグイン では、Jenkins の起動時に Jenkins イメージが実行中のプロジェクトまたは、プラグインの設定に具体的に記載されているプロジェクト内で、以下がないか検索します。

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

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

適切なラベルが指定された ConfigMap が見つかった場合には、ConfigMap のキーおよび値のデータペイロードに Jenkins および Kubernetes プラグインの Pod テンプレートの設定形式に準拠する XML が含まれることを前提とします。ConfigMap を使用時に注意すべき主な違いは、イメージストリームまたはイメージストリームタグではなく、Kubernetes プラグインの Pod テンプレートの各種フィールドすべてを制御できます。

以下は ConfigMap の例です。

kind: ConfigMap
apiVersion: v1
metadata:
  name: jenkins-slave
  labels:
    role: jenkins-slave
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-slave-maven-centos7:v3.9</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 同期プラグイン は、ImageStreams、ImageStreamTags および ConfigMaps に更新がないか、OpenShift Online の API サーバーをモニタリングして、Kubernetes プラグインの設定を調整します。

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

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

テンプレート には各種パラメーターフィールドがあり、事前定義されたデフォルト値で全環境変数 (パスワード) を定義できます。OpenShift Online では、新規の Jenkins サービスを簡単に作成できるようにテンプレートが提供されています。クラスター管理者は、初期のクラスター設定時に、Jenkins テンプレートをデフォルトの openshift プロジェクトに登録しておく必要があります。

利用できる 2 つのテンプレートを定義するテンプレートが提供され、それらはどちらもデプロイメント設定 およびサービスを定義します。テンプレートはストレージストラテジーに応じて異なります。これは、Jenkins コンテンツが Pod の再起動時に永続するかどうかに影響を与えます。

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

$ oc new-app jenkins-persistent

$ oc new-app jenkins-persistent

$ oc new-app jenkins-ephemeral

以下の例では、openshift-jee-sample BuildConfig により、Jenkins maven スレーブ Pod が動的にプロビジョニングされます。この Pod は Java ソースのクローン作成、WAR ファイルのビルドを行い、次に 2 番目の BuildConfig (openshift-jee-sample-docker) を実行して、新規作成した WAR ファイルの階層を Docker イメージに対して作成します。

同様のタスクを実行する、より詳細にわたる例は こちらで確認できます。

kind: List
apiVersion: v1
items:
- kind: ImageStream
  apiVersion: v1
  metadata:
    name: openshift-jee-sample
- kind: BuildConfig
  apiVersion: 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: 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: 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-slave-maven-centos7:v3.9", 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

Kubernetes プラグインの設定に関する詳細は、Kubernetes プラグインのドキュメントを参照してください。

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

Jenkins が使用する JVM のチューニングに関する参考情報は、「OpenShift Online での OpenJDK のサイジング」を参照してください。

メモリー効率に関して、メモリー制限が 2 GiB 以下に指定されたコンテナーで実行中の場合には、デフォルトで Jenkins イメージが動的に 32 ビットの JVMを使用します。この動作は、OPENSHIFT_JENKINS_JVM_ARCH 環境変数で上書きできます。

デフォルトでは、Jenkins JVM はヒープにコンテナーメモリー制限の 50% を使用します。この値は、CONTAINER_HEAP_PERCENT の環境変数で変更可能です。また、上限を指定することも、すべて上書きすることも可能です。詳しい情報は、「環境変数」を参照してください。

デフォルトでは、パイプラインからローカルで実行されるシェルスクリプトや oc コマンドなど、Jenkins コンテナーで実行される他の全プロセスでは、OOM 終了を呼び出さずに、残りの 256MiB 以上のメモリーを組み合わせて使用できる可能性が低い点を考慮してください。そのため、パイプラインは、できる限りスレーブコンテナーで外部のコマンドを実行することを強く推奨します。

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

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

OpenShift Online クライアントプラグインは、OpenShift Online と強力な対話を行うために、信頼性があり、簡潔で包括的な、流れるような (fluent) Jenkins Pipeline 構文を提供することが目的です。このプラグインは oc バイナリーを活用しますが、このバイナリーは、スクリプトを実行するノードで利用できるようにしておく必要があります。

このプラグインは、Jenkins イメージで完全にサポートされており、イメージに含まれています。このプラグインでは以下が提供されます。

詳しい情報は、「OpenShift Pipeline ビルドのチュートリアル」およびプラグインの README を参照してください。

OpenShift Online Pipeline プラグインは、Jenkins と OpenShift Online が統合する前のプラグインで、OpenShift Online クライアントプラグインよりも機能が少なくなっています。このプラグインは引き続き利用でき、サポートされます。

詳しい情報は、プラグインの READMEを参照してください。

OpenShift Online Pipeline ビルドストラテジーが Jenkins と OpenShift Online をスムーズに統合できるように、OpenShift Sync プラグイン は OpenShift Online の API サーバーをモニタリングして、Pipeline ストラテジーを採用する BuildConfigs と Builds に更新がないか確認し、Jenkins Pipeline プロジェクトを作成するか (BuildConfig の作成時) または、作成されたプロジェクトでジョブを開始します (Build の起動時)。

「Jenkins Kubernetes プラグインの設定」に記載されているように、このプラグインは、OpenShift Online に定義済みで具体的に引用された ImageStream、ImageStreamTag、または ConfigMap オブジェクトをベースに、Kubernetes プラグインの PodTemplate 設定を作成できます。

このプラグインは、credential.sync.jenkins.openshift.io のラベルキーと、true のラベルの値が指定された Secret オブジェクトを受け入れて Jenkins 認証情報を構築し、Jenkins 認証情報階層内のデフォルトのグローバルドメインに配置できるようになりました。認証情報の ID は、Secret が定義されている namespace、ハイフン (-)、その後の Secret の名前で構成されます。

PodTemplates の ConfigMaps の処理と同様に、OpenShift Online で定義された Secret オブジェクトは、マスター設定とみなされます。OpenShift Online のオブジェクトのその後の更新は、Jenkins 認証情報に適用されます (その間に認証情報に加えられた変更を上書きします)。

credential.sync.jenkins.openshift.io プロパティーを削除したり、このプロパティーを true 以外に設定したり、OpenShift Online から Secret を削除したりすると、Jenkins の関連の認証情報が削除されます。

シークレットのタイプは、以下のように Jenkins 認証情報タイプにマッピングされます。

Kubernetes プラグインを使用して、クラスターの Pod として Jenkins スレーブを実行します。Kubernetes プラグインの自動設定については、「Jenkins Kubernetes プラグインの使用」で説明しています。