第4章 他のイメージ

4.1. 概要

以下のトピックには、OpenShift Container Platform ユーザーに提供される、さまざまなコンテナーイメージに関する情報が含まれます。

4.2. Jenkins

4.2.1. 概要

OpenShift Container Platform には、Jenkins 実行用のコンテナーイメージがあります。このイメージには、Jenkins サーバーインスタンスが含まれており、このインスタンスを使用して継続的なテスト、統合、デリバリーの基本フローを設定することができます。

このイメージにはサンプルの Jenkins ジョブが含まれており、OpenShift Container Platform で定義した BuildConfig の新しいビルドをトリガーし、そのビルドの出力をテストします。ビルドに成功すると、この出力に再度タグ付けして、ビルドが実稼働環境での使用準備ができたことを示します。詳細情報は、README を参照してください。

OpenShift Container Platform は、Jenkins の LTS リリースに従います。OpenShift Container Platform には、Jenkins 2.x を含むイメージを提供します。Jenkins 1.x の別のイメージが以前は提供されていましたが、このイメージに対するメンテナンスは終了しました。

4.2.2. イメージ

OpenShift Container Platform Jenkins イメージのフレーバーは 2 種類あります。

RHEL 7 ベースのイメージ

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

$ docker pull registry.redhat.io/openshift3/jenkins-2-rhel7

CentOS 7 ベースのイメージ

このイメージは、Docker Hub で入手できます。

$ docker pull openshift/jenkins-2-centos7

これらのイメージを使用するには、イメージレジストリーから直接アクセスするか、ご自身の OpenShift Container Platform コンテナーイメージレジストリーにプッシュしてください。さらに、コンテナーイメージレジストリーまたは外部の場所に、対象イメージを参照する ImageStream を作成することもでき、OpenShift Container Platform リソースがこの ImageStream を参照できるようになります。提供されている全 OpenShift Container Platform イメージに対して ImageStream の 定義例 があります。

4.2.3. 設定およびカスタマイズ

4.2.3.1. 認証

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

  • OpenShift ログインプラグインが提供する OpenShift Container Platform OAuth 認証
  • Jenkins が提供する標準認証
4.2.3.1.1. OpenShift Container Platform OAuth 認証

OAuth 認証 は、Jenkins UI の Configure Global Security パネルで設定するか、Jenkins デプロイメント設定OPENSHIFT_ENABLE_OAUTH 環境変数を false 以外に設定して、有効化します。これにより、OpenShift ログインプラグインが有効になり、Pod データからまたは、OpenShift Container Platform API サーバーと対話して設定情報を取得します。

有効な認証情報は、OpenShift Container Platform アイデンティティープロバイダーが制御します。たとえば、Allow All がデフォルトのアイデンティティープロバイダーの場合には、ユーザー名とパスワードの両方に、空でなければどのような文字列でも指定できます。

Jenkins は ブラウザー および ブラウザー以外 のアクセスをサポートします。

OpenShift Container Platform ロール で、ユーザーに割り当てられる固有の Jenkins パーミッションが指定されている場合には、有効なユーザーは、ログイン時に自動的に Jenkins 認証マトリックスに追加されます。

admin ロールが割り当てられたユーザーは、従来の Jenkins 管理ユーザー権限が割り当てられます。edit または view ロールを持つユーザーのパーミッションは徐々に少なくなります。Jenkins パーミッションと OpenShift ロールのマッピングに関する具体的な情報については、Jenkins image source repository README を参照してください。

注記

OpenShift Container Platform OAuth を使用する場合には、OpenShift Container Platform クラスター管理者が明示的に OpenShift Container Platform アイデンティティープロバイダーでそのユーザーを定義し、admin ロールを割り当てない限り、OpenShift Container Platform Jenkins イメージ内で管理者権限で事前に生成された admin ユーザーには、これらの権限は割り当てられません。

