12.2. Jenkins イメージの設定

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

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

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

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

正式な OpenShift Container Platform 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 Container Platform Jenkins イメージには、事前にインストール済みの Kubernetes プラグイン が含まれ、Kubernetes および OpenShift Container Platform を使用して、Jenkins エージェントを複数のコンテナーホストで動的にプロビジョニングできるようにします。

OpenShift Container Platform は、Kubernetes プラグインを使用するために、Jenkins エージェントとして使用するのに適したイメージ (Base、Maven、および Node.js イメージ) を提供します。

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

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

OpenShift Container Platform 同期プラグインでは、Jenkins イメージは、Jenkins の起動時に、実行中のプロジェクトまたはプラグインの設定に具体的に一覧表示されているプロジェクト内で以下を検索します。

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

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

適切なラベルが指定された設定マップが検出される場合は、設定マップのキーと値のデータペイロードの値に、Jenkins および Kubernetes プラグインの Pod テンプレートの設定形式に準拠する XML (Extensible Markup Language) が含まれることが想定されます。イメージストリームやイメージストリームタグではなく、設定マップを使用する主な利点の 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: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>

インストールされた後、OpenShift Container Platform 同期プラグインは、イメージストリーム、イメージストリームタグ、および設定マップに更新がないか、OpenShift Container Platform の API サーバーをモニタリングして、Kubernetes プラグインの設定を調整します。

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

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

設定マップで、Pod テンプレート XML の <serviceAccount> 要素が結果として作成される Pod に使用される OpenShift Container Platform サービスアカウントである場合、サービスアカウントの認証情報が Pod にマウントされます。パーミッションはサービスアカウントに関連付けられ、OpenShift Container Platform マスターに対するどの操作が Pod から許可されるかについて制御します。

Pod に使用されるサービスアカウントについて以下のシナリオを考慮してください。この Pod は、OpenShift Container Platform Jenkins イメージで実行される Kubernetes プラグインによって起動されます。

OpenShift Container Platform で提供される Jenkins のテンプレートサンプルを使用する場合には、jenkins サービスアカウントが、Jenkins が実行するプロジェクトの edit ロールで定義され、マスター Jenkins Pod にサービスアカウントがマウントされます。

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

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

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

PV ストアを使用するには、クラスター管理者は OpenShift Container Platform デプロイメントで 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 宣言型フォーマットを導入しました。OpenShift Container PlatformJenkins イメージで定義されているサンプル 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: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 パラメーターを上書きします。