ビルド

ビルド とは、入力パラメーターを結果として作成されるオブジェクトに変換するプロセスです。ほとんどの場合、このプロセスは入力パラメーターまたはソースコードを実行可能なイメージに変換するために使用されます。BuildConfig オブジェクトはビルドプロセス全体の定義です。

OpenShift Container Platform は、ビルドイメージからコンテナーを作成し、それらをコンテナーイメージレジストリーにプッシュして Kubernetes を使用します。

ビルドオブジェクトは共通の特性を共有します。これらには、ビルドの入力、ビルドプロセスの完了についての要件、ビルドプロセスのロギング、正常なビルドからのリリースのパブリッシュ、およびビルドの最終ステータスのパブリッシュが含まれます。ビルドはリソースの制限を利用し、CPU 使用、メモリー使用およびビルドまたは Pod の実行時間などのリソースの制限を指定します。

OpenShift Container Platform ビルドシステムは、ビルド API で指定される選択可能なタイプに基づくビルドストラテジー を幅広くサポートします。利用可能なビルドストラテジーは主に 3 つあります。

デフォルトで、Docker ビルドおよび S2I ビルドがサポートされます。

ビルドの結果作成されるオブジェクトはこれを作成するために使用されるビルダーによって異なります。Docker および S2I ビルドの場合、作成されるオブジェクトは実行可能なイメージです。カスタムビルドの場合、作成されるオブジェクトはビルダーイメージの作成者が指定するものになります。

さらに、Pipeline ビルドストラテジーを使用して、高度なワークフローを実装することができます。

ビルド設定は、単一のビルド定義と新規ビルドを作成するタイミングについてのトリガーを記述します。ビルド設定は BuildConfig で定義されます。 BuildConfig は、新規インスタンスを作成するために API サーバーへの POST で使用可能な REST オブジェクトのことです。

ビルド設定 または BuildConfig は、ビルドストラテジー と 1 つまたは複数のソースを特徴としています。ストラテジーはプロセスを決定し、ソースは入力内容を提供します。

OpenShift Container Platform を使用したアプリケーションの作成方法の選択に応じて Web コンソールまたは CLI のいずれを使用している場合でも、BuildConfig は通常自動的に作成され、いつでも編集できます。BuildConfig を構成する部分や利用可能なオプションを理解しておくと、後に設定を手動で変更する場合に役立ちます。

以下の BuildConfig の例では、コンテナーイメージのタグやソースコードが変更されるたびに新規ビルドが作成されます。

kind: BuildConfig
apiVersion: build.openshift.io/v1
metadata:
  name: "ruby-sample-build" 1
spec:
  runPolicy: "Serial" 2
  triggers: 3
    -
      type: "GitHub"
      github:
        secret: "secret101"
    - type: "Generic"
      generic:
        secret: "secret101"
    -
      type: "ImageChange"
  source: 4
    git:
      uri: "https://github.com/openshift/ruby-hello-world"
  strategy: 5
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "ruby-20-centos7:latest"
  output: 6
    to:
      kind: "ImageStreamTag"
      name: "origin-ruby-sample:latest"
  postCommit: 7
      script: "bundle exec rake test"

ビルド入力 は、ビルドが動作するために必要なソースコンテンツを提供します。以下の ビルド入力 を使用して OpenShift Cotainer Platform でソースを提供します。以下に優先される順で記載します。

複数の異なる入力を単一のビルドにまとめることができます。インラインの Dockerfile が優先されるため、別の入力で指定される Dockerfile という名前の他のファイルは上書きされます。バイナリー (ローカル) 入力および Git リポジトリーは併用できません。

入力シークレットは、ビルド時に使用される特定のリソースや認証情報をビルドで生成される最終アプリケーションイメージで使用不可にする必要がある場合や、Secret リソースで定義される値を使用する必要がある場合に役立ちます。外部アーティファクトは、他のビルド入力タイプのいずれとしても利用できない別のファイルをプルする場合に使用できます。

ビルドを実行すると、以下が行われます。

以下のソース定義の例には、複数の入力タイプと、入力タイプの統合方法の説明が含まれています。それぞれの入力タイプの定義方法に関する詳細は、各入力タイプについての個別のセクションを参照してください。

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git 1
  images:
  - from:
      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths:
    - destinationDir: app/dir/injected/dir 2
      sourcePath: /usr/lib/somefile.jar
  contextDir: "app/dir" 3
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 4

dockerfile の値が指定されると、このフィールドの内容は、Dockerfile という名前のファイルとしてディスクに書き込まれます。これは、他の入力ソースが処理された後に実行されるので、入力ソースリポジトリーの root ディレクトリーに Dockerfile が含まれる場合は、これはこの内容で上書きされます。

ソースの定義は BuildConfig の spec セクションに含まれます。

source:
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 1

追加のファイルは、イメージを使用してビルドプロセスに渡すことができます。インプットイメージは From および To イメージターゲットが定義されるのと同じ方法で参照されます。つまり、コンテナーイメージと imagestreamtags の両方を参照できます。イメージとの関連で、1 つまたは複数のパスのペアを指定して、ファイルまたはディレクトリーのパスを示し、イメージと宛先をコピーしてビルドコンテキストに配置する必要があります。