Jenkins のユーザーパーミッションは、最初にユーザー作成してから変更できます。OpenShift ログインプラグインは、OpenShift Container Platform API サーバーをポーリングしてパーミッションを取得し、ユーザーごとに Jenkins に保存されているパーミッションを、OpenShift Container Platform から取得したパーミッションに更新します。Jenkins UI を使用して Jenkins ユーザーのパーミッションを更新する場合には、プラグインが次回に OpenShift Container Platform をポーリングするタイミングで、パーミッションの変更が上書きされます。

ポーリングの頻度は OPENSHIFT_PERMISSIONS_POLL_INTERVAL 環境変数で制御できます。デフォルトのポーリングの間隔は 5 分です。

OAuth 認証を使用して最も簡単に Jenkins サービスを作成する方法は、以下の説明のようにテンプレートを使用する方法です。

4.2.3.1.2. Jenkins 標準認証

テンプレートを使用せず、イメージが直接実行される場合には、デフォルトで Jenkins 認証が使用されます。

Jenkins の初回起動時には、設定、管理ユーザーおよびパスワードが作成されます。デフォルトのユーザー認証は、admin および password です。標準の Jenkins 認証を使用する場合 (のみ)、デフォルトのパスワードは、JENKINS_PASSWORD 環境変数で設定します。

標準の Jenkins 認証を使用して、新しい Jenkins アプリケーションを作成するには以下を実行します。

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