ソースパスは、指定したイメージ内の絶対パスで指定してください。宛先は、相対ディレクトリーパスでなければなりません。ビルド時に、イメージは読み込まれ、指定のファイルおよびディレクトリーはビルドプロセスのコンテキストディレクトリーにコピーされます。これは、ソースリポジトリーのコンテンツ (ある場合) のクローンが作成されるディレクトリーと同じです。ソースパスの末尾は /. であり、ディレクトリーのコンテンツがコピーされますが、ディレクトリー自体は宛先で作成されません。

イメージの入力は、BuildConfig の source の定義で指定します。

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git
  images: 1
  - from: 2
      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths: 3
    - destinationDir: injected/dir 4
      sourcePath: /usr/lib/somefile.jar 5
  - from:
      kind: ImageStreamTag
      name: myotherinputimage:latest
      namespace: myothernamespace
    pullSecret: mysecret 6
    paths:
    - destinationDir: injected/dir
      sourcePath: /usr/lib/somefile.jar

ソースコードは、指定されている場合は指定先の場所からフェッチされます。

インラインの Dockerfile を指定する場合は、これにより Git リポジトリーの contextDir 内にある Dockerfile (ある場合) が上書きされます。

ソースの定義は BuildConfig の spec セクションに含まれます。

source:
  git: 1
    uri: "https://github.com/openshift/ruby-hello-world"
    ref: "master"
  contextDir: "app/dir" 2
  dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" 3

ref フィールドにプル要求が記載されている場合には、システムは git fetch 操作を使用して FETCH_HEAD をチェックアウトします。

ref の値が指定されていない場合は、OpenShift Container Platform はシャロークローン (--depth=1) を実行します。この場合、デフォルトのブランチ (通常は master) での最新のコミットに関連するファイルのみがダウンロードされます。これにより、リポジトリーのダウンロード時間が短縮されます (詳細のコミット履歴はありません)。指定リポジトリーのデフォルトのブランチで完全な git clone を実行するには、ref をデフォルトのブランチ名に設定します (例: master)。

source:
  git:
    uri: "https://github.com/openshift/ruby-hello-world"
    httpProxy: http://proxy.example.com
    httpsProxy: https://proxy.example.com
    noProxy: somedomain.com, otherdomain.com

$ oc secrets link builder mysecret

$ oc annotate secret mysecret \
    'build.openshift.io/source-secret-match-uri-1=ssh://bitbucket.atlassian.com:7999/*'

kind: Secret
apiVersion: v1
metadata:
  name: matches-all-corporate-servers-https-only
  annotations:
    build.openshift.io/source-secret-match-uri-1: https://*.mycorp.com/*
data:
  ...

kind: Secret
apiVersion: v1
metadata:
  name: override-for-my-dev-servers-https-only
  annotations:
    build.openshift.io/source-secret-match-uri-1: https://mydev1.mycorp.com/*
    build.openshift.io/source-secret-match-uri-2: https://mydev2.mycorp.com/*
data:
  ...

$ oc annotate secret mysecret \
    'build.openshift.io/source-secret-match-uri-1=https://*.mycorp.com/*'

apiVersion: "v1"
kind: "BuildConfig"
metadata:
  name: "sample-build"
spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "sample-image:latest"
  source:
    git:
      uri: "https://github.com/user/app.git"
    sourceSecret:
      name: "basicsecret"
  strategy:
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "python-33-centos7:latest"

$ oc set build-secret --source bc/sample-build basicsecret

$ oc create secret generic <secret_name> --from-file=<path/to/.gitconfig>

[http]
        sslVerify=false

$ oc create secret generic <secret_name> \
    --from-file=ssh-privatekey=<path/to/ssh/private/key> \
    --from-file=<path/to/.gitconfig> \
    --type=kubernetes.io/ssh-auth

$ oc create secret generic <secret_name> \
    --from-file=ca.crt=<path/to/certificate> \
    --from-file=<path/to/.gitconfig>

$ oc create secret generic <secret_name> \
    --from-literal=username=<user_name> \
    --from-literal=password=<password> \
    --from-file=ca-cert=</path/to/file> \
    --type=kubernetes.io/basic-auth

$ oc create secret generic <secret_name> \
    --from-literal=username=<user_name> \
    --from-literal=password=<password> \
    --from-file=</path/to/.gitconfig> \
    --type=kubernetes.io/basic-auth

$ oc create secret generic <secret_name> \
    --from-literal=username=<user_name> \
    --from-literal=password=<password> \
    --from-file=</path/to/.gitconfig> \
    --from-file=ca-cert=</path/to/file> \
    --type=kubernetes.io/basic-auth

ローカルのファイルシステムからビルダーにコンテンツをストリーミングすることは、Binary タイプのビルドと呼ばれています。このビルドについての BuildConfig.spec.source.type の対応する値は Binary です。

このソースタイプは、oc start-build のみをベースとして使用される点で独特なタイプです。

バイナリービルドを使用するには、以下のオプションのいずれかを指定して oc start-build を呼び出します。

上記のそれぞれの例では、以下のようになります。