4.2.3.2. 環境変数

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

  • OPENSHIFT_ENABLE_OAUTH (デフォルト: false)

    Jenkins へのログイン時に OpenShift ログインプラグインが認証を管理するかどうかを決定します。有効にするには、true に設定します。

  • JENKINS_PASSWORD (デフォルト: password)

    標準の Jenkins 認証を使用時の admin ユーザーのパスワード。OPENSHIFT_ENABLE_OAUTHtrue に設定されている場合には該当しません。

  • OPENSHIFT_JENKINS_JVM_ARCH

    x86_64 または i386 に設定して、Jenkins のホストに使用する JVM を上書きします。メモリー効率を確保するため、メモリー制限が 2 GiB 以下のコンテナーで実行される場合には、Jenkins イメージはデフォルトで 32 ビットの JVM を動的に使用します。

  • JAVA_MAX_HEAP_PARAM
    CONTAINER_HEAP_PERCENT (デフォルト: 0.5 または 50%)
    JENKINS_MAX_HEAP_UPPER_BOUND_MB

    これらの値は Jenkins JVM の最大ヒープサイズを制御します。JAVA_MAX_HEAP_PARAM が設定されている場合には (設定例: -Xmx512m)、この値が優先されます。設定されていない場合には、最大ヒープサイズは動的に、コンテナーメモリー制限の CONTAINER_HEAP_PERCENT% (設定例: 0.5 または 50%) として計算され、オプションで JENKINS_MAX_HEAP_UPPER_BOUND_MB MiB (設定例: 512) を上限とします。

    デフォルトでは Jenkins JVM の最大ヒープサイズは、上限なしでコンテナーメモリー制限の 50% に設定されます。

  • JAVA_INITIAL_HEAP_PARAM
    CONTAINER_INITIAL_PERCENT

    これらの値は Jenkins JVM の初期ヒープサイズを制御します。JAVA_INITIAL_HEAP_PARAM が設定されている場合には (設定例: -Xmx32m)、この値が優先されます。設定されていない場合には、初期ヒープサイズは動的に、コンテナーメモリー制限の CONTAINER_INITIAL_PERCENT% (設定例: 0.1 または 10%) として計算されます。

    デフォルトでは、初期のヒープサイズは JVM に依存します。

  • CONTAINER_CORE_LIMIT

    設定されている場合には、内部の JVM スレッドのサイジング数に使用するコアの数を整数で指定します。設定例: 2

  • JAVA_TOOL_OPTIONS (デフォルト: -XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true)

    対象のコンテナーで実行中のすべての JVM が従うオプションを指定します。この値の上書きは推奨していません。

  • JAVA_GC_OPTS (デフォルト: -XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90)

    Jenkins JVM ガーベッジコレクションのパラメーターを指定します。この値の上書きは推奨していません。

  • JENKINS_JAVA_OVERRIDES

    Jenkins JVM の追加オプションを指定します。これらのオプションは、上記の Java オプションなどその他すべてのオプションに追加され、必要に応じてそれらの値のいずれかを上書きするのに使用できます。追加オプションがある場合には、スペースで区切ります。オプションにスペース文字が含まれる場合には、バックスラッシュでエスケープしてください。設定例: -Dfoo -Dbar; -Dfoo=first\ value -Dbar=second\ value

  • JENKINS_OPTS

    Jenkins への引数を指定します。

  • INSTALL_PLUGINS

    コンテナーが初めて実行された場合や、OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINStrue に設定されている場合 (以下参照) に、追加の Jenkins プラグインを指定します。プラグインは、名前:バージョンのペアをコンマ区切りの一覧して指定します。設定例: git:3.7.0,subversion:2.10.2

  • OPENSHIFT_PERMISSIONS_POLL_INTERVAL (デフォルト: 300000 - 5 分)

    OpenShift ログインプラグインが Jenkins に定義されているユーザーごとに関連付けられたパーミッションを取得するために OpenShift Container Platform をポーリングする頻度をミリ秒単位で指定します。

  • OVERRIDE_PV_CONFIG_WITH_IMAGE_CONFIG (デフォルト: false)

    Jenkins 設定ディレクトリー用に OpenShift Container Platform 永続ボリュームを使用してこのイメージを実行する場合に、永続ボリューム要求の作成により永続ボリュームが割り当てられるので、イメージから永続ボリュームに設定が移行されるのは、イメージの初回起動時だけです。このイメージを拡張するカスタムイメージを作成して、初回起動後にそのカスタムイメージの設定を更新する場合には、デフォルトで、この環境変数を true に設定していない限りコピーされません。

  • OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS (デフォルト: false)

    Jenkins 設定ディレクトリー用に OpenShift Container Platform 永続ボリュームを使用してこのイメージを実行する場合に、永続ボリューム要求の作成により永続ボリュームが割り当てられるので、イメージから永続ボリュームにプラグインが移行されるのは、イメージの初回起動時だけです。このイメージを拡張するカスタムイメージを作成して、初回起動後にそのカスタムイメージの設定を更新する場合には、デフォルトで、この環境変数を true に設定していない限りコピーされません。

  • ENABLE_FATAL_ERROR_LOG_FILE (default: false)

    Jenkins 設定ディレクトリー用に OpenShift Container Platform の Persistent Claim (永続要求) を使用してこのイメージを実行する場合に、この環境変数は致命的なエラーが生じても、致命的なエラーのログファイルが永続することを許可します。致命的なエラーのファイルは /var/lib/jenkins/logs に保存されます。

  • NODEJS_SLAVE_IMAGE

    この値を設定すると、デフォルトの NodeJS エージェント Pod 設定に使用されるイメージが上書きされます。デフォルトの NodeJS エージェント Pod は、Jenkins イメージの CentOS または RHEL バージョンのいずれかを使用しているかによって docker.io/openshift/jenkins-agent-nodejs-8-centos7 または registry.redhat.io/openshift3/jenkins-agent-nodejs-8-rhel7 を使用します。この変数は、有効にするために Jenkins の初回の起動前に設定される必要があります。

  • MAVEN_SLAVE_IMAGE

    この値を設定すると、デフォルトの maven エージェント Pod 設定に使用されるイメージが上書きされます。デフォルトの maven エージェント Pod は、Jenkins イメージの CentOS または RHEL バージョンのいずれかを使用しているかによって docker.io/openshift/jenkins-agent-maven-35-centos7 または registry.redhat.io/openshift3/jenkins-agent-maven-35-rhel7 を使用します。この変数は、有効にするために Jenkins の初回の起動前に設定される必要があります。