ファイル名ではなく、HTTP または HTTPS スキーマを使用する URL を --from-file や --from-archive に渡すことができます。--from-file で URL を指定すると、ビルダーイメージのファイル名は Web サーバーが送信する Content-Disposition ヘッダーか、ヘッダーがない場合には URL パスの最後のコンポーネントによって決定されます。認証形式はどれもサポートされておらず、カスタムのTLS 証明書を使用したり、証明書の検証を無効にしたりできません。

oc new-build --binary=true を使用すると、バイナリービルドに関連する制約が実施されるようになります。作成される BuildConfig のソースタイプは Binary になります。 つまり、この BuildConfig のビルドを実行するための唯一の有効な方法は、--from オプションのいずれかを指定して oc start-build を使用し、必須のバイナリーデータを提供する方法になります。

dockerfile および contextDir のソースオプションは、バイナリービルドに関して特別な意味を持ちます。

dockerfile はバイナリービルドソースと合わせて使用できます。dockerfile を使用し、バイナリーストリームがアーカイブの場合には、そのコンテンツはアーカイブにある Dockerfile の代わりとして機能します。dockerfile が --from-file の引数と合わせて使用されている場合には、ファイルの引数は dockerfile となり、dockerfile の値はバイナリーストリームの値に置き換わります。

バイナリーストリームが展開されたアーカイブのコンテンツをカプセル化する場合には、contextDir フィールドの値はアーカイブ内のサブディレクトリーと見なされます。 有効な場合には、ビルド前にビルダーがサブディレクトリーに切り替わります。

シナリオによっては、ビルド操作で、依存するリソースにアクセスするための認証情報や他の設定データが必要になる場合がありますが、この情報をソースコントロールに配置するのは適切ではありません。この場合は、入力シークレット および input ConfigMap を定義することができます。

たとえば、Maven を使用して Java アプリケーションをビルドする場合、プライベートキーを使ってアクセスされる Maven Central または JCenter のプライベートミラーをセットアップできます。そのプライベートミラーからライブラリーをダウンロードするには、以下を指定する必要があります。

セキュリティー上の理由により、認証情報はアプリケーションイメージで公開しないでください。

以下の例は Java アプリケーションについて説明していますが、/etc/ssl/certs ディレクトリー、API キーまたはトークン、ラインセンスファイルなどに SSL 証明書を追加する場合に同じ方法を使用できます。

$ oc new-build \
    openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \
    --context-dir helloworld --build-secret “secret-mvn” \
    --build-config-map "settings-mvn"

source:
  git:
    uri: https://github.com/wildfly/quickstart.git
  contextDir: helloworld
  configMaps:
    - configMap:
        name: settings-mvn
      destinationDir: ".m2"
  secrets:
    - secret:
        name: secret-mvn
      destinationDir: ".ssh"

$ oc new-build \
    openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \
    --context-dir helloworld --build-secret “secret-mvn:.ssh” \
    --build-config-map "settings-mvn:.m2"

FROM centos/ruby-22-centos7

USER root
COPY ./secret-dir /secrets
COPY ./config /

# Create a shell script that will output secrets and ConfigMaps when the image is run
RUN echo '#!/bin/sh' > /input_report.sh
RUN echo '(test -f /secrets/secret1 && echo -n "secret1=" && cat /secrets/secret1)' >> /input_report.sh
RUN echo '(test -f /config && echo -n "relative-configMap=" && cat /config)' >> /input_report.sh
RUN chmod 755 /input_report.sh

CMD ["/bin/sh", "-c", "/input_report.sh"]

ソースリポジトリーにバイナリーファイルを保存することは推奨していません。そのため、ビルドプロセス中に追加のファイル (Java .jar の依存関係など) をプルするビルドを定義する必要がある場合があります。この方法は、使用するビルドストラテジーにより異なります。

Source ビルドストラテジーの場合は、assemble スクリプトに適切なシェルコマンドを設定する必要があります。

#!/bin/sh
APP_VERSION=1.0
wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar

#!/bin/sh
exec java -jar app.jar

Docker ビルドストラテジーの場合は、Dockerfile を変更して、RUN 命令を指定してシェルコマンドを呼び出す必要があります。

FROM jboss/base-jdk:8

ENV APP_VERSION 1.0
RUN wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar

EXPOSE 8080
CMD [ "java", "-jar", "app.jar" ]

I実際には、ファイルの場所の環境変数を使用し、Dockerfile または assemble スクリプトを更新するのではなく、BuildConfig で定義した環境変数で、ダウンロードする特定のファイルをカスタマイズすることができます。

環境変数の定義には複数の方法があり、いずれかの方法を選択できます。

プライベートコンテナーレジストリーの有効な認証情報を指定して、.docker/config.json ファイルでビルドを提供できます。これにより、プライベートコンテナーレジストリーにアウトプットイメージをプッシュしたり、認証を必要とするプライベートコンテナーイメージレジストリーからビルダーイメージをプルすることができます。

デフォルトでは、.docker/config.json ファイルはホームディレクトリーにあり、以下の形式となっています。

auths:
  https://index.docker.io/v1/: 1
    auth: "YWRfbGzhcGU6R2labnRib21ifTE=" 2
    email: "user@example.com" 3

このファイルに複数のコンテナーイメージレジストリーを定義できます。または docker login コマンドを実行して、このファイルに認証エントリーを追加することも可能です。ファイルが存在しない場合には作成されます。