4.2.3.3. プロジェクト間のアクセス

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

  1. Jenkins がアクセスするのに必要なプロジェクトへの適切なパーミッションが指定されているサービスアカウントのシークレットを特定します。

    $ oc describe serviceaccount jenkins
    Name:       default
    Labels:     <none>
    Secrets:    {  jenkins-token-uyswp    }
                {  jenkins-dockercfg-xcr3d    }
    Tokens:     jenkins-token-izv1u
                jenkins-token-uyswp

    今回の場合は、対象のシークレットは jenkins-token-uyswp という名前です。

  2. シークレットからトークンを取得します。

    $ oc describe secret <secret name from above> # for example, jenkins-token-uyswp
    Name:       jenkins-token-uyswp
    Labels:     <none>
    Annotations:    kubernetes.io/service-account.name=jenkins,kubernetes.io/service-account.uid=32f5b661-2a8f-11e5-9528-3c970e3bf0b7
    Type:   kubernetes.io/service-account-token
    Data
    ====
    ca.crt: 1066 bytes
    token:  eyJhbGc..<content cut>....wRA

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

4.2.3.4. ボリュームのマウントポイント

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

  • /var/lib/jenkins: これは、Jenkins がジョブの定義などの設定ファイルを保存するデータディレクトリーです。

4.2.3.5. Source-To-Image での Jenkins イメージのカスタマイズ

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

  • Docker のレイヤリングを使用する
  • ここに記載されているように Source-To-Image としてイメージを使用する

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

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

plugins
このディレクトリーには、Jenkins にコピーするバイナリーの Jenkins プラグインを含めます。
plugins.txt
このファイルには、インストールするプラグインを記載します。
pluginId:pluginVersion
configuration/jobs
このディレクトリーには、Jenkins ジョブ定義を含めます。
configuration/config.xml
このファイルには、カスタムの Jenkins 設定を含めます。

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

以下は、OpenShift Container Platform で 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
1
source フィールドでは、上記のレイアウトでソースの Git リポジトリーを定義します。
2
strategy フィールドでは、ビルドのソースイメージとして使用するための元の Jenkins イメージを定義します。
3
output フィールドは、公式の Jenkins イメージの代わりにデプロイメント設定で使用できる、カスタマイズして作成された Jenkins イメージを定義します。

4.2.3.6. Jenkins Kubernetes プラグインの設定

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

OpenShift Container Platform は、Kubernetes プラグインを使用するために、Jenkins エージェントとして使用するのに適したイメージを 5 つ (BaseMaven、および Node.js) 提供します。詳しい情報は、「Jenkins エージェント」を参照してください。

注記

jenkins-slave-maven-* および jenkins-slave-nodejs-* イメージには、v3.10 リリースサイクルで deprecated (非推奨) のマークが付けられます。イメージは、ユーザーがアプリケーションを新規の jenkins-agent-maven-* および jenkins-agent-nodejs-* イメージに移行できるようにしばらく残されます。

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 同期プラグイン では、Jenkins の起動時に Jenkins イメージが実行中のプロジェクトまたは、プラグインの設定に具体的に記載されているプロジェクト内で、以下がないか検索します。

  • ラベル rolejenkins-slave に設定されているイメージストリーム
  • アノテーション rolejenkins-slave に設定されているイメージストリーム
  • ラベル rolejenkins-slave に設定されている ConfigMap

適切なラベルまたは、適切なアノテーションが付いたイメージストリームタグが見つかると、適切な 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-agent
  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-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 同期プラグイン は、ImageStreamsImageStreamTags および ConfigMaps に更新がないか、OpenShift Container Platform の API サーバーをモニタリングして、Kubernetes プラグインの設定を調節します。

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

  • ConfigMapImageStream または ImageStreamTag からラベルまたはアノテーションを削除すると、既存の PodTemplate が Kubernetes プラグインの設定から削除されてしまいます。
  • 同様に、これらのオブジェクトが削除されると、該当の設定が Kubernetes プラグインから削除されます。
  • それとは逆に、適切なラベルおよびアノテーションが付いた ConfigMapImageStream または ImageStreamTag オブジェクトを作成するか、初回作成後にラベルを追加すると、Kubernetes プラグイン設定に PodTemplate が作成されてしまいます。
  • ConfigMap フォームを使用した PodTemplate の場合には、PodTemplateConfigMap データへの変更は、Kubernetes プラグイン設定の PodTemplate 設定に適用され、ConfigMap に変更を加えてから次に変更を加えるまでの間に、Jenkins UI で加えた PodTemplate の変更は上書きされます。

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

4.2.3.6.1. パーミッションの留意事項

以前の ConfigMap の例では、Pod テンプレート XML の <serviceAccount> 要素は、作成される Pod で使用する OpenShift Container Platform サービスアカウントとなっています。Pod にマウントされたサービスアカウントの認証情報と、そのサービスアカウントに関連付けられたパーミッションで、どの OpenShift Container Platform マスターが Pod からアクセスできるかを制御します。

OpenShift Container Platform Jenkins イメージで実行される Kubernetes プラグインで起動される Pod で使用されるサービスアカウントでは、以下を考慮してください。

  • OpenShift Container Platform で提供される Jenkins のテンプレートサンプルを使用する場合には、jenkins サービスアカウントが、Jenkins が実行されているプロジェクトの edit ロールで定義され、マスター Jenkins Pod にサービスアカウントがマウントされます。
  • Jenkins 設定に挿入される、2 つのデフォルトの Maven および NodeJS Pod テンプレートは、マスターと同じサービスアカウンを使用するように設定されます。
  • イメージストリームやイメージストリームタグに必須のラベルやアノテーションが指定されている結果として、OpenShift Sync プラグイン が自動検出した Pod テンプレートには、マスターのサービスアカウントがそのサービスアカウントとして設定されます。
  • Pod テンプレートの定義を Jenkins と Kubernetes プラグインに渡す他の方法ですが、使用するサービスアカウントを明示的に指定します。
  • 他の方法には、Jenkins コンソール、Kubernetes プラグインで提供される podTemplate パイプライン DSL または Pod テンプレートのXML 設定をデータとする ConfigMap のラベル付けなどが含まれます。
  • サービスアカウントの値を指定しない場合には、default のサービスアカウントが使用されます。
  • 使用するサービスアカウントが何であっても、必要なパーミッション、ロールなどを OpenShift Container Platform で定義して、Pod から操作することにしたプロジェクトをすべて操作できるようにする必要があります。

4.2.4. 使用法

4.2.4.1. テンプレートからの Jenkins サービスの作成

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

デプロイメント設定およびサービス

注記

Pod は、別のノードに移動時、またはデプロイメント設定の更新で再デプロイメントがトリガーされた時に再起動される可能性があります。

  • jenkins-persistent は永続ボリュームストアを使用します。データは Pod が再起動されても保持されます。

テンプレートをインスタンス化して、Jenkins を使用できるようにします。

4.2.4.2. Jenkins Kubernetes プラグインの使用

新規 Jenkins サービスの作成

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

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

例4.1 Jenkins Kubernetes プラグインを使用した BuildConfig の例

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 の仕様を上書きすることも可能です。以下は、コンテナーメモリーを上書きして、環境変数を指定するように、上記の例を変更しています。

例4.2 Jenkins Kubernetes プラグインを使用した BuildConfig の例 (メモリー制限および環境変数の指定)

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-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
1
「mypod」と呼ばれる新規 Pod テンプレートがその場で定義されます。この新しい Pod テンプレート名は、以下のノードスタンザで参照されます。
2
「cloud」の値は「openshift」に設定する必要があります。
3
新しい Pod テンプレートは、既存の Pod テンプレートから設定を継承できます。今回の例では、OpenShift Container Platform で事前定義された「maven」Pod テンプレートを継承します。
4
既存のコンテナーの値を上書きするので、名前で指定する必要があります。OpenShift Container Platform に含まれる Jenkins エージェントイメージはすべて、コンテナー名として「jnlp」を使用します。
5
コンテナーイメージは、再度指定する必要があります。これは既知の問題です。
6
512Mi のメモリー要求を指定します。
7
512Mi のメモリー制限を指定します。
8
環境変数 CONTAINER_HEAP_PERCENT に「0.25」の値を指定します。
9
ノードスタンザは、上記で新たに定義した Pod テンプレート名を参照します。