Kubernetes では Secret オブジェクトが提供され、これを使用して設定とパスワードを保存することができます。

Pod 環境変数と同様に、ビルドの環境変数は Downward API を使用して他のリソースや変数の参照として定義できます。ただし、いくつかは例外があります。

oc set env コマンドで、BuildConfig に定義した環境変数を管理することも可能です。

Secret オブジェクトタイプはパスワード、OpenShift Container Platform クライアント設定ファイル、dockercfg ファイル、プライベートソースリポジトリーの認証情報などの機密情報を保持するメカニズムを提供します。シークレットは機密内容を Pod から切り離します。シークレットはボリュームプラグインを使用してコンテナーにマウントすることも、システムが Pod の代わりにシークレットを使用して各種アクションを実行することもできます。

apiVersion: v1
kind: Secret
metadata:
  name: test-secret
  namespace: my-namespace
type: Opaque 1
data: 2
  username: dmFsdWUtMQ0K 3
  password: dmFsdWUtMg0KDQo=
stringData: 4
  hostname: myapp.mydomain.com 5

サービスが提供する証明書のシークレットは、追加設定なしの証明書を必要とする複雑なミドルウェアアプリケーションをサポートするように設計されています。これにはノードおよびマスターの管理者ツールで生成されるサーバー証明書と同じ設定が含まれます。

他の Pod は Pod に自動的にマウントされる /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt ファイルの CA バンドルを使用して、クラスターで作成される証明書 (内部 DNS 名の場合にのみ署名される) を信頼できます。

この機能の署名アルゴリズムは x509.SHA256WithRSA です。ローテーションを手動で実行するには、生成されたシークレットを削除します。新規の証明書が作成されます。

シークレットを使用するには、Pod がシークレットを参照できる必要があります。シークレットは、以下の 3 つの方法で Pod で使用されます。

ボリュームタイプのシークレットは、ボリュームメカニズムを使用してデータをファイルとしてコンテナーに書き込みます。 imagePullSecrets は、シークレットを namespace のすべての Pod に自動的に挿入するためにサービスアカウントを使用します。

テンプレートにシークレット定義が含まれる場合、テンプレートで指定のシークレットを使用できるようにするには、シークレットのボリュームソースを検証し、指定されるオブジェクト参照が Secret タイプのオブジェクトを実際に参照していることを確認できる必要があります。そのため、シークレットはこれに依存する Pod の作成前に作成されている必要があります。最も効果的な方法として、サービスアカウントを使用してシークレットを自動的に挿入することができます。

シークレット API オブジェクトは namespace にあります。それらは同じ namespace の Pod によってのみ参照されます。

個々のシークレットは 1MB のサイズに制限されます。これにより、apiserver および kubelet メモリーを使い切るような大規模なシークレットの作成を防ぐことができます。ただし、小規模なシークレットであってもそれらを数多く作成するとメモリーの消費につながります。

Docker または Source-to-Image (S2I) ストラテジーを使用するビルドにより、新しいコンテナーイメージが作成されます。このイメージは、Build 仕様の output セクションで指定されているコンテナーイメージのレジストリーにプッシュされます。

出力の種類が ImageStreamTag の場合は、イメージが統合された OpenShift Container Platform レジストリーにプッシュされ、指定のイメージストリームにタグ付けされます。出力が DockerImage タイプの場合は、出力参照の名前が Docker のプッシュ仕様として使用されます。この仕様にレジストリーが含まれる場合もありますが、レジストリーが指定されていない場合は、DockerHub にデフォルト設定されます。ビルド仕様の出力セクションが空の場合には、ビルドの最後にイメージはプッシュされません。

spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "sample-image:latest"

spec:
  output:
    to:
      kind: "DockerImage"
      name: "my-registry.mycompany.com:5000/myimages/myimage:tag"

Docker および Source-to-Image (S2I) ストラテジービルドは、以下の環境変数をアウトプットイメージに設定します。

また、S2I] または Docker ストラテジーオプションなどで設定されたユーザー定義の環境変数も、アウトプットイメージの環境変数一覧の一部になります。

Docker および Source-to-Image (S2I) ビルドは、以下のラベルをアウトプットイメージに設定します。

BuildConfig.spec.output.imageLabels フィールドを使用して、カスタムラベルの一覧を指定することも可能です。 このラベルは、BuildConfig の各イメージビルドに適用されます。

spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "my-image:latest"
    imageLabels:
    - name: "vendor"
      value: "MyCompany"
    - name: "authoritative-source-url"
      value: "registry.mycompany.com"

Docker ビルドストラテジーは docker build コマンドを起動するため、Dockerfile とそれに含まれるすべての必要なアーティファクトのあるリポジトリーが実行可能なイメージを生成することを予想します。

strategy:
  dockerStrategy:
    from:
      kind: "ImageStreamTag"
      name: "debian:latest"

strategy:
  dockerStrategy:
    dockerfilePath: dockerfiles/app1/Dockerfile

dockerStrategy:
...
  env:
    - name: "HTTP_PROXY"
      value: "http://myproxy.net:5187/"

dockerStrategy:
...
  buildArgs:
    - name: "foo"
      value: "bar"