デフォルトで、Pod はビルドの完了時に削除されます。この動作は、プラグインを使用するか、またはパイプライン Jenkinsfile 内で変更できます。詳細は、「エージェント Pod の保持」を参照してください。

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

4.2.4.3. メモリーの要件

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

Jenkins が使用する JVM のチューニングに関する参考情報は、「OpenShift Container Platform での 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 パラメーターを上書きします。

4.2.5. Jenkins プラグイン

以下のプラグインは、Jenkins と OpenShift Container Platform の統合用に提供されています。これらのプラグインは、デフォルトで Jenkins イメージに含まれています。

4.2.5.1. OpenShift Container Platform Client プラグイン

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

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

  • Jenkins Pipeline で使用するための流れるような構文
  • oc で利用可能なオプションでの使用および公開
  • Jenkins の認証情報およびクラスターとの統合
  • 従来の Jenkins Freestyle ジョブに対する継続的なサポート

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

4.2.5.2. OpenShift Container Platform Pipeline プラグイン

OpenShift Container Platform Pipeline プラグインは、Jenkins と OpenShift Container Platform が統合する前のプラグインで、OpenShift Container Platform クライアントプラグインよりも機能が少なくなっています。これは非推奨になっていますが、引き続き v3.11 までの OpenShift Container Platform バージョンで機能します。これより後のバージョンでは、Jenkins Pipeline から直接 oc バイナリーを使用するか、または OpenShift Container Platform クライアントプラグインを使用します。

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

4.2.5.3. OpenShift Container Platform Sync プラグイン

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

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

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

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

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

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

  • Opaque タイプの Secret オブジェクトの場合には、プラグインは data セクション内で username および password を検索し、Jenkins UsernamePasswordCredentials 認証情報を構築します。OpenShift Container Platform では、password フィールドには、実際のパスワードまたはユーザーの一意のトークンを指定できることを忘れないでください。これらが指定されていない場合には、ssh-privatekey フィールドを検索し、Jenkins BasicSSHUserPrivateKey の認証情報を作成します。
  • kubernetes.io/basic-auth タイプの `Secret` オブジェクトの場合は、プラグインは Jenkins UsernamePasswordCredentials の認証情報を作成します。
  • kubernetes.io/ssh-auth タイプの Secret オブジェクトの場合には、プラグインは Jenkins BasicSSHUserPrivateKey 認証情報を作成します。

4.2.5.4. Kubernetes プラグイン

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

4.3. Jenkins エージェント

4.3.1. 概要

OpenShift Container Platform では、Jenkins エージェントとして使用するのに適したイメージを 3 つ (BaseMaven および Node.js) 提供します。

最初は、Jenkins エージェントの ベースイメージです。

  • 必須のツール (ヘッドレス Java、Jenkins JNLP クライアント) および役立つツール (git、tar、zip、nss など) の両方を取り入れます。
  • JNLP エージェントをエントリーポイントとして確立します。
  • Jenkins ジョブ内からコマンドラインの操作を呼び出す oc クライアントツールが含まれます。
  • CentOS および RHEL イメージ両方に対して Dockerfile を提供します。

ベースイメージを拡張するイメージがさらに 2 つ提供されます。

Maven および Node.js Jenkins エージェントイメージには、CentOS および RHEL 両方用の Dockerfiles が含まれており、新規エージェントイメージをビルドする場合に参照できます。また、contrib および contrib/bin サブディレクトリーにも注目してください。このサブディレクトリーでは、イメージについての設定ファイルや実行可能なスクリプトの挿入が可能です。

重要

使用する OpenShift Container Platform バージョンに適したエージェントイメージバージョンを使用、継承するようにしてください。エージェントイメージに埋め込まれた oc クライアントバージョンが OpenShift Container Platform バージョンと互換性がない場合には、予期せぬ動作が発生する可能性があります。詳細情報は、「「versioning policy」を参照してください。

4.3.2. イメージ

OpenShift Container Platform Jenkins エージェントイメージのフレーバーは 2 種類あります。

RHEL 7 ベースのイメージ

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

$ docker pull registry.redhat.io/openshift3/jenkins-slave-base-rhel7
$ docker pull registry.redhat.io/openshift3/jenkins-slave-maven-rhel7
$ docker pull registry.redhat.io/openshift3/jenkins-slave-nodejs-rhel7
$ docker pull registry.redhat.io/openshift3/jenkins-agent-maven-35-rhel7
$ docker pull registry.redhat.io/openshift3/jenkins-agent-nodejs-8-rhel7

CentOS 7 ベースのイメージ

これらのイメージは、Docker Hub で入手できます。

$ docker pull openshift/jenkins-slave-base-centos7
$ docker pull openshift/jenkins-slave-maven-centos7
$ docker pull openshift/jenkins-slave-nodejs-centos7
$ docker pull openshift/jenkins-agent-maven-35-centos7
$ docker pull openshift/jenkins-agent-nodejs-8-centos7

これらのイメージを使用するには、イメージレジストリーから直接アクセスするか、ご自身の OpenShift Container Platform コンテナーイメージレジストリーにプッシュしてください。

4.3.3. 設定およびカスタマイズ

4.3.3.1. 環境変数

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

  • OPENSHIFT_JENKINS_JVM_ARCH

    x86_64 または i386 に設定して、Jenkins エージェントのホストに使用する JVM を上書きします。メモリー効率を確保するため、メモリー制限が 2 GiB のコンテナーで実行される場合には、Jenkins エージェントイメージはデフォルトで 32 ビットの JVM を動的に使用します。

  • JAVA_MAX_HEAP_PARAM
    CONTAINER_HEAP_PERCENT (デフォルト: 0.5、50%)
    JNLP_MAX_HEAP_UPPER_BOUND_MB

    これらの値は Jenkins エージェントの JVM の最大ヒープサイズを制御します。JAVA_MAX_HEAP_PARAM が設定されている場合には (設定例: -Xmx512m)、この値が優先されます。設定されていない場合には、最大ヒープサイズは動的に、コンテナーメモリー制限の CONTAINER_HEAP_PERCENT% (設定例: 0.5、50%) として計算され、オプションで JNLP_MAX_HEAP_UPPER_BOUND_MB MiB (設定例: 512) を上限とします。

    デフォルトでは Jenkins エージェントの JVM の最大ヒープサイズは、上限なしで、コンテナーメモリー制限の 50% に設定されます。

  • JAVA_INITIAL_HEAP_PARAM
    CONTAINER_INITIAL_PERCENT

    これらの値は Jenkins エージェントの JVM の初期ヒープサイズを制御します。JAVA_INITIAL_HEAP_PARAM が設定されている場合には (設定例: -Xmx32m)、この値が優先されます。設定されていない場合には、初期ヒープサイズは動的に、コンテナーメモリー制限の CONTAINER_INITIAL_PERCENT% (設定例: 0.1、10%) として計算されます。

    デフォルトでは、初期のヒープサイズは JVM に依存します。

  • CONTAINER_CORE_LIMIT

    設定されている場合には、内部の JVM スレッドのサイジング数に使用するコアの数を整数で指定します。設定例: 2

  • JAVA_TOOL_OPTIONS (デフォルト: -XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true)

    対象のコンテナーで実行中のすべての JVM が従うオプションを指定します。この値の上書きは推奨していません。

  • JAVA_GC_OPTS (デフォルト: -XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90)

    Jenkins エージェントの JVM ガーベッジコレクションのパラメーターを指定します。この値の上書きは推奨していません。

  • JNLP_JAVA_OVERRIDES

    Jenkins エージェントの JVM の追加オプションを指定します。これらのオプションは、上記の Java オプションなどその他すべてのオプションに追加され、必要に応じてそれらの値のいずれかを上書きするのに使用できます。追加オプションがある場合には、スペースで区切ります。オプションにスペース文字が含まれる場合には、バックスラッシュでエスケープしてください。設定例: -Dfoo -Dbar; -Dfoo=first\ value -Dbar=second\ value

4.3.4. 使用法

4.3.4.1. メモリーの要件