Source-to-Image (S2I) は再現可能な Docker 形式のコンテナーイメージをビルドするためのツールです。これはアプリケーションソースをコンテナーイメージに挿入し、新規イメージをアセンブルして実行可能なイメージを生成します。新規イメージはベースイメージ (ビルダー) とビルドされたソースを組み込み、buildah run コマンドで使用することができます。S2I は増分ビルドをサポートします。 これは以前にダウンロードされた依存関係や、以前にビルドされたアーティファクトなどを再利用します。

S2I の利点には以下が含まれます。

strategy:
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "incremental-image:latest" 1
    incremental: true 2

strategy:
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest"
    scripts: "http://somehost.com/scripts_directory" 1

sourceStrategy:
...
  env:
    - name: "DISABLE_ASSET_COMPILATION"
      value: "true"

5.2.5. S2I によるソースコードからのイメージの作成

Source-to-Image (S2I) は、アプリケーションのソースコードを入力として取り、アセンブルされたアプリケーションを出力として実行する新規イメージを生成するイメージを簡単に作成できるようにするフレームワークです。

再生成可能なコンテナーイメージのビルドに S2I を使用する主な利点として、開発者の使い勝手の良さが挙げられます。ビルダーイメージの作成者は、イメージが最適な S2I パフォーマンスを実現できるように、ビルドプロセスと S2I スクリプトの基本的なコンセプト 2 点を理解する必要があります。

5.2.5.1. S2I ビルドプロセスについて

ビルドプロセスは、以下の 3 つの要素で構成されており、これら 3 つを組み合わせて最終的なコンテナーイメージが作成されます。

• ソース
• S2I スクリプト
• ビルダーイメージ

ビルドプロセス中に、S2I はソースとスクリプトをビルダーイメージ内に配置する必要があります。ビルダーイメージ内にソースとスクリプトを配置するために、S2I はソースとスクリプトを含む tar ファイルを作成してから、このファイルをビルダーイメージにストリーミングします。assemble スクリプトを実行する前に、S2I はファイルを展開して、ビルダーイメージからコンテンツを、デフォルトの /tmp ディレクトリーではなく、io.openshift.s2i.destination ラベルが指定する場所に配置します。

このプロセスでは、イメージに tar アーカイブユーティリティー (tar コマンドは $PATH にあります) とコマンドラインインタープリター (/bin/sh コマンド) が必要です。これにより、イメージが最速のビルドパスを使用できるようになります。 tar または /bin/sh コマンドが利用できない場合には s2i ビルド プロセスにより、イメージ内にソースとスクリプトが配置されるように、追加のコンテナーが自動で強制実行されて初めて、通常のビルドが実行されます。

基本的な S2I ビルドワークフローについては、以下の図を参照してください。

図5.1 ビルドのワークフロー

ビルドの実行では、ソース、スクリプト、アーティファクト (ある場合) を展開して、assemble スクリプトを実行します。2 回目の実行の場合には (tar または /bin/sh を検出できないエラーが発生した後など)、スクリプトとソースの両方があるので、assemble スクリプトの呼び出しのみを行います。

5.2.5.2. S2I スクリプトの作成

S2I スクリプトは、ビルダーイメージ内でスクリプトを実行できる限り、どのプログラム言語でも記述できます。S2I は assemble/run/save-artifacts スクリプトを提供する複数のオプションをサポートします。ビルドごとに、これらの場所はすべて、以下の順番にチェックされます。

1. BuildConfig に指定されるスクリプト
2. アプリケーションソースの .s2i/bin ディレクトリーにあるスクリプト
3. デフォルトの URL (io.openshift.s2i.scripts-url ラベル) にあるスクリプト

イメージで指定した io.openshift.s2i.scripts-url ラベルも、BuildConfig で指定したスクリプトも、以下の形式のいずれかを使用します。

• image:///path_to_scripts_dir: S2I スクリプトが配置されているディレクトリーへのイメージ内の絶対パス
• file:///path_to_scripts_dir: S2I スクリプトが配置されているディレクトリーへのホスト上の相対パスまたは絶対パス
• http(s)://path_to_scripts_dir: S2I スクリプトが配置されているディレクトリーの URL

表5.1 S2I スクリプト

スクリプト	説明
assemble (必須)	assemble スクリプトは、ソースからアプリケーションアーティファクトをビルドし、イメージ内の適切なディレクトリーに配置します。このスクリプトのワークフローは以下のとおりです。 ビルドのアーティファクトを復元します。save-artifacts も定義するようにしてください (オプション)。 任意の場所に、アプリケーションソースを配置します。 アプリケーションのアーティファクトをビルドします。 実行に適した場所に、アーティファクトをインストールします。
run (必須)	run スクリプトはアプリケーションを実行します。
save-artifacts (オプション)	save-artifacts スクリプトは、次に続くビルドプロセスを加速できるようにすべての依存関係を収集します。以下は例になります。 Ruby の場合は、Bundler でインストールされる gems Java の場合は、.m2 のコンテンツ これらの依存関係は tar ファイルに集められ、標準出力としてストリーミングされます。
usage (オプション)	usage スクリプトでは、ユーザーに、イメージの正しい使用方法を通知します。
test/run (オプション)	test/run スクリプトでは、イメージが正しく機能しているかどうかを確認するための単純なプロセスを作成できます。このプロセスの推奨フローは以下のとおりです。 イメージをビルドします。 イメージを実行して usage スクリプトを検証します。 s2i build を実行して assemble スクリプトを検証します。 再度 s2i build を実行して、save-artifacts と assemble スクリプトの保存、復元アーティファクト機能を検証します (オプション)。 イメージを実行して、テストアプリケーションが機能していることを確認します。 注記 test/run スクリプトでビルドしたテストアプリケーションを配置する推奨の場所は、イメージリポジトリーの test/test-app ディレクトリーです。詳しい情報は、S2I ドキュメント を参照してください。