Jenkins JNLP エージェントのホストや、Java アプリケーション (例: javac、Maven または Gradle) の実行に、Jenkins すべてにおいて JVM を使用します。Jenkins エージェントが使用する JVM のチューニングに関する参考情報は、「OpenShift Container Platform での OpenJDK のサイジング」を参照してください。

メモリー効率に関して、メモリー制限が 2 GiB 以下指定されたコンテナーで実行中の場合には、デフォルトで Jenkins イメージが動的に 32 ビットの JVMを使用します。この動作は、OPENSHIFT_JENKINS_JVM_ARCH 環境変数で上書きできます。JVM の選択は、デフォルトでエージェントコンテナー内の Jenkins JNLP エージェントおよび、他の Java プロセスの両方に適用されます。

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

デフォルトでは、パイプラインから実行されるシェルスクリプトや oc コマンドなど、Jenkins エージェントコンテナーで実行される他の全プロセスでは、OOM kill を呼び出さずに、メモリー制限の残り 50% を超えたメモリーを使用できる可能性が低い点を考慮してください。

デフォルトでは、Jenkins エージェントコンテナーで実行される他の JVM プロセスは、最大でコンテナーメモリー制限の 25% をヒープに使用します。これは、多くのビルドワークロード用にチューニングする必要がある場合があります。詳細情報は、「OpenShift Container Platform での OpenJDK のサイジング」を参照してください。

Jenkins エージェントコンテナーのメモリー要求や制限の指定に関する情報は、Jenkins ドキュメントを参照してください。

4.3.4.1.1. Gradle ビルド

OpenShift の Jenkins エージェントで Gradle ビルドをホストすると、Jenkins JNLP エージェントおよび Gradle JVM に加え、Gradle が 3 番目の JVM を起動してテストを実行するので、複雑性が増します。

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

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

  • gradle.properties ファイルに org.gradle.daemon=false を追加して、long-lived gradle デーモンを無効にするようにします。
  • gradle.properties ファイルで org.gradle.parallel=true が設定されていないこと、また、コマンドラインの引数として --parallel が指定されていないことを確認して、並行ビルドの実行を無効にします。
  • build.gradle ファイルでの java { options.fork = false } を設定して、プロセス以外で Java がコンパイルされないようにします。
  • build.gradle ファイルで test { maxParallelForks = 1 } が設定されていることを確認して、複数の追加テストプロセスを無効にします。
  • OpenShift Container Platform での OpenJDK のサイジングに従い、GRADLE_OPTS, JAVA_OPTS または JAVA_TOOL_OPTIONS の環境変数で、gradle JVM メモリーパラメーターを上書きします。
  • buile.gradle の maxHeapSize および jvmArgs の設定、または -Dorg.gradle.jvmargs コマンドラインの引数で、Gradle テスト JVM に最大ヒープサイズおよび JVM の引数を設定します。

4.3.5. エージェント Pod の保持

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

  • Always は、ビルドの結果に関係なくビルド Pod を維持します。
  • Default はプラグイン値を使用します (Pod テンプレートのみ)。
  • Never は常に Pod を削除します。
  • On Failure は Pod がビルド時に失敗した場合に Pod を維持します。

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

podTemplate(label: "mypod",
  cloud: "openshift",
  inheritFrom: "maven",
  podRetention: onFailure(), 1
  containers: [
    ...
  ]) {
  node("mypod") {
    ...
  }
}
1
podRetention に許可される値は、never()onFailure()always()、および default() です。
警告

保持される Pod は、引き続き実行され、リソースクォータに対してカウントされます。

4.4. 他のコンテナーイメージ

 

Red Hat Container Catalog に含まれていないコンテナーイメージを使用する場合には、Docker Hub にある他の任意のコンテナーイメージを OpenShift Container Platform インスタンスで使用できます。

任意の割り当てられたユーザー ID を使用してコンテナーを実行する場合の OpenShift Container Platform 固有のガイドラインについては、『イメージの作成』ガイドの「任意の ID のサポート」を参照してください。

重要

サポートの詳細については、「OpenShift Enterprise サポートポリシー」で定義されている製品サポートの対象範囲を参照してください。

システムおよび環境要件」のセキュリティー警告も参照してください。