5.2.5.2.1. S2I スクリプトの例

以下の S2I スクリプトの例は Bash で記述されています。それぞれの例では、tar の内容は/tmp/s2i ディレクトリーに展開されることが前提とされています。

例5.1 assemble スクリプト:

#!/bin/bash

# restore build artifacts
if [ "$(ls /tmp/s2i/artifacts/ 2>/dev/null)" ]; then
    mv /tmp/s2i/artifacts/* $HOME/.
fi

# move the application source
mv /tmp/s2i/src $HOME/src

# build application artifacts
pushd ${HOME}
make all

# install the artifacts
make install
popd

例5.2 run スクリプト:

#!/bin/bash

# run the application
/opt/application/run.sh

例5.3 save-artifacts スクリプト:

#!/bin/bash

pushd ${HOME}
if [ -d deps ]; then
    # all deps contents to tar stream
    tar cf - deps
fi
popd

例5.4 usage スクリプト:

#!/bin/bash

# inform the user how to use the image
cat <<EOF
This is a S2I sample builder image, to use it, install
https://github.com/openshift/source-to-image
EOF

カスタムビルドストラテジーにより、開発者はビルドプロセス全体を対象とする特定のビルダーイメージを定義できます。独自のビルダーイメージを使用することにより、ビルドプロセスをカスタマイズできます。

カスタムビルダーイメージは、RPM またはベースイメージのビルド用などの、ビルドプロセスロジックで組み込まれた単純な Docker 形式のコンテナーイメージです。

カスタムビルドは非常に高いレベルの権限で実行されるため、デフォルトではユーザーが利用することはできません。クラスター管理者のパーミッションを持つ信頼できるユーザーのみにカスタムビルドを実行するためのアクセスが付与される必要があります。

strategy:
  customStrategy:
    from:
      kind: "DockerImage"
      name: "openshift/sti-image-builder"

strategy:
  customStrategy:
    secrets:
      - secretSource: 1
          name: "secret1"
        mountPath: "/tmp/secret1" 2
      - secretSource:
          name: "secret2"
        mountPath: "/tmp/secret2"

customStrategy:
...
  env:
    - name: "HTTP_PROXY"
      value: "http://myproxy.net:5187/"

開発者は、Pipeline ビルドストラテジーを利用して Jenkins Pipeline プラグインで実行できるように、Jenkins Pipeline を定義することができます。このビルドは他のビルドタイプの場合と同様に OpenShift Container Platform での起動、モニタリング、管理が可能です。

Pipeline ワークフローは、ビルド設定に直接組み込むか、または Git リポジトリーに配置してビルド設定で参照して Jenkinsfile で定義します。

kind: "BuildConfig"
apiVersion: "v1"
metadata:
  name: "sample-pipeline"
spec:
  strategy:
    jenkinsPipelineStrategy:
      jenkinsfile: |-
        node('agent') {
          stage 'build'
          openshiftBuild(buildConfig: 'ruby-sample-build', showBuildLogs: 'true')
          stage 'deploy'
          openshiftDeploy(deploymentConfig: 'frontend')
        }

kind: "BuildConfig"
apiVersion: "v1"
metadata:
  name: "sample-pipeline"
spec:
  source:
    git:
      uri: "https://github.com/openshift/ruby-hello-world"
  strategy:
    jenkinsPipelineStrategy:
      jenkinsfilePath: some/repo/dir/filename 1

jenkinsPipelineStrategy:
...
  env:
    - name: "FOO"
      value: "BAR"

プライベートリポジトリーにアクセスできるように、ビルド設定にシークレットを追加することができます。

プライベートレジストリーへのプルを実行できるようにするには、ビルド設定に Pull Secret を設定し、プッシュを有効にするには Push Secret を設定します。

プッシュを有効にするには、以下を実行します。

カスタムビルドイメージとして使用する必要のあるイメージを作成する必要があります。

OpenShift Container Platform を使用してカスタムストラテジーで使用するカスタムビルダーイメージをビルドし、プッシュすることができます。

カスタムビルダーイメージとカスタムストラテジーを併用する BuildConfig を定義し、カスタムビルドロジックを実行することができます。

現在のプロジェクトに既存のビルド設定から新規ビルドを手動で起動できます。

$ oc start-build <buildconfig_name>

$ oc start-build --from-build=<build_name>

$ oc start-build <buildconfig_name> --follow

$ oc start-build <buildconfig_name> --env=<key>=<value>

$ oc start-build hello-world --from-repo=../hello-world --commit=v2

Web コンソールまたは以下の CLI コマンドを使用して、ビルドを中止できます。

$ oc cancel-build <build_name>

$ oc cancel-build <build1_name> <build2_name> <build3_name>

$ oc cancel-build bc/<buildconfig_name>

$ oc cancel-build bc/<buildconfig_name>

以下のコマンドで BuildConfig を削除します。

$ oc delete bc <BuildConfigName>

これにより、この BuildConfig でインスタンス化されたビルドがすべて削除されます。ビルドを削除しない場合には、--cascade=false フラグを指定します。

$ oc delete --cascade=false bc <BuildConfigName>

Web コンソールまたは oc describe CLI コマンドを使用して、ビルドの詳細を表示できます。

これにより、以下のような情報が表示されます。

ビルドが Docker または Source ストラテジーを使用する場合、oc describe 出力には、コミット ID、作成者、コミットしたユーザー、メッセージなどのビルドに使用するソースのリビジョンの情報が含まれます。

$ oc describe build <build_name>

Web コンソールまたは CLI を使用してビルドログにアクセスできます。

$ oc describe build <build_name>

$ oc logs -f bc/<buildconfig_name>

$ oc logs --version=<number> bc/<buildconfig_name>

sourceStrategy:
...
  env:
    - name: "BUILD_LOGLEVEL"
      value: "2" 1

BuildConfig の定義時に、BuildConfig を実行する必要のある状況を制御するトリガーを定義できます。以下のビルドトリガーを利用できます。

type: "GitHub"
github:
  secretReference:
    name: "mysecret"

- kind: Secret
  apiVersion: v1
  metadata:
    name: mysecret
    creationTimestamp:
  data:
    WebHookSecretKey: c2VjcmV0dmFsdWUx

type: "GitHub"
github:
  secretReference:
    name: "mysecret"

http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

type: "GitLab"
gitlab:
  secretReference:
    name: "mysecret"

http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab

type: "Bitbucket"
bitbucket:
  secretReference:
    name: "mysecret"

http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket

type: "Generic"
generic:
  secretReference:
    name: "mysecret"
  allowEnv: true 1

$ oc describe bc <name>

strategy:
  sourceStrategy:
    from:
      kind: "DockerImage"
      name: "172.30.17.3:5001/mynamespace/ruby-20-centos7:<immutableid>"

type: "ImageChange"
imageChange:
  from:
    kind: "ImageStreamTag"
    name: "custom-image:latest"
  paused: true

  type: "ConfigChange"

ビルドフックを使用すると、ビルドプロセスに動作を挿入できます。

BuildConfig オブジェクトの postCommit フィールドにより、ビルドアウトプットイメージを実行する一時的なコンテナー内でコマンドが実行されます。イメージの最後の層がコミットされた直後、かつイメージがレジストリーにプッシュされる前に、フックが実行されます。

現在の作業ディレクトリーは、イメージの WORKDIR に設定され、コンテナーイメージのデフォルトの作業ディレクトリーになります。多くのイメージでは、ここにソースコードが配置されます。

ゼロ以外の終了コードが返された場合、一時コンテナーの起動に失敗した場合には、フックが失敗します。フックが失敗すると、ビルドに失敗とマークされ、このイメージはレジストリーにプッシュされません。失敗の理由は、ビルドログを参照して検証できます。

ビルドフックは、ビルドが完了とマークされ、イメージがレジストリーに公開される前に、単体テストを実行してイメージを検証するために使用できます。すべてのテストに合格し、テストランナーにより終了コード 0 が返されると、ビルドは成功とマークされます。テストに失敗すると、ビルドは失敗とマークされます。すべての場合で、ビルドログには、テストランナーの出力が含まれるので、失敗したテストを特定するのに使用できます。

postCommit フックは、テストの実行だけでなく、他のコマンドにも使用できます。一時的なコンテナーで実行されるので、フックによる変更は永続されず、フックの実行は最終的なイメージには影響がありません。この動作はさまざまな用途がありますが、これにより、テストの依存関係がインストール、使用されて、自動的に破棄され、最終イメージには残らないようにすることができます。

デフォルトでは、ビルドは、メモリーや CPU など、バインドされていないリソースを使用して Pod により完了されます。これらのリソースは制限できます。

BuildConfig の定義時に、completionDeadlineSeconds フィールドを設定して最長期間を定義できます。このフィールドは秒単位で指定し、デフォルトでは設定されません。設定されていない場合は、最長期間は有効ではありません。

最長期間はビルドの Pod がシステムにスケジュールされた時点から計算され、ビルダーイメージをプルするのに必要な時間など、ジョブが有効である期間を定義します。指定したタイムアウトに達すると、ジョブは OpenShift Container Platform により終了されます。

spec:
  completionDeadlineSeconds: 1800

ビルドは、ビルド設定の nodeSelector フィールドにラベルを指定して、特定のノード上で実行するようにターゲットを設定できます。nodeSelector の値は、ビルド Pod のスケジュール時の node ラベルに一致するキー/値のペアに指定してください。

nodeSelector の値は、クラスター全体のデフォルトでも制御でき、値を上書きできます。ビルド設定で nodeSelector キー/値ペアが定義されておらず、nodeSelector:{} が明示的に空になるように定義されていない場合にのみ、デフォルト値が適用されます。値を上書きすると、キーごとにビルド設定の値が置き換えられます。

コンパイル言語 (Go、C、C++、Java など) の場合には、アプリケーションイメージにコンパイルに必要な依存関係を追加すると、イメージのサイズが増加したり、悪用される可能性のある脆弱性が発生したりする可能性があります。

これらの問題を回避するには、2 つのビルドをチェーンでつなげることができます。

以下の例では、Source-to-Image ビルドが Docker ビルドに組み合わされ、別のランタイムイメージに配置されるアーティファクトがコンパイルされます。

最初のビルドは、アプリケーションソースを取得して、WAR ファイルを含むイメージを作成します。このイメージは、artifact-image イメージストリームにプッシュされます。アウトプットアーティファクトのパスは、使用する Source-to-Image ビルダーの assemble スクリプトにより異なります。この場合、/wildfly/standalone/deployments/ROOT.war に出力されます。

apiVersion: v1
kind: BuildConfig
metadata:
  name: artifact-build
spec:
  output:
    to:
      kind: ImageStreamTag
      name: artifact-image:latest
  source:
    git:
      uri: https://github.com/openshift/openshift-jee-sample.git
  strategy:
    sourceStrategy:
      from:
        kind: ImageStreamTag
        name: wildfly:10.1
        namespace: openshift

2 つ目のビルドは、1 つ目のビルドからのアウトプットイメージ内にある WAR ファイルへのパスが指定されているイメージソースを使用します。インライン Dockerfile は、その WAR ファイルをランタイムイメージにコピーします。

apiVersion: v1
kind: BuildConfig
metadata:
  name: image-build
spec:
  output:
    to:
      kind: ImageStreamTag
      name: image-build:latest
  source:
    dockerfile: |-
      FROM jee-runtime:latest
      COPY ROOT.war /deployments/ROOT.war
    images:
    - from: 1
        kind: ImageStreamTag
        name: artifact-image:latest
      paths: 2
      - sourcePath: /wildfly/standalone/deployments/ROOT.war
        destinationDir: "."
  strategy:
    dockerStrategy:
      from: 3
        kind: ImageStreamTag
        name: jee-runtime:latest
  triggers:
  - imageChange: {}
    type: ImageChange

この設定の結果、2 番目のビルドのアウトプットイメージに、WAR ファイルの作成に必要なビルドツールを含める必要がなくなります。また、この 2 番目のビルドにはイメージ変更のトリガーが含まれているので、1 番目のビルドがバイナリーアーティファクトで新規イメージを実行して作成するたびに、2 番目のビルドが自動的に、そのアーティファクトを含むランタイムイメージを生成するためにトリガーされます。そのため、どちらのビルドも、ステージが 2 つある単一ビルドのように振る舞います。

デフォルトで、ライフサイクルを完了したビルドは無制限に保持されます。保持される以前のビルドの数を制限することができます。

ビルドは、作成時のタイムスタンプで分類され、一番古いビルドが先にプルーニングされます。

ビルド実行ポリシーでは、ビルド設定から作成されるビルドを実行する順番を記述します。これには、Build の spec セクションにある runPolicy フィールドの値を変更してください。

既存のビルド設定の runPolicy 値を変更することも可能です。

ビルド内で Red Hat サブスクリプションを使用するには、Universal Base Image (UBI) を参照する ImageStream を作成する必要があります。

registry.redhat.io から UBI を直接参照するビルドには、プルシークレットが必要です。

Red Hat サブスクリプションを使用してコンテンツをインストールするビルドには、ビルドシークレットとしてエンタイトルメントキーを含める必要があります。

ベース RHEL イメージのプルに使用するパスには、以下の 2 つのパスがあります。

Docker ビルドは通常、Dockerfileのそれぞれの命令を表す層を作成します。imageOptimizationPolicy を SkipLayers に設定することにより、すべての命令がベースイメージ上部の単一層にマージされます。

strategy:
  dockerStrategy:
    imageOptimizationPolicy: SkipLayers

特定のビルドストラテジーへのアクセスをグローバルに禁止するには、cluster-admin 権限を持つユーザーとしてログインし、system:authenticated グループから対応するロールを削除し、アノテーション rbac.authorization.kubernetes.io/autoupdate: "false" を適用してそれらを API の再起動間での変更から保護します。以下の例では、Docker ビルドストラテジーを無効にする方法を示します。

一連の特定ユーザーのみが特定のストラテジーでビルドを作成できます。

ユーザーにビルドストラテジーをグローバルに付与するのと同様に、プロジェクト内の特定ユーザーのセットのみが特定ストラテジーでビルドを作成することを許可できます。

build.config.openshift.io/cluster リソースは以下の設定パラメーターを提供します。

build.config.openshift.io/cluster リソースを編集してビルドの設定を行うことができます。

リソースへのアクセス要求が拒否される場合:

requested access to the resource is denied

$ oc describe quota

リソースへのアクセス要求が拒否される場合:

secret/ssl-key references serviceUID 62ad25ca-d703-11e6-9d6f-0e9c0057b608, which does not match 77b6dd80-d716-11e6-9d6f-0e9c0057b60

$ oc delete secret <secret_name>
$ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error-
$ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error-num-

以下の手順でイメージのプッシュおよびプル時に使用する認証局 (CA) をクラスターに追加することができます。