Red Hat Training

A Red Hat training course is available for OpenShift Container Platform

開発者ガイド

OpenShift Container Platform 3.10

OpenShift Container Platform 3.10 開発者リファレンス

Red Hat OpenShift Documentation Team

概要

以下のトピックは、開発者がコマンドラインインターフェース (CLI) を使用して OpenShift Container Platform クラウド環境でアプリケーションを開発およびデプロイするためにワークステーションを設定する上で役立ちます。本書では開発者に役立つ詳細の説明および例を紹介します。
  1. Web コンソールを使用したプロジェクトのモニターおよび参照
  2. CLI の設定および利用
  3. テンプレートを使用した設定の生成
  4. ビルドおよび Webhook の管理
  5. デプロイメントの定義およびトリガー
  6. 外部サービス (データベース、SaaS エンドポイント) の統合

第1章 概要

本書はアプリケーション開発者を対象としており、OpenShift Container Platform クラウド環境でアプリケーションを開発し、デプロイするためにワークステーションをセットアップし、設定する方法について説明します。これには詳細の説明および例が含まれ、開発者が以下を実行するのに役立ちます。

第2章 アプリケーションライフサイクル管理

2.1. 開発プロセスの計画

2.1.1. 概要

OpenShift Container Platform はアプリケーションをビルドし、デプロイできるように設計されています。OpenShift Container Platform を開発プロセスにどの程度組み込むかに応じて、以下から選択できます。

  • OpenShift Container Platform プロジェクト内での開発にフォーカスして、アプリケーションをゼロからビルドし、その後の継続的な開発とライフサイクルの管理を行うために OpenShift Container Platform を使用する。
  • 別の環境ですでに開発したアプリケーション (例: バイナリー、コンテナーイメージ、ソースコード) を OpenShift Container Platform にデプロイする。

2.1.2. 開発環境としての OpenShift Container Platform の使用

Deploying then developing on OpenShift Container Platform

OpenShift Container Platform を直接使用してアプリケーションの開発をゼロから行うことができます。この種類の開発プロセスを計画する場合には、以下の手順を考慮してください。

初期計画

  • アプリケーションの機能は?
  • どのプログラミング言語を使用して開発するか?

OpenShift Container Platform へのアクセス

  • この時点で、ご自身または組織内の管理者が OpenShift Container Platform をインストールする必要があります。

開発

  • 各自が選択するエディターまたは IDE を使用して、アプリケーションの基本的なスケルトンを作成します。このスケルトンは、OpenShift Container Platform が「アプリケーションの種類」について認識できるように適切に作成されている必要があります。
  • コードを Git リポジトリーにプッシュします。

生成

管理

  • アプリケーションコードの開発を開始します。
  • アプリケーションが正常にビルドされることを確認します。
  • 引き続きコードをローカルで開発し、コードを改良します。
  • コードを Git リポジトリーにプッシュします。
  • 追加の設定が必要かどうかを確認します。追加のオプションについて『開発者ガイド』で確認してください。

検証

  • アプリケーションは数多くの方法で検証できます。変更をアプリケーションの Git リポジトリーにプッシュし、OpenShift Container Platform を使用してアプリケーションの再ビルドおよび再デプロイを行うことができます。または、rsync でホットデプロイを実行して、コードの変更を実行中の Pod で同期できます。

2.1.3. アプリケーションの OpenShift Container Platform へのデプロイ

Developing then deploying on OpenShift Container Platform

アプリケーション開発ストラテジーの別の可能性として、ローカルで開発してから OpenShift Container Platform を使用して完全に開発されたアプリケーションをデプロイする方法があります。アプリケーションコードを先に準備してからビルドし、完了後に OpenShift Container Platform インストールにデプロイする場合は、以下の手順を使用します。

初期計画

  • アプリケーションの機能は?
  • どのプログラミング言語を使用して開発するか?

開発

  • 任意のエディターまたは IDE を使用してアプリケーションコードを開発します。
  • アプリケーションコードをローカルでビルドしてテストします。
  • コードを Git リポジトリーにプッシュします。

OpenShift Container Platform へのアクセス

  • この時点で、ご自身または組織内の管理者が OpenShift Container Platform をインストールする必要があります。

生成

検証

  • 前述の生成の手順においてビルドおよびデプロイしたアプリケーションが OpenShift Container Platform で正常に実行されていることを確認します。

管理

  • 納得の行く結果が得られるまで、アプリケーションコードの開発を続けます。
  • 新たにプッシュされたコードを受け入れるには、アプリケーションを OpenShift Container Platform で再ビルドします。
  • 追加の設定が必要かどうかを確認します。追加のオプションについて『開発者ガイド』で確認してください。

2.2. 新規アプリケーションの作成

2.2.1. 概要

OpenShift CLI または web コンソールのいずれかを使用して、ソースまたはバイナリーコード、イメージおよびテンプレート (あるいは両方) を含むコンポーネントから新規の OpenShift Container Platform アプリケーションを作成できます。

2.2.2. CLI を使用したアプリケーションの作成

2.2.2.1. ソースコードからのアプリケーションの作成

new-app コマンドでは、ローカルまたはリモートの Git リポジトリーのソースコードからアプリケーションを作成できます。

ローカルディレクトリーの Git リポジトリーを使用してアプリケーションを作成するには、以下を実行します。

$ oc new-app /path/to/source/code
注記

ローカルの Git リポジトリーを使用する場合には、OpenShift Container Platform クラスターがアクセス可能な URL を参照する origin という名前のリモートが必要です。認識されているリモートがない場合は、new-app により「バイナリービルド」が作成されます。

リモート Git リポジトリーを使用してアプリケーションを作成するには、以下を実行します。

$ oc new-app https://github.com/sclorg/cakephp-ex

プライベートのリモート Git リポジトリーを使用してアプリケーションを作成するには、以下を実行します。

$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret
注記

プライベートのリモート Git リポジトリーを使用する場合には、--source-secret フラグを使用して、既存の「ソースクローンのシークレット」を指定できます。これは、BuildConfig に挿入され、リポジトリーにアクセスできるようになります。

--context-dir フラグを指定することで、ソースコードリポジトリーのサブディレクトリーを使用できます。リモート Git リポジトリーおよびコンテキストのサブディレクトリーを使用してアプリケーションを作成する場合は、以下を実行します。

$ oc new-app https://github.com/sclorg/s2i-ruby-container.git \
    --context-dir=2.0/test/puma-test-app

また、リモートの URL を指定する場合には、以下のように URL の最後に #<branch_name> を追加することで、使用する Git ブランチを指定できます。

$ oc new-app https://github.com/openshift/ruby-hello-world.git#beta4

new-app コマンドは、「ビルド設定 (BuildConfig)」を作成し、これはソースコードから、新規のアプリケーション「イメージ」を作成します。new-app コマンドは通常、「デプロイメント設定 (DeploymentConfig)」を作成して新規のイメージをデプロイするほか、「サービス」を作成してイメージを実行するデプロイメントへの負荷分散したアクセスを提供します。

OpenShift Container Platform は DockerPipeline または Source「ビルドストラテジー」のいずれを使用すべきかを自動的に「検出」します。また、Source ビルドの場合は、「適切な言語のビルダーイメージを検出します」

ビルドストラテジーの検出

新規アプリケーションの作成時に Jenkinsfile がソースリポジトリーの root または指定のコンテキストディレクトリーに存在する場合に、OpenShift Container Platform は「Pipeline ビルドストラテジー」を生成します。または、Dockerfile がある場合に、OpenShift Container Platform は 「Docker ビルドストラテジー」を生成します。Dockerfile がない場合には、「Source ビルドストラテジー」を生成します。

ビルドストラテジーを上書きするには、--strategy フラグを dockerpipeline または source のいずれかに設定してください。

$ oc new-app /home/user/code/myapp --strategy=docker
注記

oc コマンドを使用するには、ビルドのソースを含むファイルがリモートの git リポジトリーで利用できる必要があります。ソースの全ビルドには、git remote -v を使用する必要があります。

言語検出

Source ビルドストラテジーを使用する場合に、new-app はリポジトリーの root または指定したコンテキストディレクトリーに特定のファイルが存在するかどうかで、使用する言語ビルダーを判別しようとします。

表2.1 new-app が検出する言語

言語ファイル

dotnet

project.json*.csproj

jee

pom.xml

nodejs

app.jsonpackage.json

perl

cpanfileindex.pl

php

composer.jsonindex.php

python

requirements.txtsetup.py

ruby

Gemfile, Rakefileconfig.ru

scala

build.sbt

golang

Godepsmain.go

言語の検出後、new-app は、検出言語に一致する supports アノテーションが指定された 「イメージストリーム」タグか、または検出言語の名前に一致するイメージストリームがないかどうか、OpenShift Container Platform サーバーを検索します。一致するものが見つからない場合には、new-appDocker Hub レジストリー で名前をベースにした検出言語と一致するイメージの検索を行います。

~ をセパレーターとして使用し、イメージ (イメージストリームまたはコンテナーの仕様) とリポジトリーを指定して、ビルダーが特定のソースリポジトリーを使用するようにイメージを上書きすることができます。この方法を使用すると、ビルドストラテジーの検出 および 言語の検出 は実行されない点に留意してください。

たとえば、リモートリポジトリーのソースを使用して myproject/my-ruby イメージストリームを作成する場合は、以下を実行します。

$ oc new-app myproject/my-ruby~https://github.com/openshift/ruby-hello-world.git

ローカルリポジトリーのソースを使用して openshift/ruby-20-centos7:latest コンテナーのイメージストリームを作成するには、以下を実行します。

$ oc new-app openshift/ruby-20-centos7:latest~/home/user/code/my-ruby-app

2.2.2.2. イメージからアプリケーションを作成する方法

既存のイメージからアプリケーションのデプロイが可能です。イメージは、OpenShift Container Platform サーバー内のイメージストリーム、指定したレジストリー内またはDocker Hub レジストリー 内のイメージ、またはローカルの Docker サーバー内のイメージから取得できます。

new-app コマンドは、渡された引数に指定されたイメージの種類を判断しようとしますが、イメージが Docker イメージ (--docker-image の引数を使用) なのか、またはイメージストリーム (-i|--image の引数を使用) なのか、new-app に明示できます。

注記

ローカル Docker リポジトリーからイメージを指定した場合、同じイメージが OpenShift Container Platform のクラスターノードでも利用できることを確認する必要があります。

たとえば、DockerHub MySQL イメージからアプリケーションを作成するには、以下を実行します。

$ oc new-app mysql

プライベートのレジストリーのイメージを使用してアプリケーションを作成する場合には、Docker イメージの仕様全体を以下のように指定します。

$ oc new-app myregistry:5000/example/myimage
注記

イメージを含むレジストリーが「SSL でセキュリティー保護」されていない場合には、OpenShift Container Platform ノードホストの Docker デーモンが、対象のレジストリーを参照する --insecure-registry フラグを指定して実行されていることを、クラスター管理者は確認する必要があります。また、--insecure-registry フラグを指定して、セキュアでないレジストリーからイメージを取得していることを、new-app に示す必要があります。

以下のように、既存の「イメージストリーム」および任意の「イメージストリームタグ」からアプリケーションを作成することができます。

$ oc new-app my-stream:v1

2.2.2.3. テンプレートからのアプリケーションの作成

テンプレート名を引数として指定して、事前に保存した「テンプレート」またはテンプレートファイルからアプリケーションを作成することができます。たとえば、サンプルアプリケーションテンプレート を保存し、これを利用してアプリケーションを作成できます。

保存したテンプレートからアプリケーションを作成する場合、以下を実行します。

$ oc create -f examples/sample-app/application-template-stibuild.json
$ oc new-app ruby-helloworld-sample

事前に OpenShift Container Platform に保存することなく、ローカルファイルシステムでテンプレートを直接使用するには、以下の -f|--file 引数を使用します。

$ oc new-app -f examples/sample-app/application-template-stibuild.json

テンプレートパラメーター

「テンプレート」をベースとするアプリケーションを作成する場合には、以下の -p|--param 引数を使用してテンプレートで定義したパラメーター値を設定します。

$ oc new-app ruby-helloworld-sample \
    -p ADMIN_USERNAME=admin -p ADMIN_PASSWORD=mypassword

パラメーターをファイルに保存しておいて、--param-file を指定して、テンプレートをインスタンス化する時にこのファイルを使用することができます。標準入力からパラメーターを読み込む場合は、以下のように--param-file=- を使用します。

$ cat helloworld.params
ADMIN_USERNAME=admin
ADMIN_PASSWORD=mypassword
$ oc new-app ruby-helloworld-sample --param-file=helloworld.params
$ cat helloworld.params | oc new-app ruby-helloworld-sample --param-file=-

2.2.2.4. アプリケーション作成における追加修正

new-app コマンドは、OpenShift Container Platform オブジェクトを生成します。このオブジェクトにより、作成されるアプリケーションがビルドされ、デプロイされ、実行されます。通常、これらのオブジェクトはインプットソースリポジトリーまたはインプットされたイメージに由来する名前を使用して現在のプロジェクトに作成されますが、new-app によりこの動作を修正することができます。

new-app で作成したオブジェクトのセットは、ソースリポジトリー、イメージまたはテンプレートなどのインプットとして渡されるアーティファクトによって異なります。

表2.2 new-app 出力オブジェクト

オブジェクト説明

BuildConfig

BuildConfig は、コマンドラインで指定された各ソースリポジトリーに作成されます。BuildConfig は使用するストラテジー、ソースのロケーション、およびビルドの出力ロケーションを指定します。

ImageStreams

BuildConfig では、通常 2 つの ImageStreams が作成されます。1 つ目は、インプットイメージを表します。Source ビルドでは、これはビルダーイメージです。Docker ビルドでは、これは FROM イメージです。2 つ目は、アウトプットイメージを表します。コンテナーイメージが new-app にインプットとして指定された場合に、このイメージに対してもイメージストリームが作成されます。

DeploymentConfig

DeploymentConfig は、ビルドの出力または指定されたイメージのいずれかをデプロイするために作成されます。new-app コマンドは、結果として生成される DeploymentConfig に含まれるコンテナーに指定される全 Docker ボリュームに emptyDir ボリューム を作成します。

Service

new-app コマンドは、インプットイメージで公開ポートを検出しようと試みます。公開されたポートで数値が最も低いものを使用して、そのポートを公開するサービスを生成します。new-app 完了後に別のポートを公開するには、単に oc expose コマンドを使用し、追加のサービスを生成するだけです。

その他

テンプレート のインスタンスを作成する際に、他のオブジェクトがテンプレートに基づいて生成される可能性があります。

2.2.2.4.1. 環境変数の指定

テンプレートソース または イメージ からアプリケーションを生成する場合、-e|--env 引数を使用し、ランタイムに環境変数をアプリケーションコンテナーに渡すことができます。

$ oc new-app openshift/postgresql-92-centos7 \
    -e POSTGRESQL_USER=user \
    -e POSTGRESQL_DATABASE=db \
    -e POSTGRESQL_PASSWORD=password

変数は、--env-file 引数を使用してファイルから読み取ることもできます。

$ cat postgresql.env
POSTGRESQL_USER=user
POSTGRESQL_DATABASE=db
POSTGRESQL_PASSWORD=password
$ oc new-app openshift/postgresql-92-centos7 --env-file=postgresql.env

さらに --env-file=- を使用することで、標準入力で環境変数を指定することもできます。

$ cat postgresql.env | oc new-app openshift/postgresql-92-centos7 --env-file=-

詳細については、「環境変数の管理」を参照してください。

注記

-e|--env または --env-file 引数で渡される環境変数では、new-app 処理の一環として作成される BuildConfig オブジェクトは更新されません。

2.2.2.4.2. ビルド環境変数の指定

テンプレートソース または イメージ からアプリケーションを生成する場合、--build-env 引数を使用し、ランタイムに環境変数をビルドコンテナーに渡すことができます。

$ oc new-app openshift/ruby-23-centos7 \
    --build-env HTTP_PROXY=http://myproxy.net:1337/ \
    --build-env GEM_HOME=~/.gem

変数は、--build-env-file 引数を使用してファイルから読み取ることもできます。

$ cat ruby.env
HTTP_PROXY=http://myproxy.net:1337/
GEM_HOME=~/.gem
$ oc new-app openshift/ruby-23-centos7 --build-env-file=ruby.env

さらに --build-env-file=- を使用して、環境変数を標準入力で指定することもできます。

$ cat ruby.env | oc new-app openshift/ruby-23-centos7 --build-env-file=-
2.2.2.4.3. ラベルの指定

ソースイメージ または テンプレート からアプリケーションを生成する場合、-l|--label 引数を使用し、作成されたオブジェクトにラベルを追加できます。ラベルを使用すると、アプリケーションに関連するオブジェクトを一括で選択、設定、削除することが簡単になります。

$ oc new-app https://github.com/openshift/ruby-hello-world -l name=hello-world
2.2.2.4.4. 作成前の出力の表示

new-app が作成する内容についてのドライランを確認するには、yaml または json の値と共に -o|--output 引数を使用できます。次にこの出力を使用して、作成されるオブジェクトのプレビューまたは編集可能なファイルへのリダイレクトを実行できます。問題がなければ、oc create を使用して OpenShift Container Platform オブジェクトを作成できます。

new-app アーティファクトをファイルに出力するには、これらを編集し、作成します。

$ oc new-app https://github.com/openshift/ruby-hello-world \
    -o yaml > myapp.yaml
$ vi myapp.yaml
$ oc create -f myapp.yaml
2.2.2.4.5. 別名でのオブジェクトの作成

通常 new-app で作成されるオブジェクトの名前はソースリポジトリーまたは生成に使用されたイメージに基づいて付けられます。コマンドに --name フラグを追加することで、生成されたオブジェクトの名前を設定できます。

$ oc new-app https://github.com/openshift/ruby-hello-world --name=myapp
2.2.2.4.6. 別のプロジェクトでのオブジェクトの作成

通常 new-app は現在のプロジェクトにオブジェクトを作成しますが、-n|--namespace 引数を使用してアクセス可能な別のプロジェクトにオブジェクトを作成することができます。

$ oc new-app https://github.com/openshift/ruby-hello-world -n myproject
2.2.2.4.7. 複数のオブジェクトの作成

new-app コマンドは、複数のパラメーターを new-app に指定して複数のアプリケーションを作成できます。コマンドラインで指定するラベルは、この単一コマンドで作成されるすべてのオブジェクトに適用され、環境変数はソースまたはイメージから作成されるすべてのコンポーネントに適用されます。

ソースリポジトリーおよび Docker Hub イメージからアプリケーションを作成するには、以下を実行します。

$ oc new-app https://github.com/openshift/ruby-hello-world mysql
注記

ソースコードリポジトリーおよびビルダーイメージが別個の引数として指定されている場合、new-app はソースコードリポジトリーのビルダーとしてそのビルダーイメージを使用します。これを意図していない場合は、~ セパレーターを使用してソースに必要なビルダーイメージを指定します。

2.2.2.4.8. 単一 Pod でのイメージとソースのグループ化

new-app コマンドにより、単一 Pod に複数のイメージをまとめてデプロイできます。イメージのグループ化を指定するには + セパレーターを使用します。--group コマンドライン引数をグループ化する必要のあるイメージを指定する際に使用することもできます。ソースリポジトリーからビルドされたイメージを別のイメージと共にグループ化するには、そのビルダーイメージをグループで指定します。

$ oc new-app ruby+mysql

ソースからビルドされたイメージと外部のイメージをまとめてデプロイするには、以下を実行します。

$ oc new-app \
    ruby~https://github.com/openshift/ruby-hello-world \
    mysql \
    --group=ruby+mysql
2.2.2.4.9. イメージ、テンプレート、および他の入力の検索

イメージ、テンプレート、および oc new-app コマンドの他の入力内容を検索するには、--search フラグおよび --list フラグを追加します。たとえば、PHP を含むすべてのイメージまたはテンプレートを検索するには、以下を実行します。

$ oc new-app --search php

2.2.3. Web コンソールを使用したアプリケーションの作成

  1. 必要なプロジェクトで Add to Project をクリックします。

    Add to Project
  2. プロジェクト内にあるイメージの一覧またはサービスカタログからビルダーイメージを選択します。

    Browse Catalog
    注記

    以下に示すように、builder タグがアノテーションに一覧表示されている 「イメージストリームタグ」のみが一覧に表示されます。

    kind: "ImageStream"
    apiVersion: "v1"
    metadata:
      name: "ruby"
      creationTimestamp: null
    spec:
      dockerImageRepository: "registry.access.redhat.com/openshift3/ruby-20-rhel7"
      tags:
        -
          name: "2.0"
          annotations:
            description: "Build and run Ruby 2.0 applications"
            iconClass: "icon-ruby"
            tags: "builder,ruby" 1
            supports: "ruby:2.0,ruby"
            version: "2.0"
    1
    ここに builder タグを含めると、この ImageStreamTag がビルダーとして Web コンソールに表示されます。
  3. 新規アプリケーション画面で設定を変更し、オブジェクトをアプリケーションをサポートするように設定します。

    Configuration Wizard

2.3. 環境全体におけるアプリケーションのプロモート

2.3.1. 概要

アプリケーションのプロモーションとは、さまざまなランタイム環境でのアプリケーションの移動を意味します。通常は、移動により成熟度が向上していきます。たとえば、あるアプリケーションが開発環境からスタートし、ステージング環境へと進み、さらなるテストが行われ、最後に実稼働環境へとプロモートされる場合に、アプリケーションに変更が加えられると、変更が開発環境に加えられ、ステージング環境および実稼働環境へとプロモートされます。

「アプリケーション」は、単に Java、Perl、および Python などで記述された単なるソースコードを意味する訳でも、静的 Web コンテンツや統合スクリプト、またはアプリケーションの言語固有のランタイムに関連する設定に留まる訳でもありません。現在のアプリケーションは、これらの言語固有のランタイムで使用されるアプリケーション固有のアーカイブ以上のものを指します。

OpenShift Container Platform および Kubernetes と Docker を統合した基盤という環境では、追加のアプリケーションのアーティファクトとして以下が含まれます。

  • メタデータと関連ツールの豊富なセットを含む Docker コンテナーイメージ
  • アプリケーションで使用されるためにコンテナーに挿入される 環境変数
  • 以下の OpenShift Container Platform の API オブジェクト (リソース定義としても知られています。「コアとなる概念」を参照してください)。

    • アプリケーションで使用されるためにコンテナーに挿入される API オブジェクト。
    • OpenShift Container Platform によるコンテナーおよび Pod の管理方法を指示する API オブジェクト。

OpenShift Container Platform でのアプリケーションのプロモート方法を検討するため、本トピックでは以下を扱います。

  • アプリケーション定義に導入される新規アーティファクトの詳細。
  • アプリケーションのプロモーションパイプラインの各種環境を区別する方法。
  • 新規アーティファクトを管理する方法およびツールについて。
  • 各種の概念、構成、方法およびツールをアプリケーションのプロモートに適用する実例。

2.3.2. アプリケーションコンポーネント

2.3.2.1. API オブジェクト

OpenShift Container Platform および Kubernetes リソース定義 (アプリケーションインベントリーに新規に導入された項目) に関連して、アプリケーションのプロモートについて検討する際に API オブジェクトの設計ポイントについて留意しておくべき 2 つの主要な点があります。

1 つ目の点として、すべての API オブジェクトは、OpenShift Container Platform ドキュメント全体で強調されているように JSON または YAML のいずれかで表現することができます。そのため、これらのリソース定義は従来のソースコントロールおよびスクリプトを使用して容易に管理できます。

2 つ目の点として、API オブジェクトは、システムの必要とされる状態を指定するオブジェクトの部分とシステムのステータスまたは現在の状態を反映する部分で構成されるように設計されています。これはインプットおよびアウトプットとして捉えることができます。インプット部分は JSON または YAML で表現され、ソースコントロール管理 (SCM) のアーティファクトとして適合します。

注記

API オブジェクトのインプット部分つまり仕様部分は、インスタンス化の際に テンプレート処理による変数置換を実行できるため、完全に静的または動的に機能する点に留意してください。

API オブジェクトに関する上記の点により、JSON または YAML ファイルの表現を使ってアプリケーションの設定をコードとして処理することができます。

ほぼすべての API オブジェクトについて、組織はこれらをアプリケーションのアーティファクトとみなすことができます。以下は、アプリケーションのデプロイおよび管理に最も関連するオブジェクトです。

BuildConfigs
これはアプリケーションのプロモーションのコンテキストにおける特殊なリソースです。BuildConfig はとくに開発者の観点ではアプリケーションの一部ではありますが、BuildConfig は通常パイプラインでプロモートされません。これはパイプラインで (他のアイテムと共に) プロモートされる イメージ を作成します。
Templates (テンプレート)
アプリケーションのプロモーションの観点では、Templates はとくにパラメーター化機能を使ってリソースを所定のステージング環境でセットアップするための開始ポイントとしての役割を果たします。ただしアプリケーションがプロモーションのパイプラインを移動する際に、インスタンス化の後に追加の変更が生じる可能性が高くなります。詳細については、シナリオおよび実例 を参照してください。
Routes (ルート)
Route (ルート) は最も典型的なリソースで、アプリケーションプロモーションパイプラインのステージごとに異なります。アプリケーションの各種ステージに対するテストの際に、アプリケーションへのアクセスが Route 経由で行われるためです。また、ホスト名だけでなく Route の HTTP レベルのセキュリティーに関しても、手動指定や自動生成のオプションがある点に留意してください。
Services (サービス)
(初期ステージでの個々の開発者の便宜を考慮する場合など) 所定のアプリケーションプロモーションステージで Routers および Routes を避ける理由がある場合、アプリケーションは Cluster の IP アドレスおよびポート経由でアクセスできます。これらを使用した場合、ステージ間のアドレスおよびポートの管理の一部が必要となる可能性があります。
Endpoints (エンドポイント)
特定のアプリケーションレベルのサービス (たとえば、多くの企業におけるデータベースのインスタンスなど) は OpenShift Container Platform で管理されない場合があります。そのような場合に、独自に Endpoints を作成して、関連する Service (Service のセレクターフィールドは除外) に必要な修正を加えると、(環境をどのようにプランニングするかにより異なりますが) アクティビティーがステージ間で重複または共有されます。
シークレット
Secrets でカプセル化された機密情報は、その情報関連の対応するエンティティー (OpenShift Container Platform が管理する Service または OpenShift Container Platform 外で管理する外部サービス) が共有されると、ステージ環境間で共有されます。このエンティティーの異なるバージョンがアプリケーションのプロモートパイプラインの各ステージにある場合には、パイプラインの各ステージで固有の Secret を維持するか、それをパイプラインの移動時に変更する必要がある場合があります。また Secret を SCM に JSON または YAML として保存する場合、機密情報を保護するための暗号化フォームが必要となることがあるので注意してください。
DeploymentConfigs
このオブジェクトは、所定のアプリケーションのプロモーションパイプラインステージの環境を定義し、そのスコープを設定する際の最も重要なリソースになります。これはアプリケーションの起動方法を管理します。各種ステージ間で共通する部分がありますが、アプリケーションプロモーションパイプラインの移動に伴い、このオブジェクトには変更が加えられます。この変更には、各ステージの環境の違いを反映させるための修正や、アプリケーションがサポートする必要のある各種シナリオのテストを容易にするためのシステム動作を変更が含まれます。
ImageStreams, ImageStreamTags、および ImageStreamImage
「イメージ」および「イメージストリーム」の各セクションで説明されているように、これらのオブジェクトは、コンテナーイメージの管理に関連して OpenShift Container Platform の追加要素の中核を成しています。
ServiceAccounts および RoleBindings
アプリケーション管理において、OpenShift Container Platform や外部サービスでの他の API オブジェクトに対するパーミッション管理は必要不可欠です。Secrets と同様に、ServiceAccounts および RoleBindingscan オブジェクトのアプリケーションプロモーションパイプラインのステージ間での共有方法は、各種の異なる環境を共有するか、分離するかなどの各自のニーズによって異なります。
PersistentVolumeClaims
データベースのようなステートフルなサービスに関連して、これらが異なるアプリケーションプロモーションステージ間で共有される程度は、組織がアプリケーションデータのコピーを共有または隔離する方法に直接関連します。
ConfigMap
Pod 設定の Pod 自体からの分離 (環境変数スタイルの設定など) に関連して、これらは Pod の動作に一貫性をもたせる場合に各種のステージング環境で共有することができます。またこれらをステージごとに変更して Pod 動作を変更することも可能です ( 通常アプリケーションの各種の側面はステージごとに検証されます)。

2.3.2.2. イメージ

前述のように、コンテナーイメージはアプリケーションのアーティファクトであり、実際に、アプリケーションのプロモーションにおいて、イメージおよびイメージの管理は新しいアプリケーションのアーティファクトの中でも重要な部分です。場合によっては、イメージはアプリケーション全体をカプセル化する場合もあり、アプリケーションのプロモーションフローはイメージの管理のみで成り立っています。

通常イメージは SCM システムでは管理されません (アプリケーションのバイナリーが以前のシステムで管理されていなかったのと同様です)。ただしバイナリーと同様に、インストール可能なアーティファクトおよび対応するリポジトリー (RPM、RPM リポジトリー、Nexus など) は SCM と同様のセマンティクスで生成されるので、SCM に似たイメージ管理の構成および専門用語が導入されました。

  • Image registry == SCM server
  • Image repository == SCM repository

イメージはレジストリーに存在するので、アプリケーションプロモーションでは、適切なイメージがレジストリーに存在し、そのイメージで表されるアプリケーションを実行する必要のある環境からアクセスできるようにします。

イメージを直接参照するよりも、アプリケーションの定義は通常イメージストリームに参照を抽象化します。これは、イメージストリームがアプリケーションコンポーネントを構成する別の API オブジェクトになることを意味します。イメージストリームについての詳細は、「中核となる概念」を参照してください。

2.3.2.3. 概要

これまでノート、イメージ、および API オブジェクトのアプリケーションのアーティファクトについて OpenShift Container Platform 内のアプリケーションプロモーションのコンテキストで説明しました。次は、アプリケーションをプロモーションパイプラインの各種ステージの どこで 実行するのかを見ていきます。

2.3.3. デプロイメント環境

このコンテキストでのデプロイメント環境は、CI/CD パイプラインの特定ステージでアプリケーションが実行される固有のスペースを表します。通常の環境には、「開発」「テスト」「ステージング」および「実稼働環境」などが含まれます。環境の境界については、以下のようにさまざまな方法で定義できます。

  • 単一プロジェクト内のラベルおよび独自の名前を使用する
  • クラスター内の固有のプロジェクトを使用する
  • 固有のクラスターを使用する

上記の 3 つ方法すべてを利用できることが想定されます。

2.3.3.1. 留意事項

通常デプロイメント環境の構成を検討する際は、以下のヒューリスティックな側面について検討します。

  • プロモーションフローの各種ステージで許可するリソース共有の度合い
  • プロモーションフローの各種ステージで必要な分離の度合い
  • プロモーションフローの各種ステージの中心からの位置 (またはどの程度地理的に分散しているか)

さらに OpenShift Container Platform のクラスターおよびプロジェクトがイメージレジストリーにどのように関係するかについて以下の重要な点に留意してください。

  • 同一クラスター内の複数のプロジェクトは同一のイメージストリームにアクセスできる。
  • 複数のクラスターが同一の外部レジストリーにアクセスできる。
  • OpenShift Container Platform の内部イメージレジストリーがルート経由で公開される場合、クラスターはレジストリーのみを共有できる。

2.3.3.2. 概要

デプロイメント環境が定義された後、パイプライン内のステージの記述を含むプロモーションフローを実装できます。以下では、これらのプロモーションフローの実装を構成する方法およびツールについて説明します。

2.3.4. 方法およびツール

基本的にアプリケーションのプロモートとは、前述のアプリケーションのコンポーネントをある環境から別の環境に移動するプロセスのことです。アプリケーションのプロモートの自動化に関する全体的なソリューションを検討する前に、各種コンポーネントを手動で移動する場合に使用できるツールの概要について以下のサブセクションで見ていきましょう。

注記

ビルドおよびデプロイメントの両方のプロセスにおいて多数の挿入ポイントを利用できます。これらは BuildConfig および DeploymentConfig API オブジェクトで定義されます。これらの hook により、データベースなどのデプロイされたコンポーネントおよび OpenShift Container Platform クラスター自体と対話できるカスタムスクリプトの呼び出しが可能となります。

したがって、hook 内からイメージタグ操作を実行するなど、このような hook を使用して、アプリケーションを環境間で効果的に移動するコンポーネント管理操作を実行できます。ただし、これらの hook ポイントの使用は、環境間でアプリケーションコンポーネントを移動する場合よりも、所定の環境でアプリケーションのライフサイクル管理を行う場合に適しています (アプリケーションの新バージョンがデプロイされる際のデータベーススキーマの移行に使用するなど)。

2.3.4.1. API オブジェクトの管理

1 つの環境で定義されるリソースは、新しい環境へのインポートに備えて JSON または YAML ファイルの内容としてエクスポートされます。したがって JSON または YAML としての API オブジェクトの表現は、アプリケーションパイプラインで API オブジェクトをプロモートする際の作業単位として機能します。このコンテンツのエクスポートやインポートには oc CLI を使用します。

ヒント

OpenShift Container Platform のプロモーションフローには必要ないですが、JSON または YAML はファイルに保存されるので、SCM システムを使用したコンテンツの保存や取得について検討することができます。これにより、ブランチの作成、バージョンに関連する各種ラベルやタグの割り当てやクエリーなど、SCM のバージョン関連の機能を活用できるようになります。

2.3.4.1.1. API オブジェクトステートのエクスポート

API オブジェクトの仕様は、oc export で取り込む必要があります。この操作は、オブジェクト定義から環境に固有のデータを取り除き (現在の namespace または割り当てられた IP アドレスなど)、異なる環境で再作成できるようにします (オブジェクトのフィルターされていないステートを出力する oc get 操作とは異なります) 。

oc label を使用すると、API オブジェクトに対するラベルの追加、変更、または削除が可能になり、ラベルがあれば、操作 1 回で Pod のグループの選択や管理ができるので、プロモーションフロー用に収集されたオブジェクトを整理するのに有用であることが分かります。oc label を使用すると、適切なオブジェクトをエクスポートするのが簡単になります。また、オブジェクトが新しい環境で作成された場合にラベルが継承されるので、各環境のアプリケーションコンポーネントの管理も簡素化されます。

注記

API オブジェクトには、Secret を参照する DeploymentConfig などの参照が含まれることがよくあります。API オブジェクトをある環境から別の環境へと移動する際、これらの参照も新しい環境へと移動することを確認する必要があります。

同様に DeploymentConfig などの API オブジェクトには、外部レジストリーを参照する ImageStreams の参照が含まれることがよくあります。API オブジェクトをある環境から別の環境へと移動する際、このような参照が新しい環境内で解決可能であることを確認する必要があります。つまり、参照が解決可能であり、ImageStream は新しい環境でアクセス可能なレジストリーを参照できる必要があります。詳細については、「イメージの移動」および「プロモートの注意事項」を参照してください。

2.3.4.1.2. API オブジェクトステートのインポート
2.3.4.1.2.1. 初期作成

アプリケーションを新しい環境に初めて導入する場合は、API オブジェクトの仕様を表現する JSON または YAML を使用し、oc create を実行して適切な環境で作成するだけで十分です。oc create を使用する場合、--save-config オプションに留意してください。アノテーション一覧にオブジェクトの設定要素を保存しておくことで、後の oc apply を使用したオブジェクトの変更が容易になります。

2.3.4.1.2.2. 反復修正

各種のステージング環境が最初に確立されると、プロモートサイクルが開始し、アプリケーションがステージからステージへと移動します。アプリケーションの更新には、アプリケーションの一部である API オブジェクトの修正を含めることができます。API オブジェクトはOpenShift Container Platform システムの設定を表すことから、それらの変更が想定されます。それらの変更の目的として以下のケースが想定されます。

  • ステージング環境間における環境の違いについて説明する。
  • アプリケーションがサポートする各種シナリオを検証する。

oc CLI を使用することで、API オブジェクトの次のステージ環境への移行が実行されます。API オブジェクトを変更する oc コマンドセットは充実していますが、本トピックではオブジェクト間の差分を計算し、適用する oc apply に焦点を当てます。

とりわけ oc apply は既存のオブジェクト定義と共にファイルまたは標準入力 (stdin) を入力として取る 3 方向マージと見ることができます。以下の間で 3 方向マージを実行します。

  1. コマンドへの入力
  2. オブジェクトの現行バージョン
  3. 現行オブジェクトにアノテーションとして保存された最新のユーザー指定オブジェクト定義

その後に既存のオブジェクトは結果と共に更新されます。

オブジェクトがソース環境とターゲット環境間で同一であることが予期されていない場合など、API オブジェクトの追加のカスタマイズが必要な場合に、oc set などの oc コマンドは、アップストリーム環境から最新のオブジェクト定義を適用した後に、オブジェクトを変更するために使用できます。

使用方法についての詳細は、「シナリオおよび実例」を参照してください。

2.3.4.2. イメージおよびイメージストリームの管理

OpenShift Container Platform のイメージも一連の API オブジェクトで管理されます。ただし、イメージの管理はアプリケーションのプロモートにおける非常に中心的な部分であるため、イメージに最も直接的に関係するツールおよび API オブジェクトについては別途扱います。イメージのプロモートの管理には、手動および自動の方法を使用できます (パイプラインによるイメージの伝搬) 。

2.3.4.2.1. イメージの移動
注記

イメージの管理に関する注意事項すべての詳細については、「イメージの管理」のトピックを参照してください。

2.3.4.2.1.1. ステージング環境がレジストリーを共有する場合

ステージング環境が同じ OpenShift Container Platform レジストリーを共有する場合 (すべてが同じ OpenShift Container Platform クラスター上にある場合など)、アプリケーションのプロモートパイプラインのステージ間でイメージを 移動する 基本的な方法として、以下の 2 つ操作を実行できます。

  1. 1 つ目は、 docker tag および git tag と類似する oc tag コマンドにより、OpenShift Container Platform のイメージストリームを特定のイメージへの参照で更新できます。また、あるイメージストリームから別のイメージストリームへとイメージの特定のバージョンへの参照をコピーすることも可能で、クラスター内の複数の異なるプロジェクト全体でもコピーが可能です。
  2. 2 つ目として、oc import-image は外部レジストリーとイメージストリーム間の橋渡しの機能を持ちます。レジストリーから所定のイメージのメタデータをインポートし、これを「イメージストリームタグ」としてイメージストリームに保存します。プロジェクトの各種の BuildConfigs および DeploymentConfigs がこれらの特定のイメージを参照できます。
2.3.4.2.1.2. ステージング環境が異なるレジストリーを使用する場合

ステージング環境が異なる OpenShift Container Platform レジストリーを活用している場合、より高度な使用方法が見られます。内部レジストリーへのアクセス で、手順を詳細に説明していますが、まとめると以下のようになります。

  1. OpenShift Container Platform のアクセストークンの取得と関連して docker コマンドを使用し、docker login コマンドに指定します。
  2. OpenShift Container Platform レジストリーにログインした後、docker pulldocker tag および docker push を使用してイメージを移行します。
  3. イメージがパイプラインの次の環境のレジストリーで利用可能になってから、必要に応じて oc tag を使用してイメージストリームを設定します。
2.3.4.2.2. デプロイ

変更対象が基礎となるアプリケーションイメージであるか、アプリケーションを設定する API オブジェクトであるかを問わず、プロモートされた変更を認識するにはデプロイメントが通常必要になります。アプリケーションのイメージが変更される場合 (アップストリームからのイメージのプロモートの一環としての oc tag 操作または docker push の実行による場合など)、DeploymentConfigImageChangeTriggers が新規デプロイメントをトリガーできます。同様に DeploymentConfig API オブジェクト自体が変更されている場合、API オブジェクトがプロモーション手順によって更新されると (例: oc apply)、ConfigChangeTrigger がデプロイメントを開始できます。

それ以外の場合に、手動のデプロイメントを容易にする oc コマンドには以下が含まれます。

  • oc rollout: デプロイメント管理の新しいアプローチです(停止と再開のセマンティクスおよび履歴管理に関する充実した機能を含む)。
  • oc rollback: 以前のデプロイメントに戻すことができます。プロモーションのシナリオでは、新しいバージョンのテストで問題が発生した場合には、以前のバージョンで問題がないかどうかを確認する必要がある場合があります。
2.3.4.2.3. Jenkins でのプロモーションフローの自動化

アプリケーションをプロモートする際に環境間での移動が必要なアプリケーションのコンポーネントを理解し、コンポーネントを移動する際に必要な手順を理解した後に、ワークフローのオーケストレーションおよび自動化を開始できます。OpenShift Container Platform は、このプロセスで役立つ Jenkins イメージおよびプラグインを提供しています。

OpenShift Container Platform Jenkins のイメージについては、「イメージの使用」で詳細に説明されています。これには Jenkins と Jenkins Pipeline の統合を容易にする OpenShift Container Platform プラグインのセットも含まれます。また、「Pipeline ビルドストラテジー」により、Jenkins Pipeline と OpenShift Container Platform との統合が容易になります。これらすべてはアプリケーションのプロモートを含む、CI/CD のさまざまな側面の有効化に焦点を当てています。

アプリケーションのプロモート手順の手動による実行から自動へと切り替える際には、以下の OpenShift Container Platform が提供する Jenkins 関連の機能に留意してください。

  • OpenShift Container Platform は、OpenShift Container Platform クラスターでのデプロイメントを非常に容易なものとするために高度にカスタマイズされた Jenkins のイメージを提供します。
  • Jenkins イメージには OpenShift Pipeline プラグインが含まれます。これはプロモーションワークフローを実装する構成要素を提供します。これらの構成要素には、イメージストリームの変更に伴う Jenkins ジョブのトリガーやそれらのジョブ内でのビルドおよびデプロイメントのトリガーも含まれます。
  • OpenShift Container Platform の Jenkins Pipeline のビルドストラテジーを使用する BuildConfigs により、Jenkinsfile ベースの Jenkins Pipeline ジョブの実行が可能になります。パイプラインジョブは Jenkins における複雑なプロモーションフロー用の戦略を構成するものであり、OpenShift Pipeline プラグインにより提供される手順を利用できます。
2.3.4.2.4. プロモーションについての注意事項
2.3.4.2.4.1. API オブジェクト参照

API オブジェクトは他のオブジェクトを参照することができます。この一般的な使用方法として、イメージストリームを参照するDeploymentConfig を設定します (他の参照関係も存在する場合があります)。

ある環境から別の環境へと API オブジェクトをコピーする場合、すべての参照がターゲット環境内で解決できることが重要となります。以下のような参照のシナリオを見てみましょう。

  • プロジェクトに「ローカル」から参照している場合。この場合、参照オブジェクトは、プロジェクトを参照しているオブジェクトと同じプロジェクトに存在します。通常の方法として、参照しているオブジェクトと同じプロジェクト内にあるターゲット環境に参照オブジェクトをコピーできることを確認します。
  • 他のプロジェクトのオブジェクトを参照する場合。これは、共有プロジェクトのイメージストリームが複数のアプリケーションプロジェクトによって使用されている場合によくあるケースです (「イメージの管理」を参照してください)。この場合、参照するオブジェクトを新しい環境にコピーする際、ターゲット環境内で解決できるように参照を随時更新しなければなりません。以下が必要になる場合があります。

    • 共有されるプロジェクトの名前がターゲット環境では異なる場合、参照先のプロジェクトを変更する。
    • 参照されるオブジェクトを共有プロジェクトからターゲット環境のローカルプロジェクトへと移動し、主要オブジェクトをターゲット環境へと移動する際に参照をローカルルプロジェクトをポイントするよう更新する。
    • 参照されるオブジェクトのターゲット環境へのコピーおよびその参照の更新の他の組み合わせ。

通常は、新しい環境にコピーされるオブジェクトによって参照されるオブジェクトを確認し、参照がターゲット環境で解決可能であることを確認することをお勧めします。それ以外には、参照の修正を行うための適切なアクションを取り、ターゲット環境で参照されるオブジェクトを利用可能にすることができます。

2.3.4.2.4.2. イメージレジストリー参照

イメージストリームはイメージレポジトリーを参照してそれらが表すイメージのソースを示唆します。イメージストリームがある環境から別の環境へと移動する場合、レジストリーおよびレポジトリーの参照も変更すべきかどうかを検討することが重要です。

  • テスト環境と実稼働環境間の分離をアサートするために異なるイメージレジストリーが使用されている場合。
  • テスト環境および実稼働環境に対応したイメージを分離するために異なるイメージレポジトリーが使用されている場合。

上記のいずれかが該当する場合、イメージストリームはソース環境からターゲット環境にコピーされる際に、適切なイメージに対して解決されるよう変更される必要があります。これは、あるレジストリーおよびレポジトリーから別のレジストリーおよびレポジトリーへとイメージをコピーするという シナリオおよび実例 に説明されている手順の追加として行われます。

2.3.4.3. 概要

現時点で、以下が定義されています。

  • デプロイされたアプリケーションを構成する新規アプリケーションアーティファクト。
  • アプリケーションのプロモーションアクティビティーと OpenShift Container Platform によって提供されるツールおよびコンセプトとの相関関係。
  • OpenShift Container Platform と CI/CD パイプラインエンジン Jenkins との統合。

このトピックにおける残りの部分では、OpenShift Container Platform 内のアプリケーションのプロモーションフローのいくつかの例について扱います。

2.3.5. シナリオおよび実例

Docker、Kubernetes および OpenShift Container Platform のエコシステムにより導入された新規アプリケーションアーティファクトのコンポーネントを定義した上に、このセクションでは OpenShift Container Platform によって提供される方法およびツールを使用してこれらのコンポーネントを環境間でプロモートする方法を説明します。

アプリケーションを構成するコンポーネントにおいて、イメージは主要なアーティファクトです。これを前提とし、かつアプリケーションのプロモーションに当てはめると、中心的なアプリケーションのプロモーションパターンとなるのがイメージのプロモーションであり、この場合にイメージが作業単位となります。ほとんどのアプリケーションプロモーションシナリオでは、プロモーションパイプラインを使用したイメージの管理および伝搬が行われます。

単純なシナリオでは、パイプラインを使用したイメージの管理および伝搬のみを扱います。プロモーションシナリオの対象範囲が広がるにつれ、API オブジェクトを筆頭とする他のアプリケーションアーティファクトがパイプラインで管理および伝搬されるアイテムのインベントリーに含まれます。

このトピックでは、手動および自動の両方のアプローチを使用して、イメージおよび API オブジェクトのプロモートに関する特定の実例をいくつか紹介します。最初にアプリケーションのプロモーションパイプラインの環境のセットアップに関して、以下の点に留意してください。

2.3.5.1. プロモーションのセットアップ

アプリケーションの初期リビジョンの開発が完了すると、次の手順として、プロモーションパイプラインのステージング環境に移行できるようにアプリケーションのコンテンツをパッケージ化します。

  1. 最初に、表示されるすべての API オブジェクトを移行可能なものとしてグループ化し、共通の label を適用します。

    labels:
      promotion-group: <application_name>

    前述のように oc label コマンドは、さまざまな API オブジェクトのラベルの管理を容易にします。

    ヒント

    OpenShift Container Platform テンプレートに API オブジェクトを最初に定義する場合、プロモート用にエクスポートする際にクエリーに使用する共通のラベルがすべての関連するオブジェクトにあることを簡単に確認できます。

  2. このラベルは後続のクエリーで使用できます。たとえば、アプリケーションの API オブジェクトの移行を行う以下の oc コマンドセットの呼び出しについて検討しましょう。

    $ oc login <source_environment>
    $ oc project <source_project>
    $ oc export dc,is,svc,route,secret,sa -l promotion-group=<application_name> -o yaml > export.yaml
    $ oc login <target_environment>
    $ oc new-project <target_project> 1
    $ oc create -f export.yaml
    1
    または、すでに存在している場合は oc project <target_project> を実行します。
    注記

    oc export コマンドでは、イメージストリーム用に is タイプを含めるかどうかは、パイプライン内の異なる環境全体でイメージ、イメージストリーム、およびレジストリーの管理方法をどのように選択するかによって変わってきます。この点に関する注意事項を以下で説明しています。イメージの管理 のトピックも参照してください。

  3. プロモーションパイプラインの各種のステージング環境で使用されるそれぞれのレジストリーに対して機能するトークンを取得する必要があります。各環境について以下を実行します。

    1. 環境にログインします。

      $ oc login <each_environment_with_a_unique_registry>
    2. 以下を実行してアクセストークンを取得します。

      $ oc whoami -t
    3. 次回に使用できるようにトークン値をコピーアンドペーストします。

2.3.5.2. 繰り返し可能なプロモーションプロセス

パイプラインの異なるステージング環境での初回のセットアップ後に、プロモーションパイプラインを使用したアプリケーションの反復を検証する繰り返し可能な手順のセットを開始できます。これらの基本的な手順は、ソース環境のイメージまたは API オブジェクトが変更されるたびに実行されます。

更新後のイメージの移動→更新後の API オブジェクトの移動→環境固有のカスタマイズの適用

  1. 通常、最初の手順ではアプリケーションに関連するイメージの更新をパイプラインの次のステージにプロモートします。前述のように、ステージング環境間で OpenShift Container Platform レジストリーが共有されるかどうかが、イメージをプロモートする上での主要な差別化要因となります。

    1. レジストリーが共有されている場合、単に oc tag を使用します。

      $ oc tag <project_for_stage_N>/<imagestream_name_for_stage_N>:<tag_for_stage_N> <project_for_stage_N+1>/<imagestream_name_for_stage_N+1>:<tag_for_stage_N+1>
    2. レジストリーが共有されていない場合、ソースおよび宛先の両方のレジストリーにログインする際、各プロモーションパイプラインレジストリーに対してアクセストークンを使用でき、アプリケーションイメージのプル、タグ付け、およびプッシュを随時実行できます。

      1. ソース環境レジストリーにログインします。

        $ docker login -u <username> -e <any_email_address> -p <token_value> <src_env_registry_ip>:<port>
      2. アプリケーションのイメージをプルします。

        $ docker pull <src_env_registry_ip>:<port>/<namespace>/<image name>:<tag>
      3. アプリケーションのイメージを宛先レジストリーの場所にタグ付けし、宛先ステージング環境と一致するように namespace、名前、タグを随時更新します。

        $ docker tag <src_env_registry_ip>:<port>/<namespace>/<image name>:<tag> <dest_env_registry_ip>:<port>/<namespace>/<image name>:<tag>
      4. 宛先ステージング環境レジストリーにログインします。

        $ docker login -u <username> -e <any_email_address> -p <token_value> <dest_env_registry_ip>:<port>
      5. イメージを宛先にプッシュします。

        $ docker push <dest_env_registry_ip>:<port>/<namespace>/<image name>:<tag>
        ヒント

        外部レジストリーからイメージの新バージョンを自動的にインポートするために、oc tag コマンドで --scheduled オプションを使用できます。これを使用する場合、ImageStreamTag が参照するイメージは、イメージをホストするレジストリーから定期的にプルされます。

  2. 次に、アプリケーションの変化によってアプリケーションを構成する API オブジェクトの根本的な変更や API オブジェクトセットへの追加と削除が必要となるケースがあります。アプリケーションの API オブジェクトにこのような変化が生じると、OpenShift Container Platform CLI はあるステージング環境から次の環境へと変更を移行するための広範囲のオプションを提供します。

    1. プロモーションパイプラインの初回セットアップ時と同じ方法で開始します。

      $ oc login <source_environment>
      $ oc project <source_project>
      $ oc export dc,is,svc,route,secret,sa -l promotion-group=<application_name> -o yaml > export.yaml
      $ oc login <target_environment>
      $ oc <target_project>
    2. 単に新しい環境でリソースを作成するのではなく、それらを更新します。これを実行するための方法がいくつかあります。

      1. より保守的なアプローチとして、oc apply を使用し、ターゲット環境内の各 API オブジェクトに新しい変更をマージできます。これを実行することにより、--dry-run=true オプションを実行し、オブジェクトを実際に変更する前に結果として得られるオブジェクトを確認することができます。

        $ oc apply -f export.yaml --dry-run=true

        問題がなければ、apply コマンドを実際に実行します。

        $ oc apply -f export.yaml

        apply コマンドはより複雑なシナリオで役立つ追加の引数をオプションで取ります。詳細については oc apply --help を参照してください。

      2. または、よりシンプルで積極的なアプローチとして、oc replace を使用できます。この更新および置換についてはドライランは利用できません。最も基本的な形式として、以下を実行できます。

        $ oc replace -f export.yaml

        apply と同様に、replace はより高度な動作については他の引数をオプションで取ります。詳細は、oc replace --help を参照してください。

  3. 直前の手順では、導入された新しい API オブジェクトは自動的に処理されますが、API オブジェクトがソースの環境から削除された場合には、 oc delete を使用してこれらをターゲットの環境から手動で削除する必要があります。
  4. ステージング環境ごとに必要な値が異なる可能性があるため、API オブジェクトで引用された環境変数を調整する必要がある場合があります。この場合は oc set env を使用します。

    $ oc set env <api_object_type>/<api_object_ID> <env_var_name>=<env_var_value>
  5. 最後に、oc rollout コマンドまたは、上記の「デプロイメント」のセクションで説明した他のメカニズムを使用して、更新したアプリケーションの新規デプロイメントをトリガーします。

2.3.5.3. Jenkins を使用した反復可能なプロモーションプロセス

OpenShift Container Platform の Jenkins Docker イメージ で定義された OpenShift サンプル ジョブは、Jenkins 構成ベースの OpenShift Container Platform でのイメージのプロモーションの例です。このサンプルのセットアップは OpenShift Origin ソースリポジトリー にあります。

このサンプルには以下が含まれます。

  • CI/CD エンジンとして Jenkins の使用。
  • OpenShift Pipeline plug-in for Jenkins の使用。このプラグインでは、Jenkins Freestyle および DSL Job ステップとしてパッケージされた OpenShift Container Platform の oc CLI が提供する機能サブセットを提供します。oc バイナリーは、OpenShift Container Platform 用の Jenkins Docker イメージにも含まれており、Jenkins ジョブで OpenShift Container Platform と対話するために使用することも可能です。
  • OpenShift Container Platform が提供する Jenkins のテンプレート。一時ストレージおよび永続ストレージの両方のテンプレートがあります。
  • サンプルアプリケーション: OpenShift Origin ソースリポジトリー で定義されます。このアプリケーションは ImageStreamsImageChangeTriggersImageStreamTagsBuildConfigs およびプロモーションパイプラインの各種ステージに対応した別個の DeploymentConfigsServices を利用します。

以下では、OpenShift のサンプルジョブを詳細に検証していきます。

  1. 最初のステップ は、oc scale dc frontend --replicas=0 の呼び出しと同じです。この手順は、実行されている可能性のあるアプリケーションイメージの以前のバージョンを終了させるために実行されます。
  2. 2 番目のステップoc start-build frontend の呼び出しと同じです。
  3. 3 番目のステップoc rollout latest dc/frontend の呼び出しと同じです。
  4. 4 番目のステップ は、このサンプルの「テスト」を行います。このステップでは、アプリケーションに関連するサービスがネットワークからアクセス可能であることを確認します。背後で、OpenShift Container Platform サービスに関連する IP アドレスやポートにソケット接続を試みます。当然のこととして別のテストを追加することも可能です (OpenShift Pipepline plug-in ステップを使用しない場合は、Jenkins Shell ステップを使用して、OS レベルのコマンドとスクリプトを使用してアプリケーションをテストします)。
  5. 5 番目のステップ は、アプリケーションがテストに合格したことを前提としているため、イメージは「Ready (使用準備完了)」としてマークされます。このステップでは、新規の prod タグが 最新の イメージをベースにしたアプリケーションイメージ用に作成されます。フロントエンドの DeploymentConfigそのタグに対してImageChangeTrigger が定義されている場合には、対応する「実稼働」デプロイメントが起動されます。
  6. 6 番目と最後のステップ は検証のステップで、OpenShift Container Platform が「実稼働」デプロイメントのレプリカを必要なの数を起動したことを確認します。

第3章 認証

3.1. Web コンソール認証

ブラウザーで <master_public_addr>:8443「Web コンソール」にアクセスすると、自動的にログインページにリダイレクトされます。

「ブラウザーのバージョンとオペレーティングシステム」を使用して、Web コンソールにアクセスできることを確認します。

このページでログイン認証情報を入力して、API 呼び出しを行うためのトークンを取得します。ログイン後には、「Web コンソール」を使用してプロジェクトをナビゲートできます。

3.2. CLI 認証

CLI コマンドの oc login を使用して、コマンドラインで認証することができます。オプションなしにこのコマンドを実行して、「CLI の使用を開始」できます。

$ oc login

このコマンドの対話式フローでは、指定の認証情報を使用して OpenShift Container Platform サーバーへのセッションを確立することができます。OpenShift Container Platform サーバーに正常にログインするための情報がない場合には、必要に応じてコマンドにより、ユーザー入力を求めるプロンプトが出されます。「設定」は自動的に保存され、その後のコマンドすべてに使用されます。

oc login コマンドのすべての設定オプションは oc login --help コマンドの出力で表示されますが、オプションの指定は任意です。以下の例では、一般的なオプションの使用方法を紹介します。

$ oc login [-u=<username>] \
  [-p=<password>] \
  [-s=<server>] \
  [-n=<project>] \
  [--certificate-authority=</path/to/file.crt>|--insecure-skip-tls-verify]

以下の表では、一般的なオプションを紹介しています。

表3.1 一般的な CLI 設定オプション

オプション構文説明

-s, --server

$ oc login -s=<server>

OpenShift Container Platform サーバーのホスト名を指定します。サーバーがこのフラグで指定されている場合には、このコマンドではホスト名は対話的に確認されません。また、このフラグは、CLI 設定ファイルがある場合や、ログインして別のサーバーに切り替える場合に使用できます。

-u, --username および -p, --password

$ oc login -u=<username> -p=<password>

OpenShift Container Platform サーバーにログインするための認証情報を指定できます。これらのフラグを指定してユーザー名またはパスワードを入力した場合は、このコマンドでは、ユーザー名やパスワードが対話的に確認されません。設定ファイルでセッショントークンを確立し、ログインしてから別のユーザー名に切り替える場合に、これらのフラグを使用することができます。

-n, --namespace

$ oc login -u=<username> -p=<password> -n=<project>

oc login と合わせて使用する場合は、グローバル CLI オプションは、指定のユーザーとしてログインしている場合に、切り替え後のプロジェクトを指定することができます。

--certificate-authority

$ oc login --certificate-authority=<path/to/file.crt>

HTTPS を使用する OpenShift Container Platform サーバーで正常かつセキュアに認証します。認証局ファイルへのパスは指定する必要があります。

--insecure-skip-tls-verify

$ oc login --insecure-skip-tls-verify

HTTPS サーバーとの対話を可能にして、サーバーの証明書チェックを省略します。ただし、これはセキュリティーが確保されない点に注意してください。有効な証明書を提示しない HTTPS サーバーに oc login を試行する際に、これかまたは --certificate-authority フラグを指定しない場合に、oc login は接続がセキュアでないこと確認するユーザー入力 (y/N の入力形式) を求めるプロンプトを出します。

CLI 設定ファイルを使用すると、簡単に「複数の CLI プロファイル」を管理することができます。

注記

管理者認証情報があるのに、「デフォルトシステムユーザー」system:admin としてログインされていない場合、認証情報が 「CLI 設定ファイル」にある限り、いつでもこのユーザーとしてログインし直すことができます。以下のコマンドはログインを実行し、「デフォルト」プロジェクトに切り替えます。

$ oc login -u system:admin -n default

第4章 承認

4.1. 概要

以下のトピックでは、アプリケーション開発者向けの「認証タスク」と、クラスター管理者が指定する認証機能について紹介します。

4.2. ユーザーの Pod 作成権限の有無の確認

scc-reviewscc-subject-review オプションを使用することで、個別ユーザーまたは特定のサービスアカウントのユーザーが Pod を作成または更新可能かどうかを確認できます。

scc-review オプションを使用すると、サービスアカウントが Pod を作成または更新可能かどうかを確認できます。このコマンドは、リソースを許可する SCC (Security Context Constraints) について出力します。

たとえば、system:serviceaccount:projectname:default サービスアカウントのユーザーが Pod を作成可能かどうかを確認するには、以下を実行します。

$ oc policy scc-review -z system:serviceaccount:projectname:default -f my_resource.yaml

scc-subject-review オプションを使用して、特定のユーザーが Pod を作成または更新できるかどうかを確認することも可能です。

$ oc policy scc-subject-review -u <username> -f my_resource.yaml

特定のグループに所属するユーザーが特定のファイルで Pod を作成できるかどうかを確認するには、以下を実行します。

$ oc policy scc-subject-review -u <username> -g <groupname> -f my_resource.yaml

4.3. 認証済みのユーザーとして何が実行できるのかを判断する方法

OpenShift Container Platform プロジェクト内から、(サードパーティーのリソースを含む) namespace スコープの全リソースに対してどのような 「verb (動詞)」を実行できるのかを判断することができます。

can-i コマンドオプションは、ユーザーとロール関連のスコープをテストします。

$ oc policy can-i --list --loglevel=8

この出力で、情報収集のために呼び出す API 要求を判断しやすくなります。

ユーザーが判読可能な形式で情報を取得し直すには、以下を実行します。

$ oc policy can-i --list

この出力では、完全な一覧が表示されます。

特定の verb (動詞) を実行可能かどうかを判断するには、以下を実行します。

$ oc policy can-i <verb> <resource>

「ユーザースコープ」は、指定のスコープに関する詳細情報を提供します。以下に例を示します。

$ oc policy can-i <verb> <resource> --scopes=user:info

第5章 プロジェクト

5.1. 概要

「プロジェクト」を使用すると、ユーザーコミュニティーが、他のコミュニティーとは別にコンテンツを整理し、管理することができます。

5.2. プロジェクトの作成

クラスター管理者が 「許可した場合は」「CLI」または「Web コンソール」を使用して新規プロジェクトを作成することができます。

5.2.1. Web コンソールの使用

Web コンソールを使用して新規プロジェクトを作成するには、Project パネルまたは Project ページの Create Project ボタンをクリックします。

Create Project

Create Project ボタンはデフォルトで表示されていますが、オプションで非表示にしたり、カスタマイズしたりすることができます。

5.2.2. CLI の使用

CLI を使用して新規プロジェクトを作成するには、以下を実行します。

$ oc new-project <project_name> \
    --description="<description>" --display-name="<display_name>"

以下に例を示します。

$ oc new-project hello-openshift \
    --description="This is an example project to demonstrate OpenShift v3" \
    --display-name="Hello OpenShift"
注記

作成可能なプロジェクト数は、「システム管理者が制限することができます」。上限に達すると、既存のプロジェクトを削除してからでないと、新しいプロジェクトは作成できません。

5.3. プロジェクトの表示

プロジェクトを表示する場合は、「認証ポリシー」に基いて、表示アクセスのあるプロジェクトだけを表示できるように制限されます。

プロジェクトの一覧を表示するには、以下を実行します。

$ oc get projects

CLI 操作について現在のプロジェクトから別のプロジェクトに切り換えることができます。その後の操作についてはすべて指定のプロジェクトが使用され、プロジェクトスコープのコンテンツの操作が実行されます。

$ oc project <project_name>

また、「Web コンソール」を使用してプロジェクト間の表示や切り替えが可能です。「認証」してログインすると、アクセスできるプロジェクト一覧が表示されます。

サービスカタログの右側のパネルでは、最近アクセスしたプロジェクト (最大 5 個) へのクィックアクセスが可能です。プロジェクトの詳細一覧については、右パネルの上部にある View All リンクを使用します。

Projects List

「CLI」を使用して 「新規プロジェクト」を作成する場合は、ブラウザーでページを更新して、新規プロジェクトを表示できます。

プロジェクトを選択すると、そのプロジェクトの「プロジェクトの概要」が表示されます。

特定プロジェクトの kebab (ケバブ) メニューをクリックすると、以下のオプションが表示されます。

Project Kebab Menu

5.4. プロジェクトステータスの確認

oc status コマンドは、コンポーネントと関係を含む現在のコンポーネントの概要を示します。このコマンドには引数は指定できません。

$ oc status

5.5. ラベル別の絞り込み

リソースの「ラベル」を使用して、「Web コンソール」のプロジェクトページのコンテンツを絞り込むことができます。提案されたラベル名や値から選択することも、独自の内容を入力することも可能です。また、複数のフィルターを指定することもできます。複数のフィルターが適用される場合には、リソースはすべてのフィルターと一致しないと表示されなくなります。

ラベル別で絞り込むには以下を実行します。

  1. ラベルタイプを選択します。

    List of options
  2. 以下のいずれかを選択します。

    exists

    ラベル名が存在することを確認するだけで、値は無視します。

    does not exist

    ラベル名が存在しないことを確認してこの値を無視します。

    in

    ラベル名が存在し、選択した値の 1 つと同じであることを確認します。

    not in

    ラベル名が存在しない、または選択した値に該当しないことを確認します。

    Web Console Filter Step 2
    1. in または not in を選択した場合には、値セットを選択してから、Filter を選択します。

      Web Console Filter Step 3
  3. フィルターの追加後に、Clear all filters を選択するか、削除するフィルターをそれぞれクリックして、絞り込みを停止します。

    Clear filters

5.6. ページの状態のブックマーク

OpenShift Container Platform「Web コンソール」では、ページの状態をブックマークできるようになり、ラベルのフィルターや他の設定を保存する場合に役立ちます。

タブ間の切り替えなど、ページの状態を変更する作業を行った場合には、ブラウザーのナビゲーションバーの URL が自動的に更新されます。

5.7. プロジェクトの削除

プロジェクトを削除すると、サーバーは Terminating から Active にプロジェクトのステータスを更新します。次にサーバーは、Terminating の状態のプロジェクトからコンテンツをすべて削除してから、プロジェクトを最終的に削除します。プロジェクトが Terminating のステータスの間は、ユーザーはそのプロジェクトに新規コンテンツを追加できません。プロジェクトは、CLI または Web コンソールで削除できます。

CLI を使用してプロジェクトを削除するには以下を実行します。

$ oc delete project <project_name>

第6章 アプリケーションの移行

6.1. 概要

以下のトピックでは、OpenShift version 2 (v2) アプリケーションから OpenShift version 3 (v3) に移行する手順を説明します。

注記

以下のトピックでは、OpenShift v2 に固有の用語を使用します。「「OpenShift Enterprise 2 と OpenShift Enterprise 3 の比較」では、これら 2 つのバージョンや、使用する用語の違いについて詳しく説明しています。

OpenShift v2 アプリケーションから OpenShift Container Platform v3 に移行するには、各 v2 カートリッジは OpenShift Container Platform v3 の対応のイメージまたはテンプレートと同等であり、個別に移行する必要があるので、v2 アプリケーションのすべてのカートリッジを記録する必要があります。またそれぞれのカートリッジについて、すべての依存関係または必要なパッケージは v3 イメージに含める必要があるため、それらを記録する必要もあります。

一般的な移行手順は以下のとおりです。

  1. v2 アプリケーションをバックアップします。

    • Web カートリッジ: ソースコードは、GitHub のリポジトリーにプッシュするなど、Git リポジトリーにバックアップすることができます。
    • データベースカートリッジ: データベースは、dump コマンドを使用してバックアップすることができます (mongodumpmysqldumppg_dump)。
    • Web およびデータベースカートリッジ: rhc クライアントツールには、複数のカートリッジをバックアップするスナップショットの機能があります。

      $ rhc snapshot save <app_name>

      スナップショットは展開可能な tar ファイルであり、このファイルには、アプリケーションのソースコードとデータベースのダンプが含まれます。

  2. アプリケーションにデータベースカートリッジが含まれる場合には、v3 データベースアプリケーションを作成し、データベースダンプを新しい v3 データベースアプリケーションの Pod に同期してから、データベースの復元コマンドを使用して v3 データベースアプリケーションに v2 データベースを復元します。
  3. Web フレームワークアプリケーションの場合には、v3 と互換性を持たせるようにアプリケーションのソースコードを編集してから、Git リポジトリーの適切なファイルに、必要な依存関係やパッケージを追加します。v2 環境変数を適切な v3 環境変数に変換します。
  4. ソース (Git リポジトリー) または Git URL のクイックスタートから v3 アプリケーションを作成します。また、データベースのサービスパラメーターを新規アプリケーションに追加して、データベースアプリケーションと Web アプリケーションをリンクします。
  5. v2 には統合 git 環境があり、アプリケーションは v2 git リポジトリーに変更がプッシュされるたびに自動的に再ビルドされ、再起動されます。v3 では、ビルドがパブリックの git リポジトリーにプッシュされるソースコードの変更で自動的にトリガーされるようにするために、v3 の初期ビルドの完了後に webhook を設定する必要があります。

6.2. データベースアプリケーションの移行

6.2.1. 概要

以下のトピックでは、MySQL、PostgreSQL および MongoDB データベースアプリケーションを OpenShift バージョン 2 (v2) から OpenShift version 3 (v3) に移行する方法を確認します。

6.2.2. サポートされているデータベース

v2v3

MongoDB: 2.4

MongoDB: 2.4、2.6

MySQL: 5.5

MySQL: 5.5、5.6

PostgreSQL: 9.2

PostgreSQL: 9.2、9.4

6.2.3. MySQL

  1. すべてのデータベースをダンプファイルにエクスポートして、これをローカルマシン (現在のディレクトリー) にコピーします

    $ rhc ssh <v2_application_name>
    $ mysqldump --skip-lock-tables -h $OPENSHIFT_MYSQL_DB_HOST -P ${OPENSHIFT_MYSQL_DB_PORT:-3306} -u ${OPENSHIFT_MYSQL_DB_USERNAME:-'admin'} \
     --password="$OPENSHIFT_MYSQL_DB_PASSWORD" --all-databases > ~/app-root/data/all.sql
    $ exit
  2. dbdump をローカルマシンにダウンロードします。

    $ mkdir mysqldumpdir
    $ rhc scp -a <v2_application_name> download mysqldumpdir app-root/data/all.sql
  3. テンプレートから v3 mysql-persistent Pod を作成します。

    $ oc new-app mysql-persistent -p \
       MYSQL_USER=<your_V2_mysql_username> -p \
       MYSQL_PASSWORD=<your_v2_mysql_password> -p MYSQL_DATABASE=<your_v2_database_name>
  4. Pod の使用準備ができているかどうかを確認します。

    $ oc get pods
  5. Pod の実行中に、データベースのアーカイブファイルを v3 MySQL Pod にコピーします。

    $ oc rsync /local/mysqldumpdir <mysql_pod_name>:/var/lib/mysql/data
  6. v3 の実行中の Pod に、データベースを復元します。

    $ oc rsh <mysql_pod>
    $ cd /var/lib/mysql/data/mysqldumpdir

    v3 では、データベースを復元するには、root ユーザーとして MySQL にアクセスする必要があります。

    v2 では、$OPENSHIFT_MYSQL_DB_USERNAME には全データベースに対する完全な権限がありました。v3 では、権限をデータベースごとに $MYSQL_USER に割り当てる必要があります。

    $ mysql -u root
    $ source all.sql

    <dbname> のすべての権限を <your_v2_username>@localhost に割り当ててから、権限をフラッシュします。

  7. Pod からダンプディレクトリーを削除します。

    $ cd ../; rm -rf /var/lib/mysql/data/mysqldumpdir

サポート対象の MySQL 環境変数

v2v3

OPENSHIFT_MYSQL_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_MYSQL_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_MYSQL_DB_USERNAME

MYSQL_USER

OPENSHIFT_MYSQL_DB_PASSWORD

MYSQL_PASSWORD

OPENSHIFT_MYSQL_DB_URL

 

OPENSHIFT_MYSQL_DB_LOG_DIR

 

OPENSHIFT_MYSQL_VERSION

 

OPENSHIFT_MYSQL_DIR

 

OPENSHIFT_MYSQL_DB_SOCKET

 

OPENSHIFT_MYSQL_IDENT

 

OPENSHIFT_MYSQL_AIO

MYSQL_AIO

OPENSHIFT_MYSQL_MAX_ALLOWED_PACKET

MYSQL_MAX_ALLOWED_PACKET

OPENSHIFT_MYSQL_TABLE_OPEN_CACHE

MYSQL_TABLE_OPEN_CACHE

OPENSHIFT_MYSQL_SORT_BUFFER_SIZE

MYSQL_SORT_BUFFER_SIZE

OPENSHIFT_MYSQL_LOWER_CASE_TABLE_NAMES

MYSQL_LOWER_CASE_TABLE_NAMES

OPENSHIFT_MYSQL_MAX_CONNECTIONS

MYSQL_MAX_CONNECTIONS

OPENSHIFT_MYSQL_FT_MIN_WORD_LEN

MYSQL_FT_MIN_WORD_LEN

OPENSHIFT_MYSQL_FT_MAX_WORD_LEN

MYSQL_FT_MAX_WORD_LEN

OPENSHIFT_MYSQL_DEFAULT_STORAGE_ENGINE

 

OPENSHIFT_MYSQL_TIMEZONE

 
 

MYSQL_DATABASE

 

MYSQL_ROOT_PASSWORD

 

MYSQL_MASTER_USER

 

MYSQL_MASTER_PASSWORD

6.2.4. PostgreSQL

  1. ギアから v2 PostgreSQL データベースをバックアップします。

    $ rhc ssh -a <v2-application_name>
    $ mkdir ~/app-root/data/tmp
    $ pg_dump <database_name> | gzip > ~/app-root/data/tmp/<database_name>.gz
  2. ローカルマシンに、バックアップファイルを展開します。

    $ rhc scp -a <v2_application_name> download <local_dest> app-root/data/tmp/<db-name>.gz
    $ gzip -d <database-name>.gz
    注記

    手順 4 とは別のフォルダーにバックアップファイルを保存します。

  3. 新規サービスを作成するための v2 アプリケーションのデータベース名、ユーザー名、パスワードを使用して PostgreSQL サービスを作成します。

    $ oc new-app postgresql-persistent -p POSTGRESQL_DATABASE=dbname -p
    POSTGRESQL_PASSWORD=password -p POSTGRESQL_USER=username
  4. Pod の使用準備ができているかどうかを確認します。

    $ oc get pods
  5. Pod を実行中に、バックアップディレクトリーを Pod に同期します。

    $ oc rsync /local/path/to/dir <postgresql_pod_name>:/var/lib/pgsql/data
  6. Pod にリモートからアクセスします。

    $ oc rsh <pod_name>
  7. データベースを復元します。

    psql dbname < /var/lib/pgsql/data/<database_backup_file>
  8. 必要のなくなったバックアップファイルをすべて削除します。

    $ rm /var/lib/pgsql/data/<database-backup-file>

サポート対象の PostgreSQL 環境変数

v2v3

OPENSHIFT_POSTGRESQL_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_POSTGRESQL_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_POSTGRESQL_DB_USERNAME

POSTGRESQL_USER

OPENSHIFT_POSTGRESQL_DB_PASSWORD

POSTGRESQL_PASSWORD

OPENSHIFT_POSTGRESQL_DB_LOG_DIR

 

OPENSHIFT_POSTGRESQL_DB_PID

 

OPENSHIFT_POSTGRESQL_DB_SOCKET_DIR

 

OPENSHIFT_POSTGRESQL_DB_URL

 

OPENSHIFT_POSTGRESQL_VERSION

 

OPENSHIFT_POSTGRESQL_SHARED_BUFFERS

 

OPENSHIFT_POSTGRESQL_MAX_CONNECTIONS

 

OPENSHIFT_POSTGRESQL_MAX_PREPARED_TRANSACTIONS

 

OPENSHIFT_POSTGRESQL_DATESTYLE

 

OPENSHIFT_POSTGRESQL_LOCALE

 

OPENSHIFT_POSTGRESQL_CONFIG

 

OPENSHIFT_POSTGRESQL_SSL_ENABLED

 
 

POSTGRESQL_DATABASE

 

POSTGRESQL_ADMIN_PASSWORD

6.2.5. MongoDB

注記
  • OpenShift v3 の場合: MongoDB シェルバージョン 3.2.6
  • OpenShift v2 の場合: MongoDB シェルバージョン 2.4.9
  1. ssh コマンドを使用して、v2 アプリケーションにリモートからアクセスします。

    $ rhc ssh <v2_application_name>
  2. -d <database_name> -c <collections> で単一のデータベースを指定して、mongodump を実行します。このオプションがないと、データベースはすべてダンプされます。各データベースは、独自のディレクトリーにダンプされます。

    $ mongodump -h $OPENSHIFT_MONGODB_DB_HOST -o app-root/repo/mydbdump -u 'admin' -p $OPENSHIFT_MONGODB_DB_PASSWORD
    $ cd app-root/repo/mydbdump/<database_name>; tar -cvzf dbname.tar.gz
    $ exit
  3. dbdumpmongodump ディレクトリーのローカルマシンにダウンロードします。

    $ mkdir mongodump
    $ rhc scp -a <v2 appname> download mongodump \
      app-root/repo/mydbdump/<dbname>/dbname.tar.gz
  4. v3 で MongoDB Pod を実行します。最新のイメージ (3.2.6) には mongo-tools が含まれないので、mongorestore または mongoimport コマンドを使用するには、デフォルトのmongodb-persistent テンプレートを編集して、mongo-tools, “mongodb:2.4” を含むイメージタグを指定します。このため、以下の oc export コマンドを使用して、編集することが必要です。

    $ oc export template mongodb-persistent -n openshift -o json > mongodb-24persistent.json

    mongodb-24persistent.json の L80 を編集します。mongodb:latestmongodb:2.4 に置き換えてください。

    $ oc new-app --template=mongodb-persistent -n <project-name-that-template-was-created-in> \
      MONGODB_USER=user_from_v2_app -p \
      MONGODB_PASSWORD=password_from_v2_db -p \
      MONGODB_DATABASE=v2_dbname -p \
      MONGODB_ADMIN_PASSWORD=password_from_v2_db
    $ oc get pods
  5. mongodb Pod の実行中に、データベースのアーカイブファイルを v3 MongoDB Pod にコピーします。

    $ oc rsync local/path/to/mongodump <mongodb_pod_name>:/var/lib/mongodb/data
    $ oc rsh <mongodb_pod>
  6. MongoDB Pod で、復元する各データベースについて以下を実行します。

    $ cd /var/lib/mongodb/data/mongodump
    $ tar -xzvf dbname.tar.gz
    $ mongorestore -u $MONGODB_USER -p $MONGODB_PASSWORD -d dbname -v /var/lib/mongodb/data/mongodump
  7. データベースが復元されたかどうかを確認します。

    $ mongo admin -u $MONGODB_USER -p $MONGODB_ADMIN_PASSWORD
    $ use dbname
    $ show collections
    $ exit
  8. Pod から mongodump ディレクトリーを削除します。

    $ rm -rf /var/lib/mongodb/data/mongodump

サポート対象の MongoDB 環境変数

v2v3

OPENSHIFT_MONGODB_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_MONGODB_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_MONGODB_DB_USERNAME

MONGODB_USER

OPENSHIFT_MONGODB_DB_PASSWORD

MONGODB_PASSWORD

OPENSHIFT_MONGODB_DB_URL

 

OPENSHIFT_MONGODB_DB_LOG_DIR

 
 

MONGODB_DATABASE

 

MONGODB_ADMIN_PASSWORD

 

MONGODB_NOPREALLOC

 

MONGODB_SMALLFILES

 

MONGODB_QUIET

 

MONGODB_REPLICA_NAME

 

MONGODB_KEYFILE_VALUE

6.3. Web フレームワークアプリケーションの移行

6.3.1. 概要

以下のトピックでは、Python、Ruby、PHP、Perl、Node.js、WordPress、Ghost、JBoss EAP、JBoss WS (Tomcat) および Wildfly 10 (JBoss AS) の Web フレームワークアプリケーションを OpenShift version 2 (v2) から OpenShift version 3 (v3) に移行する方法を確認します。

6.3.2. Python

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>.git
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. setup.pywsgi.pyrequirements.txt および etc などの重要なファイルがすべて新規リポジトリーにプッシュされていることを確認します。

    • アプリケーションに必要なパッケージがすべて requirements.txt に含まれていることを確認します。
  4. oc コマンドを使用して、ビルダーイメージとソースコードから新規の Python アプリケーションを起動します。

    $ oc new-app --strategy=source
    python:3.3~https://github.com/<github-id>/<repo-name> --name=<app-name> -e
    <ENV_VAR_NAME>=<env_var_value>

サポート対象の Python バージョン

v2v3

Python: 2.6、2.7、3.3

サポート対象のコンテナーイメージ

Django

Django-psql-example (quickstart)

6.3.3. Ruby

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>.git
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. Gemfile がなく、単純な rack アプリケーションを実行している場合には、この Gemfile ファイルをソースの root にコピーします。

    https://github.com/sclorg/ruby-ex/blob/master/Gemfile
    注記

    Ruby 2.0 がサポートする rack gem の最新バージョンは 1.6.4 であるため、Gemfile は gem 'rack', “1.6.4” に変更する必要があります。

    Ruby 2.2 以降の場合は、rack gem 2.0 以降を使用してください。

  4. oc コマンドを使用して、ビルダーイメージとソースコードから新規の Ruby アプリケーションを起動します。

    $ oc new-app --strategy=source
    ruby:2.0~https://github.com/<github-id>/<repo-name>.git

サポート対象の Ruby バージョン

v2v3

Ruby: 1.8、1.9、2.0

サポート対象のコンテナーイメージ

Ruby on Rails: 3、4

Rails-postgresql-example (quickstart)

Sinatra

 

6.3.4. PHP

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. oc コマンドを使用して、ビルダーイメージとソースコードから新規の PHP アプリケーションを起動します。

    $ oc new-app https://github.com/<github-id>/<repo-name>.git
    --name=<app-name> -e <ENV_VAR_NAME>=<env_var_value>

サポート対象の PHP バージョン

v2v3

PHP: 5.3、5.4

サポート対象のコンテナーイメージ

PHP 5.4 with Zend Server 6.1

 

CodeIgniter 2

 

HHVM

 

Laravel 5.0

 
 

cakephp-mysql-example (quickstart)

6.3.5. Perl

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. ローカルの Git リポジトリーを編集して、変更をアップストリームにプッシュして、v3 との互換性を確保します。

    1. v2 では、CPAN モジュールは .openshift/cpan.txt にあり、v3 では s2i ビルダーは、ソースの root ディレクトリーで cpanfile という名前のファイルを検索します。

      $ cd <local-git-repository>
      $ mv .openshift/cpan.txt cpanfile

      cpanfile の形式が若干異なるので、これを編集します。

      cpanfile の形式cpan.txt の形式

      requires ‘cpan::mod’;

      cpan::mod

      requires ‘Dancer’;

      Dancer

      requires ‘YAML’;

      YAML

    2. .openshift ディレクトリーを削除します。

      注記

      v3 では、action_hooks および cron タスクは同じようにサポートされません。詳細情報は、「アクションフック」を参照してください。

  4. oc コマンドを使用して、ビルダーイメージとソースコードから新規の Perl アプリケーションを起動します。
$ oc new-app https://github.com/<github-id>/<repo-name>.git

サポート対象の Perl バージョン

v2v3

Perl: 5.10

サポート対象のコンテナーイメージ

 

Dancer-mysql-example (quickstart)

6.3.6. Node.js

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. ローカルの Git リポジトリーを編集して、変更をアップストリームにプッシュして、v3 との互換性を確保します。

    1. .openshift ディレクトリーを削除します。

      注記

      v3 では、action_hooks および cron タスクは同じようにサポートされません。詳細情報は、「アクションフック」を参照してください。

    2. server.js を編集します。

      • L116 server.js: 'self.app = express();'
      • L25 server.js: self.ipaddress = '0.0.0.0';
      • L26 server.js: self.port = 8080;

        注記

        Lines(L) は V2 カートリッジの server.js から取得されます。

  4. oc コマンドを使用して、ビルダーイメージとソースコードから新規の Node.js アプリケーションを起動します。

    $ oc new-app https://github.com/<github-id>/<repo-name>.git
    --name=<app-name> -e <ENV_VAR_NAME>=<env_var_value>

サポート対象の Node.js バージョン

v2v3

Node.js 0.10

サポート対象のコンテナーイメージ

 

Nodejs-mongodb-example。このクイックスタートテンプレートは Node.js バージョン 6 のみをサポートします。

6.3.7. WordPress

重要

現時点で WordPress アプリケーションの移行はコミュニティーによるサポートのみで、Red hat のサポートはありません。

WordPress アプリケーションの OpenShift Container Platform v3 への移行に関する情報は、「OpenShift ブログ」を参照してください。

6.3.8. Ghost

重要

現時点で Ghost アプリケーションの移行はコミュニティーによるサポートのみで、Red hat のサポートはありません。

Ghost アプリケーションの OpenShift Container Platform v3 への移行に関する情報は、「OpenShift ブログ」を参照してください。

6.3.9. JBoss EAP

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. リポジトリーに事前にビルドされた .war ファイルが含まれている場合には、それらをリポジトリーの root ディレクトリー内の deployments ディレクトリーに置く必要があります。
  4. JBoss EAP 7 ビルダーイメージ (jboss-eap70-openshift) と GitHub からのソースコードリポジトリーを使用して新規アプリケーションを作成します。

    $ oc new-app --strategy=source jboss-eap70-openshift:1.6~https://github.com/<github-id>/<repo-name>.git

6.3.10. JBoss WS (Tomcat)

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. リポジトリーに事前にビルドされた .war ファイルが含まれている場合には、それらをリポジトリーの root ディレクトリー内の deployments ディレクトリーに置く必要があります。
  4. JBoss Web Server 3 (Tomcat 7) ビルダーイメージ (jboss-webserver30-tomcat7) と GitHub からのソースコードリポジトリーを使用して新規アプリケーションを作成します。

    $ oc new-app --strategy=source
    jboss-webserver30-tomcat7-openshift~https://github.com/<github-id>/<repo-name>.git
    --name=<app-name> -e <ENV_VAR_NAME>=<env_var_value>

6.3.11. JBoss AS (Wildfly 10)

  1. 新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. ローカルの v2 ソースコードを新規リポジトリーにプッシュします。

    $ git push -u <remote-name> master
  3. ローカルの Git リポジトリーを編集して、変更をアップストリームにプッシュして v3 との互換性を確保します。

    1. .openshift ディレクトリーを削除します。

      注記

      v3 では、action_hooks および cron タスクは同じようにサポートされません。詳細情報は、「アクションフック」を参照してください。

    2. deployments ディレクトリーをソースリポジトリーの root に追加します。.war ファイルをこの「deployments」ディレクトリーに移動します。
  4. oc コマンドを使用して、ビルダーイメージとソースコードから新規の Wildfly アプリケーションを起動します。

    $ oc new-app https://github.com/<github-id>/<repo-name>.git
     --image-stream=”openshift/wildfly:10.0" --name=<app-name> -e
     <ENV_VAR_NAME>=<env_var_value>
    注記

    引数 --name はアプリケーション名を指定するためのオプションの引数です。また、-eOPENSHIFT_PYTHON_DIR などのビルドやデプロイメントプロセスに必要な環境変数を追加するためのオプションの引数です。

6.3.12. サポート対象の JBoss バージョン

v2v3

JBoss App Server 7

 

Tomcat 6 (JBoss EWS 1.0)

サポート対象のコンテナーイメージ

Tomcat 7 (JBoss EWS 2.0)

サポート対象のコンテナーイメージ

Vert.x 2.1

 

WildFly App Server 10

 

WildFly App Server 8.2.1.Final

 

WildFly App Server 9

 

CapeDwarf

 

JBoss Data Virtualization 6

サポート対象のコンテナーイメージ

JBoss Enterprise App Platform (EAP) 6

サポート対象のコンテナーイメージ

JBoss Unified Push Server 1.0.0.Beta1、Beta2

 

JBoss BPM Suite

サポート対象のコンテナーイメージ

JBoss BRMS

サポート対象のコンテナーイメージ

 

jboss-eap70-openshift: 1.3-Beta

 

eap64-https-s2i

 

eap64-mongodb-persistent-s2i

 

eap64-mysql-persistent-s2i

 

eap64-psql-persistent-s2i

6.4. クイックスタートの例

6.4.1. 概要

v2 クイックスタートから v3 クイックスタートへの明確な移行パスはありませんが、v3 では以下のクイックスタートを利用できます。データベースを含むアプリケーションがある場合には、oc new-app でアプリケーションを作成してから、もう一度 oc new-app を実行して別のデータベースサービスを起動し、これら 2 つを共通の環境変数を使用してリンクするのではなく、以下のいずれかを使用し、ソースコードを含む GitHub リポジトリーからリンクしたアプリケーションとデータベースを一度にインスタンス化できます。oc get templates -n openshift で利用可能なテンプレートをすべて表示することができます。

6.4.2. ワークフロー

上記のテンプレート URL のいずれかに対して git clone をローカルで実行します。アプリケーションのソースコードを追加し、コミットし、GitHub リポジトリーにプッシュしてから、上記のテンプレートのいずれかで v3 クイックスタート アプリケーションを起動します。

  1. アプリケーション用の GitHub リポジトリーを作成します。
  2. クイックスタートテンプレートのクローンを作成して、GitHub リポジトリーをリモートとして追加します。

    $ git clone <one-of-the-template-URLs-listed-above>
    $ cd <your local git repository>
    $ git remote add upstream <https://github.com/<git-id>/<quickstart-repo>.git>
    $ git push -u upstream master
  3. ソースコードを GitHub にコミットし、プッシュします。

    $ cd <your local repository>
    $ git commit -am “added code for my app”
    $ git push origin master
  4. v3 で新規アプリケーションを作成します。

    $ oc new-app --template=<template> \
    -p SOURCE_REPOSITORY_URL=<https://github.com/<git-id>/<quickstart_repo>.git> \
    -p DATABASE_USER=<your_db_user> \
    -p DATABASE_NAME=<your_db_name> \
    -p DATABASE_PASSWORD=<your_db_password> \
    -p DATABASE_ADMIN_PASSWORD=<your_db_admin_password> 1
    1
    MongoDB にのみ該当します。

    web フレームワーク Pod とデータベース Pod の 2 つの Pod が実行され、web フレームワーク Pod 環境は、データベース Pod 環境と一致しているはずです。oc set env pod/<pod_name> --list を使用して、環境変数を表示できます。

    • DATABASE_NAME<DB_SERVICE>_DATABASE になります。
    • DATABASE_USER<DB_SERVICE>_USER になります。
    • DATABASE_PASSWORD<DB_SERVICE>_PASSWORD になります。
    • DATABASE_ADMIN_PASSWORDMONGODB_ADMIN_PASSWORD になります (MongoDB のみに該当します)。

      SOURCE_REPOSITORY_URL が指定されていない場合、テンプレートはソースリポジトリーとして上記のテンプレート URL (https://github.com/openshift/<quickstart>-ex) を使用して、hello-welcome アプリケーションが起動します。

  5. データベースを移行する場合は、データベースをダンプファイルにエクスポートして、新しい v3 データベース Pod にデータベースを復元します。「データベースアプリケーション」に記載の手順を参照してください。ただし、データベース Pod はすでに実行中であるため、oc new-app の手順は省略してください。

6.5. 継続的インテグレーションまたは継続的デプロイ (CI/CD)

6.5.1. 概要

以下のトピックでは、OpenShift バージョン 2 (v2) と OpenShift バージョン 3 (v3) 間の継続的インテグレーションおよびデプロイメント (CI/CD) アプリケーションの相違点と、これらのアプリケーションを v3 環境に移行する方法を確認します。

6.5.2. Jenkins

Jenkins アプリケーションは、アーキテクチャーの根本的な違いにより OpenShift バージョン 2 (v2) と OpenShift バージョン 3 (v3) では異なる方法で設定されます。たとえば、v2 ではアプリケーションはギアでホストされる統合型の Git リポジトリーを使用してソースコードを保存します。v3 では、ソースコードは Pod の外部でホストされるパブリックまたはプライベート Git リポジトリーに置かれます。

さらに OpenShift v3 では、Jenkins ジョブは、ソースコードの変更だけでなく、ソースコードと共にアプリケーションをビルドするために使用されるイメージの変更である ImageStream の変更によってもトリガーされます。そのため、v3 で新しい Jenkins アプリケーションを作成してから、OpenShift v3 環境に適した設定でジョブを作成し直して Jenkins アプリケーションを手動で移行することを推奨します。

Jenkins アプリケーションの作成、ジョブの設定、Jenkins プラグインの正しい使用の方法に関する詳細は、以下のリソースを参照してください。

6.6. Webhook およびアクションフック

6.6.1. 概要

以下のトピックでは、OpenShift バージョン 2 (v2) と OpenShift バージョン 3 (v3) 間の webhook とアクションフックの相違点と、これらのアプリケーションの v3 環境への移行方法について説明します。

6.6.2. Webhook

  1. GitHub リポジトリーから BuildConfig を作成した後に、以下を実行します。

    $ oc describe bc/<name-of-your-BuildConfig>

    以下のように、上記のコマンドは webhook GitHub URL を出力します。

    <https://api.starter-us-east-1.openshift.com:443/oapi/v1/namespaces/nsname/buildconfigs/bcname/webhooks/secret/github>.
  2. GitHub の Web コンソールから、この URL を GitHub にカットアンドペーストします。
  3. GitHub リポジトリーで、Settings → Webhooks & Services から Add Webhook を選択します。
  4. Payload URL フィールドに、(上記と同様の) URL の出力を貼り付けます。
  5. Content Typeapplication/json に設定します。
  6. Add webhook をクリックします。

webhook の設定が正常に完了したことを示す GitHub のメッセージが表示されます。

これで変更を GitHub リポジトリーにプッシュするたびに新しいビルドが自動的に起動し、ビルドに成功すると新しいデプロイメントが起動します。

注記

アプリケーションを削除または再作成する場合には、GitHub の Payload URL フィールドを BuildConfig webhook url で更新する必要があります。

6.6.3. アクションフック

OpenShift バージョン 2 (v2) では、.openshift/action_hooks ディレクトリーに build、deploy、post_deploy および pre_build スクリプトまたは action_hooks が置かれます。v3 にはこれらのスクリプトに対応する 1 対 1 の機能マッピングはありませんが、v3 の 「S2I ツール」には「カスタム可能なスクリプト」を指定の URL またはソースリポジトリーの .s2i/bin ディレクトリーに追加するオプションがあります。

OpenShift バージョン 3 (v3) には、イメージをビルドしてからレジストリーにプッシュするまでのイメージの基本的なテストを実行する「post-build hook」があります。「デプロイメントフック」はデプロイメント構成で設定されます。

v2 では、通常 action_hooks は環境変数を設定するために使用されます。v2 では、環境変数は以下のように渡される必要があります。

$ oc new-app <source-url> -e ENV_VAR=env_var

または以下を実行します。

$ oc new-app <template-name> -p ENV_VAR=env_var

または、以下を使用して環境変数を追加し、変更することができます。

$ oc set env dc/<name-of-dc>
ENV_VAR1=env_var1 ENV_VAR2=env_var2’

6.7. S2I ツール

6.7.1. 概要

「Source-to-Image (S2I) ツール」は、アプリケーションのソースコードをコンテナーイメージに挿入します。最終成果物として、ビルダーイメージとビルド済みのソースコードが組み込まれた実行準備のできたコンテナーイメージが新たに作成されます。S2I ツールは、OpenShift Container Platform がなくても、「リポジトリー」から、ローカルマシンにインストールできます。

S2I ツールは、OpenShift Container Platform で使用する前にアプリケーションとイメージをローカルでテストし、検証するための非常に強力なツールです。

6.7.2. コンテナーイメージの作成

  1. アプリケーションに必要なビルダーイメージを特定します。Red Hat は、「Python、Ruby、Perl、PHP および Node.js」など各種の言語のビルダーイメージを複数提供しています。他のイメージは コミュニティースペース から取得できます。
  2. S2I は、Git リポジトリーまたはローカルのファイルシステムのソースコードからイメージをビルドできます。ビルダーイメージおよびソースコードから新しいコンテナーイメージをビルドするには、以下を実行します。

    $ s2i build <source-location> <builder-image-name> <output-image-name>
    注記

    <source-location> には Git リポジトリーの URL、 またはローカルファイルシステムのソースコードのディレクトリーのいずれかを指定できます。

  3. Docker デーモンでビルドしたイメージをテストします。

    $ docker run -d --name <new-name> -p <port-number>:<port-number> <output-image-name>
    $ curl localhost:<port-number>
  4. 新しいイメージを「OpenShift レジストリー」にプッシュします。
  5. oc コマンドを使用して、OpenShift レジストリーのイメージから新規アプリケーションを作成します。

    $ oc new-app <image-name>

6.8. サポートガイド

6.8.1. 概要

以下のトピックでは、OpenShift バージョン 2 (v2) および OpenShift バージョン 3 (v3) でサポート対象の言語、フレームワーク、データベース、マーカーについて説明します。

OpenShift Container Platform のお客様が使用する一般的な組み合わせに関する情報は、「OpenShift Container Platform tested integrations」を参照してください。

6.8.2. サポートされているデータベース

データベースアプリケーションのトピックの「サポート対象のデータベース」セクションを参照してください。

6.8.3. サポート言語

6.8.4. サポート対象のフレームワーク

表6.1 サポート対象のフレームワーク

v2v3

Jenkins サーバー

jenkins-persistent

Drupal 7

 

Ghost 0.7.5

 

WordPress 4

 

Ceylon

 

Go

 

MEAN

 

6.8.5. サポート対象のマーカー

表6.2 Python

v2v3

pip_install

リポジトリーに requirements.txt が含まれる場合には、デフォルトで pip が呼び出されます。含まれていない場合に pip は使用されません。

表6.3 Ruby

v2v3

disable_asset_compilation

これは、buildconfig ストラテジー定義で DISABLE_ASSET_COMPILATION 環境変数を true に設定すると使用できます。

表6.4 Perl

v2v3

enable_cpan_tests

これは、「ビルド設定」ENABLE_CPAN_TEST 環境変数を true に設定すると使用できます。

表6.5 PHP

v2v3

use_composer

ソースリポジトリーの root ディレクトリーに composer.json が含まれる場合に、コンポーザーが常に使用されます。

表6.6 Node.js

v2v3

NODEJS_VERSION

該当なし

use_npm

アプリケーションの起動には、DEV_MODEtrue に設定されていない限り npm が常に使用されます。true に設定されていない場合には nodemon が使用されます。

表6.7 JBoss EAP、JBoss WS、WildFly

v2v3

enable_debugging

このオプションは、デプロイメント設定で設定される ENABLE_JPDA 環境変数に値を設定することで制御します。

skip_maven_build

pom.xml がある場合には、maven が実行されます。

java7

該当なし

java8

JavaEE は JDK8 を使用します。

表6.8 Jenkins

v2v3

enable_debugging

該当なし

表6.9 all

v2v3

force_clean_build

v3 には同様の概念が使われています。buildconfignoCache フィールドにより、コンテナービルドによる各層の再実行が強制的に実行されます。S2I ビルドでは、clean build を示す incremental フラグはデフォルトで false になっています。

hot_deploy

RubyPythonPerlPHPNode.js

enable_public_server_status

該当なし

disable_auto_scaling

自動スケーリングはデフォルトではオフになっていますが、「Pod auto-scaling」でオンにすることができます。

6.8.6. サポート対象の環境変数

第7章 チュートリアル

7.1. 概要

以下のトピックでは、OpenShift Container Platform でアプリケーションを稼働させる方法や、さまざまな言語とフレームワークについて説明します。

7.2. クイックスタートのテンプレート

7.2.1. 概要

クイックスタートは、OpenShift Container Platform で実行するアプリケーションの基本例です。クイックスタートはさまざまな言語やフレームワークが含まれており、サービスのセット、ビルド設定およびデプロイメント設定などで構成される「テンプレート」で定義されています。このテンプレートは、必要なイメージやソースリポジトリーを参照して、アプリケーションをビルドし、デプロイします。

クイックスタートを試してみるには、テンプレートからアプリケーションを作成します。管理者がすでにこれらのテンプレートを OpenShift Container Platform クラスターにインストールしている可能性がありますが、その場合には、Web コンソールからこれを簡単に選択できます。テンプレートのアップロード、作成、変更に関する情報は、「テンプレート」のドキュメントを参照してください。

クイックスタートは、アプリケーションのソースコードを含むソースリポジトリーを参照します。クイックスタートをカスタマイズするには、リポジトリーをフォークし、テンプレートからアプリケーションを作成する時に、デフォルトのソースリポジトリー名をフォークしたリポジトリーに置き換えます。これにより、提供されたサンプルのソースではなく、独自のソースコードを使用してビルドが実行されます。ソースリポジトリーでコードを更新し、新しいビルドを起動して、デプロイされたアプリケーションで変更が反映されていることを確認できます。

7.2.2. Web フレームワーククイックスタートのテンプレート

以下のクイックスタートでは、指定のフレームワークおよび言語の基本アプリケーションを提供します。

7.3. Ruby on Rails

7.3.1. 概要

Ruby on Rails は Ruby で記述された一般的な Web フレームワークです。本ガイドでは、OpenShift Container Platform での Rails 4 の使用について説明します。

警告

チュートリアル全体をチェックして、OpenShift Container Platform でアプリケーションを実行するために必要なすべての手順を概観することを強く推奨します。問題に直面した場合には、チュートリアル全体を振り返り、もう一度問題に対応してください。またチュートリアルは、実行済みの手順を確認し、すべての手順が適切に実行されていることを確認するのに役立ちます。

本ガイドでは、以下があることを前提としています。

  • Ruby/Rails の基本知識
  • Ruby 2.0.0+、Rubygems、Bundler のローカルにインストールされたバージョン
  • Git の基本知識
  • OpenShift Container Platform v3 の実行インスタンス

7.3.2. ローカルのワークステーション設定

まず、OpenShift Container Platform のインスタンスが実行されており、利用できることを確認します。OpenShift Container Platform を稼働させる方法については、「インストール方法」を確認してください。また、oc CLI クライアントのインストール」が実行されており、コマンドがお使いのコマンドシェルから利用できることを確認し、CLI クライアントからメールとパスワードを使用して、「ログイン」できるようにします。

7.3.2.1. データベースの設定

Rails アプリケーションはほぼ常にデータベースと併用されます。ローカル開発の場合は、PostgreSQL データベースを選択してください。PostgreSQL データベースをインストール方法するには、以下を入力します。

$ sudo yum install -y postgresql postgresql-server postgresql-devel

次に、以下のコマンドでデータベースを初期化する必要があります。

$ sudo postgresql-setup initdb

このコマンドで /var/lib/pgsql/data ディレクトリーが作成され、このディレクトリーにデータが保存されます。

以下を入力してデータベースを起動します。

$ sudo systemctl start postgresql.service

データベースが実行されたら、rails ユーザーを作成します。

$ sudo -u postgres createuser -s rails

作成をしたユーザーのパスワードは作成されていない点に留意してください。

7.3.3. アプリケーションの作成

Rails アプリケーションをゼロからビルドするには、Rails gem を先にインストールする必要があります。

$ gem install rails
Successfully installed rails-4.2.0
1 gem installed

Rails gem のインストール後に、PostgreSQL をデータベースとして 指定して新規アプリケーションを作成します。

$ rails new rails-app --database=postgresql

次に、新規ディレクトリーに移動します。

$ cd rails-app

アプリケーションがすでにある場合には pg (postgresql) gem が Gemfile に配置されているはずです。配置されていない場合には、Gemfile を編集して gem を追加します。

gem 'pg'

すべての依存関係を含む Gemfile.lock を新たに生成するには、以下を実行します。

$ bundle install

pg gem で postgresql データベースを使用することのほかに、config/database.ymlpostgresql アダプターを使用していることを確認する必要があります。

config/database.yml ファイルの default セクションを以下のように更新するようにしてください。

default: &default
  adapter: postgresql
  encoding: unicode
  pool: 5
  host: localhost
  username: rails
  password:

アプリケーションの開発およびテストデータベースを作成するには、以下の rake コマンドを使用します。

$ rake db:create

これで PostgreSQL サーバーに development および test データベースが作成されます。

7.3.3.1. Welcome ページの作成

Rails 4 では、静的な public/index.html ページが実稼働環境で提供されなくなったので、新たに root ページを作成する必要があります。

welcome ページをカスタマイズするには、以下の手順を実行する必要があります。

  • index アクションで コントローラー を作成します。
  • welcome コントローラー index アクションの ビュー ページを作成します。
  • 作成した コントローラービュー と共にアプリケーションの root ページを提供する ルート を作成します。

Rails には、これらの必要な手順をすべて実行するジェネレーターがあります。

$ rails generate controller welcome index

必要なファイルはすべて作成されたので、config/routes.rb ファイルの 2 行目を以下のように編集することのみが必要になります。

root 'welcome#index'

rails server を実行して、ページが利用できることを確認します。

$ rails server

ブラウザーで http://localhost:3000 に移動してページを表示してください。このページが表示されない場合は、サーバーに出力されるログを確認してデバッグを行ってください。

7.3.3.2. OpenShift Container Platform のアプリケーションの設定

アプリケーションと OpenShift Container Platform で実行されている PostgreSQL データベースサービスとを通信させるには、「環境変数」を使用するように config/database.ymldefault セクションを編集する必要があります。環境変数は、後でデータベースサービスを作成する時に定義します。

編集した config/database.ymldefault セクションに事前定義済みの変数を入力すると、以下のようになります。

<% user = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? "root" : ENV["POSTGRESQL_USER"] %>
<% password = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? ENV["POSTGRESQL_ADMIN_PASSWORD"] : ENV["POSTGRESQL_PASSWORD"] %>
<% db_service = ENV.fetch("DATABASE_SERVICE_NAME","").upcase %>

default: &default
  adapter: postgresql
  encoding: unicode
  # For details on connection pooling, see rails configuration guide
  # http://guides.rubyonrails.org/configuring.html#database-pooling
  pool: <%= ENV["POSTGRESQL_MAX_CONNECTIONS"] || 5 %>
  username: <%= user %>
  password: <%= password %>
  host: <%= ENV["#{db_service}_SERVICE_HOST"] %>
  port: <%= ENV["#{db_service}_SERVICE_PORT"] %>
  database: <%= ENV["POSTGRESQL_DATABASE"] %>

最終的なファイルの内容のサンプルについては、「Ruby on Rails アプリケーションの例 config/database.yml」を参照してください。

7.3.3.3. git へのアプリケーションの保存

OpenShift Container Platform には git が必要なので、まだインストールされていない場合はインストールする必要があります。

OpenShift Container Platform でアプリケーションをビルドするには通常、ソースコードを git リポジトリーに保存する必要があるため、git がない場合にはインストールしてください。

ls -1 コマンドを実行して、Rails アプリケーションのディレクトリーで操作を行っていることを確認します。コマンドの出力は以下のようになります。

$ ls -1
app
bin
config
config.ru
db
Gemfile
Gemfile.lock
lib
log
public
Rakefile
README.rdoc
test
tmp
vendor

Rails app ディレクトリーでこれらのコマンドを実行して、コードを初期化して、git にコミットします。

$ git init
$ git add .
$ git commit -m "initial commit"

アプリケーションをコミットしたら、リモートのリポジトリーにプッシュする必要があります。これには、GitHub アカウント が必要です。このアカウントで 新しいリポジトリーを作成します

お使いの git リポジトリーを参照するリモートを設定します。

$ git remote add origin git@github.com:<namespace/repository-name>.git

次に、アプリケーションをリモートの git リポジトリーにプッシュします。

$ git push

7.3.4. OpenShift Container Platform へのアプリケーションのデプロイ

Ruby on Rails アプリケーションをデプロイするには、アプリケーション用に新規の プロジェクト を作成します。

$ oc new-project rails-app --description="My Rails application" --display-name="Rails Application"

rails-app プロジェクト」を作成すると、自動的に新しいプロジェクトの namespace に切り替えられます。

OpenShift Container Platform へのアプリケーションのデプロイでは 3 つの手順を実行します。

7.3.4.1. データベースサービスの作成

Rails アプリケーションには、稼働中のデータベース「サービス」が必要です。このサービスには PostgeSQL データベース 「イメージ」を使用してください。

データベース「サービス」を作成するには、oc new-app コマンドを使用します。このコマンドでは必要な「環境変数」を指定する必要があります。この環境変数は、データベースコンテナー内で使用します。このような「環境変数」では、ユーザー名、パスワード、データベース名を設定する必要があります。これらの 「環境変数」は任意の値に変更することが可能です。今回設定する変数は以下のとおりです。

  • POSTGRESQL_DATABASE
  • POSTGRESQL_USER
  • POSTGRESQL_PASSWORD

これらの変数を設定すると、以下を確認できます。

  • 指定の名前でデータベースが存在する
  • 指定の名前でユーザーが存在する
  • ユーザーは指定のパスワードで指定のデータベースにアクセスできる

以下に例を示します。

$ oc new-app postgresql -e POSTGRESQL_DATABASE=db_name -e POSTGRESQL_USER=username -e POSTGRESQL_PASSWORD=password

データベースの管理者のパスワードも設定するには、直前のコマンドに以下を追加します。

-e POSTGRESQL_ADMIN_PASSWORD=admin_pw

このコマンドの進捗を確認するには、以下を実行します。

$ oc get pods --watch

7.3.4.2. フロントエンドサービスの作成

アプリケーションを OpenShift Container Platform にデプロイするには、「oc new-app」コマンドをもう一度使用して、アプリケーションを配置するリポジトリーを指定する必要があります。このコマンドでは、「データベースサービスの作成」で設定したデータベース関連の「環境変数」を指定してください。

$ oc new-app path/to/source/code --name=rails-app -e POSTGRESQL_USER=username -e POSTGRESQL_PASSWORD=password -e POSTGRESQL_DATABASE=db_name -e DATABASE_SERVICE_NAME=postgresql

このコマンドでは、OpenShift Container Platform は、ソースコードの取得、ビルダーイメージの設定、アプリケーションイメージの「ビルド」、新規作成したイメージと指定の「環境変数」のデプロイを行います。このアプリケーションは rails-app という名前に指定します。

rails-app「DeploymentConfig」の JSON ドキュメントを参照して、環境変数が追加されたかどうかを確認できます。

$ oc get dc rails-app -o json

以下のセクションが表示されるはずです。

env": [
    {
        "name": "POSTGRESQL_USER",
        "value": "username"
    },
    {
        "name": "POSTGRESQL_PASSWORD",
        "value": "password"
    },
    {
        "name": "POSTGRESQL_DATABASE",
        "value": "db_name"
    },
    {
        "name": "DATABASE_SERVICE_NAME",
        "value": "postgresql"
    }

],

ビルドプロセスを確認するには、以下を実行します。

$ oc logs -f build rails-app-1

ビルドが完了すると、OpenShift Container Platform で Pod が実行されていることを確認できます。

$ oc get pods

myapp-<number>-<hash> で始まる行が表示されますが、これは OpenShift Container Platform で実行中のアプリケーションです。

データベースの移行スクリプトを実行してデータベースを初期化してからでないと、アプリケーションは機能しません。これを実行する 2 種類の方法があります。

  • 実行中のフロントエンドコンテナーから手動で行う

最初に「rsh」コマンドでフロントエンドコンテナーに対して実行します。

$ oc rsh <FRONTEND_POD_ID>

コンテナー内から移行を実行します。

$ RAILS_ENV=production bundle exec rake db:migrate

development または test 環境で Rails アプリケーションを実行する場合には、RAILS_ENV の環境変数を指定する必要はありません。

7.3.4.3. アプリケーションのルートの作成

www.example.com などの外部からアクセスできるホスト名を指定してサービスを公開するには、OpenShift Container Platform のルートを使用します。この場合は、以下を入力してフロントエンドサービスを公開する必要があります。

$ oc expose service rails-app --hostname=www.example.com
警告

ユーザーは指定したホスト名がルーターの IP アドレスに解決することを確認する必要があります。詳しい情報は、以下に関する OpenShift Container Platform ドキュメントを参照してください。

7.4. Maven 用の Nexus ミラーリングの設定

7.4.1. はじめに

Java および Maven でアプリケーションを開発すると、ビルドを複数回実行する可能性が非常に高くなります。Pod のビルド時間を短縮するために、Maven の依存関係をローカルの Nexus リポジトリーにキャッシュすることができます。このチュートリアルでは、クラスター上に Nexus リポジトリーを作成する方法を説明します。

このチュートリアルでは、ご利用のプロジェクトが Maven で使用できるように設定されていることを前提としています。Java プロジェクトで Maven を使用する場合は、Maven のガイド を参照することを強く推奨します。

また、アプリケーションのイメージに Maven ミラーリング機能があるか確認するようにしてください。Maven を使用するイメージの多くに MAVEN_MIRROR_URL 環境変数が含まれており、このプロセスを単純化するために使用できます。この機能が含まれていない場合には、Nexus ドキュメント を参照して、ビルドが正しく設定されていることを確認してください。

さらに、各 Pod が機能するように十分なリソースを割り当てるようにしてください。追加のリソースを要求するには、Nexus デプロイメント設定で「Pod テンプレートを編集」する必要がある場合があります。

7.4.2. Nexus の設定

  1. 正式な Nexus コンテナーイメージをダウンロードし、デプロイします。

    oc new-app sonatype/nexus
  2. 新規作成した Nexus サービスを公開して、ルートを作成します。

    oc expose svc/nexus
  3. oc get routes を使用して、Pod の新規外部アドレスを検索します。

    oc get routes

    出力は以下のようになります。

    NAME      HOST/PORT                              PATH      SERVICES   PORT       TERMINATION
    nexus     nexus-myproject.192.168.1.173.xip.io             nexus      8081-tcp
  4. ブラウザーで HOST/PORT の対象の URL に移動して、Nexus が実行されていることを確認します。Nexus にサインインするには、デフォルトの管理者ユーザー名 admin、パスワード admin123 を使用します。
注記

Nexus は中央リポジトリー用に事前に設定されていますが、アプリケーション用に他のリポジトリーが必要な場合があります。Red Hat イメージの多くは、Maven リポジトリーjboss-ga リポジトリーを追加 することを推奨します。

7.4.2.1. プローブを使用した正常な実行の確認

ここで readiness プローブと liveness プローブ を設定することができます。これらのプローブは、Nexus が正しく実行されていることを定期的に確認します。

$ oc set probe dc/nexus \
	--liveness \
	--failure-threshold 3 \
	--initial-delay-seconds 30 \
	-- echo ok
$ oc set probe dc/nexus \
	--readiness \
	--failure-threshold 3 \
	--initial-delay-seconds 30 \
	--get-url=http://:8081/nexus/content/groups/public

7.4.2.2. Nexus への永続性の追加

注記

永続ストレージを必要としない場合には、Nexus への接続 に進みます。ただし、Pod が何らかの理由で再起動された場合には、キャッシュされた依存関係および設定のカスタマイズはなくなります。

Nexus の Persistent Volume Claim (永続ボリューム要求、PVC) を作成し、サーバーを実行中の pod を中断すると、キャッシュされた依存関係が失われないようにします。PVC にはクラスター内で利用可能な永続ボリューム (PV) が必要です。利用可能な PV がない場合や、クラスターに管理者としてのアクセス権限がない場合には、システム管理者に、読み取り/書き込み可能な永続ボリュームを作成するように依頼してください。

永続ボリュームの作成手順については、「OpenShift Container Platform での永続ストレージ」を参照してください。

Nexus デプロイメント設定に PVC を追加します。

$ oc volumes dc/nexus --add \
	--name 'nexus-volume-1' \
	--type 'pvc' \
	--mount-path '/sonatype-work/' \
	--claim-name 'nexus-pv' \
	--claim-size '1G' \
	--overwrite

これで、デプロイメント設定の以前の emptyDir ボリュームが削除され、1 GB 永続ストレージを /sonatype-work (依存関係の保存先) にマウントする要求を追加します。この設定の変更により、Nexus Pod は自動的に再デプロイされます。

Nexus が実行していることを確認するには、ブラウザーで Nexus ページを更新します。以下を使用して、デプロイメントの進捗をモニタリングすることができます。

$ oc get pods -w

7.4.3. Nexus への接続

次の手順では、新しい Nexus リポジトリーを使用するビルドを定義する方法を説明します。残りのチュートリアルでは、このリポジトリーサンプル と、ビルダーとして wildfly-100-centos7を使用しますが、これらの変更はどのプロジェクトでも機能します。

ビルダーイメージサンプル では、環境の一部として MAVEN_MIRROR_URL をサポートするため、これを使用して、ビルダーイメージを Nexus リポジトリーにポイントすることができます。イメージが環境変数を使用した Mavin のミラーリングをサポートしていない場合には、Nexus ミラーリングを参照する正しい Maven 設定を指定するようにビルダーイメージを変更する必要がある場合があります。

$ oc new-build openshift/wildfly-100-centos7:latest~https://github.com/openshift/jee-ex.git \
	-e MAVEN_MIRROR_URL='http://nexus.<Nexus_Project>:8081/nexus/content/groups/public'
$ oc logs build/jee-ex-1 --follow

<Nexus_Project> は Nexus リポジトリーのプロジェクト名に置き換えます。これが使用するアプリケーションと同じプロジェクトに含まれる場合には、<Nexus_Project>. を削除できます。「OpenShift Container Platform の DNS 解決について参照してください」

7.4.4. 正常な実行の確認

web ブラウザーで、http://<NexusIP>:8081/nexus/content/groups/public に移動して、アプリケーションの依存関係を保存したことを確認します。また、ビルドログを確認して Maven が Nexus ミラーリングを使用しているかどうかをチェックできます。正常にミラーリングされている場合には、URL http://nexus:8081 を参照する出力が表示されるはずです。

7.4.5. その他のリソース

7.5. OpenShift Pipeline ビルド

7.5.1. はじめに

シンプルな web サイトを作成する場合も、複雑なマイクロサービス web を作成する場合も、OpenShift Pipeline を使用して、OpenShift でアプリケーションをビルド、テスト、デプロイ、プロモートを実行します。

標準の Jenkins Pipeline 構文のほかにも、OpenShift Jenkins イメージは (OpenShift Jenkins Client プラグインを使用して) OpenShift の Domain Specific Language (DSL) を提供します。これは、OpenShift API サーバーと高度な対話を行う、読み取り可能でコンパクトで総合的な、かつ Fluent (流れるような) 構文を提供することを目的とし、OpenShift クラスターのアプリケーションのビルド、デプロイメント、プロモートのより詳細な制御が可能になります。

以下の例では、nodejs-mongodb.json テンプレートを使用して Node.js/MongoDB アプリケーションをビルドし、デプロイし、検証する OpenShift Pipeline を作成する方法を紹介します。

7.5.2. Jenkins Master の作成

Jenkins master を作成するには以下を実行します。

  $ oc project <project_name> 1
  $ oc new-app jenkins-ephemeral 2
1
oc new-project <project_name> で新規プロジェクトを使用するか、または作成するプロジェクトを選択します。
2
永続ストレージを使用する場合は、jenkins-persistent を代わりに使用します。
注記

Jenkins の自動プロビジョニングがクラスターで有効化されており、Jenkins master をカスタマイズする必要がない場合には、以前の手順を省略できます。

Jenkins の自動プロビジョニングに関する情報は、「Pipeline の実行設定」を参照してください。

7.5.3. Pipeline のビルド設定

Jenkins master が機能するようになったので、Jenkins Pipeline ストラテジーを使用して Node.js/MongoDB のサンプルアプリケーションをビルドし、デプロイし、スケーリングする BuildConfig を作成します。

以下の内容で nodejs-sample-pipeline.yaml という名前のファイルを作成します。

kind: "BuildConfig"
apiVersion: "v1"
metadata:
  name: "nodejs-sample-pipeline"
spec:
  strategy:
    jenkinsPipelineStrategy:
      jenkinsfile: <pipeline content from below>
    type: JenkinsPipeline

Pipeline ビルドストラテジーに関する情報は、「Pipeline ストラテジーオプション」を参照してください。

7.5.4. Jenkinsfile

jenkinsPipelineStrategy で BuildConfig を作成したら、インラインの jenkinsfile を使用して、パイプラインに指示を出します。以下の例では、アプリケーションの git リポジトリーは設定していません。

以下の jenkinsfile の内容は、OpenShift DSL を使用して Groovy で記述されています。ソースリポジトリーに jenkinsfile を追加することが推奨される方法ですが、この例では YAML Literal Style を使用して BuildConfig にインラインコンテンツを追加しています。

完了した BuildConfig は、OpenShift Origin リポジトリーの examples ディレクトリーの nodejs-sample-pipeline.yaml で確認できます。

def templatePath = 'https://raw.githubusercontent.com/openshift/nodejs-ex/master/openshift/templates/nodejs-mongodb.json' 1
def templateName = 'nodejs-mongodb-example' 2
pipeline {
  agent {
    node {
      label 'nodejs' 3
    }
  }
  options {
    timeout(time: 20, unit: 'MINUTES') 4
  }
  stages {
    stage('preamble') {
        steps {
            script {
                openshift.withCluster() {
                    openshift.withProject() {
                        echo "Using project: ${openshift.project()}"
                    }
                }
            }
        }
    }
    stage('cleanup') {
      steps {
        script {
            openshift.withCluster() {
                openshift.withProject() {
                  openshift.selector("all", [ template : templateName ]).delete() 5
                  if (openshift.selector("secrets", templateName).exists()) { 6
                    openshift.selector("secrets", templateName).delete()
                  }
                }
            }
        }
      }
    }
    stage('create') {
      steps {
        script {
            openshift.withCluster() {
                openshift.withProject() {
                  openshift.newApp(templatePath) 7
                }
            }
        }
      }
    }
    stage('build') {
      steps {
        script {
            openshift.withCluster() {
                openshift.withProject() {
                  def builds = openshift.selector("bc", templateName).related('builds')
                  timeout(5) { 8
                    builds.untilEach(1) {
                      return (it.object().status.phase == "Complete")
                    }
                  }
                }
            }
        }
      }
    }
    stage('deploy') {
      steps {
        script {
            openshift.withCluster() {
                openshift.withProject() {
                  def rm = openshift.selector("dc", templateName).rollout()
                  timeout(5) { 9
                    openshift.selector("dc", templateName).related('pods').untilEach(1) {
                      return (it.object().status.phase == "Running")
                    }
                  }
                }
            }
        }
      }
    }
    stage('tag') {
      steps {
        script {
            openshift.withCluster() {
                openshift.withProject() {
                  openshift.tag("${templateName}:latest", "${templateName}-staging:latest") 10
                }
            }
        }
      }
    }
  }
}
1
使用するテンプレートへのパス
2
作成するテンプレート名
3
このビルドを実行する node.js のスレーブ Pod をスピンアップします。
4
このパイプラインに 20 分間のタイムアウトを設定します。
5
このテンプレートラベルが指定されたものすべてを削除します。
6
このテンプレートラベルが付いたシークレットをすべて削除します。
7
templatePath から新規アプリケーションを作成します。
8
ビルドが完了するまで最大 5 分待機します。
9
デプロイメントが完了するまで最大 5 分待機します。
10
すべてが正常に完了した場合は、$ {templateName}:latest イメージに $ {templateName}-staging:latest のタグを付けます。ステージング環境向けのパイプラインの BuildConfig は、変更する $ {templateName}-staging:latest イメージがないかを確認し、このイメージをステージング環境にデプロイします。
注記

以前の例は、declarative pipeline スタイルを使用して記述されていますが、以前の scripted pipeline スタイルもサポートされます。

7.5.5. パイプラインの作成

OpenShift の BuildConfig を作成するには、以下を実行します。

$ oc create -f nodejs-sample-pipeline.yaml

独自のファイルを作成しない場合には、以下を実行して Origin リポジトリーからサンプルを使用できます。

$ oc create -f https://raw.githubusercontent.com/openshift/origin/master/examples/jenkins/pipeline/nodejs-sample-pipeline.yaml

使用する OpenShift DSL 構文の情報は、「OpenShift Jenkins クライアントプラグイン」を参照してください。

7.5.6. パイプラインの起動

以下のコマンドでパイプラインを起動します。

$ oc start-build nodejs-sample-pipeline
注記

または、OpenShift Web コンソールで Builds → Pipeline セクションに移動して、Start Pipeline をクリックするか、Jenkins コンソールから作成したパイプラインに移動して、Build Now をクリックしてパイプラインを起動できます。

パイプラインが起動したら、以下のアクションがプロジェクト内で実行されるはずです。

  • ジョブインスタンスが Jenkins サーバー上で作成される
  • パイプラインで必要な場合には、スレーブ Pod が起動される
  • パイプラインがスレーブ Pod で実行されるか、またはスレーブが必要でない場合には master で実行される

    • template=nodejs-mongodb-example ラベルの付いた以前に作成されたリソースは削除されます。
    • 新規アプリケーションおよびそれに関連するすべてのリソースは、nodejs-mongodb-example テンプレートで作成されます。
    • ビルドは nodejs-mongodb-example BuildConfig を使用して起動されます。

      • パイプラインは、ビルドが完了して次のステージをトリガーするまで待機します。
    • デプロイメントは、nodejs-mongodb-example のデプロイメント設定を使用して開始されます。

      • パイプラインは、デプロイメントが完了して次のステージをトリガーするまで待機します。
    • ビルドとデプロイに成功すると、nodejs-mongodb-example:latest イメージが nodejs-mongodb-example:stage としてトリガーされます。
  • パイプラインで以前に要求されていた場合には、スレーブ Pod が削除される
注記

OpenShift Web コンソールで確認すると、最適な方法でパイプラインの実行を視覚的に把握することができます。Web コンソールにログインして、Builds → Pipelines に移動して、パイプラインを確認します。

7.5.7. OpenShift Pipeline の詳細オプション

OpenShift Pipeline では、Jenkins を 1 つのプロジェクトで起動してから、OpenShift 同期プラグインに開発者が作業をするプロジェクトグループをモニタリングさせることができます。以下のセクションでは、このプロセスを完了する手順を説明します。

  • Jenkins の自動プロビジョニングを無効化するには、「Pipeline の実行設定」を参照してください。
  • Jenkins サービスアカウントを有効化して、OpenShift Pipeline を実行する各プロジェクトにアクセスする方法は、「プロジェクト間のアクセス」を参照してください。
  • モニタリングするプロジェクトを追加するには、以下のいずれかを行います。

    • Jenkins コンソールにログインします。

      • Manage Jenkins から、Configure System に移動します。
      • OpenShift Jenkins SyncNamespace フィールドを更新します。
    • または、S2I 拡張オプションを使用して OpenShift Jenkins イメージを拡張して Jenkins 設定ファイルを更新します。
注記

OpenShift 同期プラグインを実行する複数の Jenkins デプロイメントから、同じプロジェクトのモニタリングがされないようにします。これらのインスタンス間の連携はなく、予期せぬ結果が発生する可能性があります。

7.6. バイナリービルド

7.6.1. はじめに

OpenShift のバイナリービルドの機能では、開発者はビルドで Git リポジトリーの URL からソースをプルするのではなく、ソースまたはアーティファクトをビルドに直接アップロードします。ソース、Docker またはカスタムのストラテジーが指定された BuildConfig はバイナリービルドとして起動できます。ローカルのアーティファクトからビルドを起動する場合は、既存のソース参照をローカルユーザーのマシンのソースに置き換えます。

ソースは複数の方法で提供できます。これは、start-build コマンドの使用時に利用可能な引数に相当します。

  • ファイルから (--from-file): これは、ビルドのソース全体が単一ファイルで構成されている場合です。たとえば、Docker ビルドは Dockerfile、Wildfly ビルドは pom.xml、Ruby ビルドは Gemfile です。
  • ディレクトリーから (--from-directory): ソースがローカルのディレクトリーにあり、Git リポジトリーにコミットされていない場合に使用します。start-build コマンドは指定のディレクトリーのアーカイブを作成して、ビルダーにソースとしてアップロードします。
  • アーカイブから (--from-archive): ソースが含まれるアーカイブがすでに存在する場合に使用します。アーカイブはtartar.gz または zip 形式のいずれかを使用できます。
  • Git リポジトリーから (--from-repo): これはソースがユーザーのローカルマシンで Git リポジトリーの一部となっている場合に使用します。現在のリポジトリーの HEAD コミットがアーカイブされ、ビルド用に OpenShift に送信されます。

7.6.1.1. 使用例

バイナリービルドの場合は、ビルドでソースを既存の git リポジトリーからプルする必要がありません。バイナリービルドを使用する理由は以下のとおりです。

  • ローカルコードの変更をビルドし、テストする。パブリックリポジトリーからのソースはクローンでき、ローカルの変更を OpenShift にアップロードしてビルドできます。ローカルの変更はコミットまたはプッシュする必要はありません。
  • プロイベートコードをビルドする。新規ビルドをゼロからバイナリービルドとして起動することができます。ソースは、SCM にチェックインする必要なく、ローカルのワークステションから OpenShift に直接アップロードできます。
  • 別のソースからアーティファクトを含むイメージをビルドする。Jenkins Pipeline では、Maven または C コンパイラー、これらのビルドを活用するランタイムイメージなどのツールでビルドしたアーティファクトを組み合わせる場合に、バイナリービルドが役立ちます。

7.6.1.2. 制限

  • バイナリービルドは反復できません。バイナリービルドは、ビルドの開始時にアーティファクトをアップロードするユーザーに依存するため、そのユーザーが毎回同じアップロードを繰り返さない限り、OpenShift は同じビルドを反復できません。
  • バイナリービルドは自動的にトリガーできません。バイナリービルドは、ユーザーが必要なバイナリーアーティファクトをアップロードする時にのみ手動で起動できます。
注記

バイナリービルドとして起動したビルドには設定済みのソース URL が含まれる場合があります。その場合、トリガーでビルドが正常に起動しますが、ソースはビルドの最終実行時にユーザーが指定した URL ではなく、設定済みのソース URL から取得されます。

7.6.2. チュートリアルの概要

以下のチュートリアルは、OpenShift クラスターが利用可能であり、アーティファクトを作成できるプロジェクトが用意されていることを前提としています。このチュートリアルでは、gitoc がローカルで使用できる必要があります。

7.6.2.1. チュートリアル: ローカルコードの変更のビルド

  1. 既存のソースリポジトリーをベースにして新規アプリケーションを作成し、そのルートを作成します。

    $ oc new-app https://github.com/openshift/ruby-hello-world.git
    $ oc expose svc/ruby-hello-world
  2. 初期ビルドが完了するまで待機し、ルートのホストに移動してアプリケーションのページを表示すると、Welcome ページが表示されるはずです。

    $ oc get route ruby-hello-world
  3. リポジトリーをローカルにクローンします。

    $ git clone https://github.com/openshift/ruby-hello-world.git
    $ cd ruby-hello-world
  4. アプリケーションのビューに変更を加えます。任意のエディターで views/main.rb を編集します。<body> タグを <body style="background-color:blue"> に変更します。
  5. ローカルで変更したソースで新規ビルドを起動します。リポジトリーのローカルディレクトリーから、以下を実行します。

    ----
    $ oc start-build ruby-hello-world --from-dir="." --follow
    ----

ビルドが完了し、アプリケーションが再デプロイされたら、アプリケーションのルートホストに移動すると、青のバックグラウンドのページが表示されるはずです。

ローカルでさらに変更を加えて、oc start-build --from-dir でコードをビルドします。

また、コードのブランチを作成し、変更をローカルでコミットし、リポジトリーの HEAD をビルドのソースとして使用します。

$ git checkout -b my_branch
$ git add .
$ git commit -m "My changes"
$ oc start-build ruby-hello-world --from-repo="." --follow

7.6.2.2. チュートリアル: プライベートコードのビルド

  1. コードを保存するローカルディレクトリーを作成します。

    $ mkdir myapp
    $ cd myapp
  2. このディレクトリーで、以下の内容を含む Dockerfile という名前のファイルを作成します。

    FROM centos:centos7
    
    EXPOSE 8080
    
    COPY index.html /var/run/web/index.html
    
    CMD cd /var/run/web && python -m SimpleHTTPServer 8080
  3. 以下の内容を含む index.html という名前のファイルを作成します。

    <html>
      <head>
        <title>My local app</title>
      </head>
      <body>
        <h1>Hello World</h1>
        <p>This is my local application</p>
      </body>
    </html>
  4. アプリケーションの新規ビルドを作成します。

    $ oc new-build --strategy docker --binary --docker-image centos:centos7 --name myapp
  5. ローカルディレクトリーの内容を使用して、バイナリービルドを起動します。

    $ oc start-build myapp --from-dir . --follow
  6. new-app を使用してアプリケーションをデプロイしてから、そのルートを作成します。

    $ oc new-app myapp
    $ oc expose svc/myapp
  7. ルートのホスト名を取得して、そこに移動します。

    $ oc get route myapp

コードをビルドし、デプロイした後に、ローカルファイルに変更を加えて、oc start-build myapp --from-dir を呼び出して新規ビルドを起動します。ビルドされると、コードが自動的にデプロイされ、ページを更新すると、変更がブラウザーに反映されます。

7.6.2.3. チュートリアル: パイプラインからのバイナリーアーティファクト

Jenkins on OpenShift では、適切なツールでスレーブイメージを使用して、コードをビルドすることができます。たとえば、maven スレーブを使用して、コードリポジトリーから WAR をビルドできます。ただし、このアーティファクトがビルドされたら、コードを実行するための適切なランタイムアーティファクトが含まれるイメージにコミットする必要があります。これらのアーティファクトをランタイムイメージに追加するために、バイナリービルドが使用される場合があります。以下のチュートリアルでは、maven スレーブで WAR をビルドし、Dockerfile でバイナリービルドを使用してこの WAR を WIldfly のランタイムイメージに追加するように Jenkins パイプラインを作成します。

  1. アプリケーションの新規ディレクトリーを作成します。

    $ mkdir mavenapp
    $ cd mavenapp
  2. WAR を wildfly イメージ内の適切な場所にコピーする Dockerfile を作成します。以下を Dockerfile という名前のローカルファイルにコピーします。

    FROM wildfly:latest
    COPY ROOT.war /wildfly/standalone/deployments/ROOT.war
    CMD  $STI_SCRIPTS_PATH/run
  3. Dockerfile の新規 BuildConfig を作成します。

    注記

    これにより、ビルドが自動的に起動しますが、ROOT.war アーティファクトがまだ利用できないので初回は失敗します。以下のパイプラインでは、バイナリービルドを使用してその WAR をビルドに渡します。

    $ cat Dockerfile | oc new-build -D - --name mavenapp
  4. Jenkins Pipeline で BuildConfig を作成します。この BuildConfig では WAR をビルドし、以前に作成した Dockerfile を使用してこの WAR でイメージをビルドします。ツールのセットでバイナリーアーティファクトをビルドしてから、最終的なパッケージ用に別のランタイムイメージと組み合わせる場合など、同じパターンを別のプラットフォームでも使用できます。以下のコードを mavenapp-pipeline.yml に保存します。

    apiVersion: v1
    kind: BuildConfig
    metadata:
      name: mavenapp-pipeline
    spec:
      strategy:
        jenkinsPipelineStrategy:
          jenkinsfile: |-
            pipeline {
              agent { label "maven" }
              stages {
                stage("Clone Source") {
                  steps {
                    checkout([$class: 'GitSCM',
                                branches: [[name: '*/master']],
                                extensions: [
                                  [$class: 'RelativeTargetDirectory', relativeTargetDir: 'mavenapp']
                                ],
                                userRemoteConfigs: [[url: 'https://github.com/openshift/openshift-jee-sample.git']]
                            ])
                  }
                }
                stage("Build WAR") {
                  steps {
                    dir('mavenapp') {
                      sh 'mvn clean package -Popenshift'
                    }
                  }
                }
                stage("Build Image") {
                  steps {
                    dir('mavenapp/target') {
                      sh 'oc start-build mavenapp --from-dir . --follow'
                    }
                  }
                }
              }
            }
        type: JenkinsPipeline
      triggers: []
  5. Pipeline ビルドを作成します。Jenkins がプロジェクトにデプロイされていない場合は、パイプラインが含まれる BuildConfig を作成すると、Jenkins がデプロイされます。Jenkins がパイプラインをビルドする準備ができるまで、2 分ほどかかる場合があります。Jenkins のロールアウトの状況を確認するには、oc rollout status dc/jenkins を起動します。

    $ oc create -f ./mavenapp-pipeline.yml
  6. Jenkins の準備ができたら、以前に定義したパイプラインを起動します。

    $ oc start-build mavenapp-pipeline
  7. パイプラインがビルドを完了した時点で、new-app で新規アプリケーションをデプロイし、ルートを公開します。

    $ oc new-app mavenapp
    $ oc expose svc/mavenapp
  8. ブラウザーで、アプリケーションのルートに移動します。

    $ oc get route mavenapp

第8章 ビルド

8.1. ビルドの仕組み

8.1.1. ビルドの概要

OpenShift Container Platform での「ビルド」とは、入力パラメーターをオブジェクトに変換するプロセスのことです。多くの場合に、ビルドを使用して、ソースコードを実行可能なコンテナーイメージに変換します。

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

ビルドストラテジーには、以下が含まれます。

「ビルド入力」として指定できるソースは 6 種類あります。

ビルドストラテジーごとに、特定タイプのソースを検討するか、または無視するか、またはそのソースタイプの使用方法が決まります。バイナリーおよび Git のソースタイプは併用できません。Dockerfile とイメージは、そのまま単体で使用することも、2 つを併用することも、Git またはバイナリーと組み合わせることも可能です。バイナリーのソースタイプは、他のオプションと比べると「システムへの指定方法」という点が独特です。

8.1.2. BuildConfig の概要

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

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

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

BuildConfig のオブジェクト定義

kind: "BuildConfig"
apiVersion: "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"

1
この仕様は、ruby-sample-build という名前の新規の BuildConfig を作成します。
2
runPolicy フィールドは、このビルド設定に基づいて作成されたビルドを同時に実行できるかどうかを制御します。デフォルトの値は Serial です。これは新規ビルドが同時にではなく、順番に実行されることを意味します。
3
新規ビルドを作成する トリガー の一覧を指定できます。
4
source セクションでは、ビルドのソースを定義します。ソースの種類は入力の主なソースを決定し、Git (コードのリポジトリーの場所を参照)、Dockerfile (インラインの Dockerfile からビルド) または Binary (バイナリーペイロードを受け入れる) のいずれかとなっています。複数のソースを一度に指定できます。詳細は、各ソースタイプのドキュメントを参照してください。
5
strategy セクションでは、ビルドの実行に使用するビルドストラテジーを記述します。ここでは SourceDocker または Custom ストラテジーを指定できます。上記の例では、Source-To-Image がアプリケーションのビルドに使用する ruby-20-centos7 コンテナーイメージを使用します。
6
コンテナーイメージが正常にビルドされた後に、これは output セクションで記述されているリポジトリーにプッシュされます。
7
postCommit セクションは、オプションで ビルドフック を定義します。

8.2. 基本的なビルド操作

8.2.1. ビルドの開始

以下のコマンドを使用して、現在のプロジェクトに既存のビルド設定から新規ビルドを手動で起動します。

$ oc start-build <buildconfig_name>

--from-build フラグを使用してビルドを再度実行します。

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

--follow フラグを指定して、stdout のビルドのログをストリームします。

$ oc start-build <buildconfig_name> --follow

--env フラグを指定して、ビルドに任意の環境変数を設定します。

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

Git ソースプルまたは Dockerfile に依存してビルドするのではなく、ソースを直接プッシュしてビルドを開始することも可能です。ソースには、Git または SVN の作業ディレクトリーの内容、デプロイする事前に構築済みバイナリーアーティファクトまたは単一ファイルのいずれかを選択できます。これは、start-build コマンドに以下のオプションのいずれかを指定して実行できます。

オプション説明

--from-dir=<directory>

アーカイブし、ビルドのバイナリー入力として使用するディレクトリーを指定します。

--from-file=<file>

単一ファイルを指定します。これはビルドソースで唯一のファイルでなければなりません。このファイルは、元のファイルと同じファイル名で空のディレクトリーのルートに置いてください。

--from-repo=<local_source_repo>

ビルドのバイナリー入力として使用するローカルリポジトリーへのパスを指定します。--commit オプションを追加して、ビルドに使用するブランチ、タグ、またはコミットを制御します。

以下のオプションをビルドに直接指定した場合には、コンテンツはビルドにストリームされ、現在のビルドソースの設定が上書きされます。

注記

バイナリー入力からトリガーされたビルドは、サーバー上にソースを保存しないため、ベースイメージの変更でビルドが再度トリガーされた場合には、ビルド設定で指定されたソースが使用されます。

たとえば、以下のコマンドは、タグ v2 からのアーカイブとしてローカルの Git リポジトリーのコンテンツを送信し、ビルドを開始します。

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

8.2.2. ビルドの中止

Web コンソールまたは以下の CLI コマンドを使用して、ビルドを手動でキャンセルします。

$ oc cancel-build <build_name>

複数のビルドを同時にキャンセルします。

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

ビルド設定から作成されたビルドすべてをキャンセルします。

$ oc cancel-build bc/<buildconfig_name>

特定の状態にあるビルドをすべてキャンセルします (例: new または pending)。この際、他の状態のビルドは無視されます。

$ oc cancel-build bc/<buildconfig_name>  --state=<state>

8.2.3. BuildConfig の削除

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

$ oc delete bc <BuildConfigName>

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

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

8.2.4. ビルドの詳細表示

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

$ oc describe build <build_name>

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

  • ビルドソース
  • ビルドストラテジー
  • 出力先
  • 宛先レジストリーのイメージのダイジェスト
  • ビルドの作成方法

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

8.2.5. ビルドログへのアクセス

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

ビルドを直接使用してログをストリームするには、以下を実行します。

$ oc logs -f build/<build_name>

ビルド設定の最新ビルドのログをストリームするには、以下を実行します。

$ oc logs -f bc/<buildconfig_name>

ビルド設定で指定されているバージョンのビルドに関するログを返すには、以下を実行します。

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

ログの詳細レベル

詳細の出力を有効にするには、BuildConfig 内の sourceStrategy または dockerStrategy の一部として BUILD_LOGLEVEL 環境変数を指定します。

sourceStrategy:
...
  env:
    - name: "BUILD_LOGLEVEL"
      value: "2" 1
1
この値を任意のログレベルに調整します。
注記

プラットフォームの管理者は、BuildDefaults 受付コントローラーの env/BUILD_LOGLEVEL を設定して、OpenShift Container Platform インスタンス全体のデフォルトのビルドの詳細レベルを設定できます。このデフォルトは、指定の BuildConfigBUILD_LOGLEVEL を指定することで上書きできます。コマンドラインで --build-logleveloc start-build に渡すことで、バイナリー以外のビルドについて優先順位の高い上書きを指定することができます。

ソースビルドで利用できるログレベルは以下のとおりです。

レベル 0

assemble スクリプトを実行してコンテナーからの出力とすべてのエラーを生成します。これはデフォルトの設定です。

レベル 1

実行したプロセスに関する基本情報を生成します。

レベル 2

実行したプロセスに関する詳細情報を生成します。

レベル 3

実行したプロセスに関する詳細情報と、アーカイブコンテンツの一覧を生成します。

レベル 4

現時点ではレベル 3 と同じ情報を生成します。

レベル 5

これまでのレベルで記載したすべての内容と docker のプッシュメッセージを提供します。

8.3. ビルド入力

8.3.1. ビルド入力の仕組み

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

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

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

ビルドが実行されるたびに、以下が行われます。

  1. 作業ディレクトリーが作成され、すべての入力内容がその作業ディレクトリーに配置されます。たとえば、入力 Git リポジトリーのクローンはこの作業ディレクトリーに作成され、入力イメージから指定されたファイルはターゲットのパスを使用してこの作業ディレクトリーにコピーされます。
  2. ビルドプロセスによりディレクトリーが contextDir に変更されます (定義されている場合)。
  3. インライン Dockerfile がある場合は、現在のディレクトリーに書き込まれます。
  4. 現在の作業ディレクトリーにある内容が Dockerfile、カスタムビルダーのロジック、または assemble スクリプトが参照するビルドプロセスに提供されます。つまり、ビルドでは contextDir 内にない入力コンテンツは無視されます。

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

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
1
作業ディレクトリーにクローンされるビルド用のリポジトリー
2
myinputimage/usr/lib/somefile.jar は、<workingdir>/app/dir/injected/dir に保存されます。
3
ビルドの作業ディレクトリーは <original_workingdir>/app/dir になります。
4
このコンテンツを含む Dockerfile は <original_workingdir>/app/dir に作成され、この名前が指定された既存ファイルは上書きされます。

8.3.2. Dockerfile のソース

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

このフィールドの一般的な用途は、Dockerfile「Docker ストラテジー」ビルドに渡すことです。

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

source:
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 1
1
dockerfile フィールドには、ビルドされるインライン Dockerfile が含まれます。

8.3.3. イメージソース

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

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

イメージのインプットは、BuildConfigsource の定義で指定します。

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
1
1 つ以上のインプットイメージおよびファイルの配列
2
コピーされるファイルが含まれるイメージへの参照
3
ソース/宛先パスの配列
4
ビルドプロセスで対象のファイルにアクセス可能なビルドルートへの相対パス
5
参照イメージの中からコピーするファイルの場所
6
認証情報がインプットイメージにアクセスするのに必要な場合に提供されるオプションのシークレット
注記

この機能は、カスタムストラテジー を使用したビルドではサポートされません。

8.3.4. git ソース

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

インラインの Dockerfile がサポートされる場合には、git リポジトリー contextDir 内にあるDockerfile (ある場合) が上書きされます。

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

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
1
git フィールドには、ソースコードのリモート git リポジトリーへの URI が含まれます。オプションで、ref フィールドを指定して特定の git 参照をチェックアウトします。SHA1 タグまたはブランチ名は、ref として有効です。
2
contextDir フィールドでは、ビルドがアプリケーションのソースコードを検索する、ソースコードのリポジトリー内のデフォルトの場所を上書きできます。アプリケーションがサブディレクトリーに存在する場合には、このフィールドを使用してデフォルトの場所 (root フォルダー) を上書きすることができます。
3
オプションの dockerfile フィールドがある場合は、Dockerfile を含む文字列を指定してください。この文字列は、ソースリポジトリーに存在する可能性のある Dockerfile を上書きします。

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

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

8.3.4.1. プロキシーの使用

プロキシー経由でのみ Git リポジトリーにアクセスできる場合には、BuildConfigsource セクションで使用するプロキシーを定義できます。HTTP および HTTPS プロキシーの両方を設定できますが、いずれのフィールドもオプションです。プロキシーを使用すべきでないドメインは、NoProxy フィールドで指定することも可能です。

注記

これを機能させるには、ソース URI で HTTP または HTTPS プロトコルを使用する必要があります。

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

クラスター管理者は「Ansible を使用した Git クローン用のグローバルプロキシーの設定」を実行することもできます。

注記

Pipeline ストラテジーのビルドの場合には、現在 Jenkins の Git プラグインに制約があるので、Git プラグインを使用する Git の操作では BuildConfig に定義された HTTP または HTTPS プロキシーは使用されません。Git プラグインは、Jenkins UI の Plugin Manager パネルで設定されたプロキシーのみを使用します。どのジョブであっても、Jenkins 内の git のすべての対話にはこのプロキシーが使用されます。Jenkins UI でのプロキシーの設定方法については、JenkinsBehindProxy を参照してください。

8.3.4.2. ソースクローンのシークレット

ビルダー Pod には、ビルドのソースとして定義された git リポジトリーへのアクセスが必要です。ソースクローンのシークレットは、ビルダー Pod に対し、プライベートリポジトリーや自己署名証明書または信頼されていない SSL 証明書が設定されたリポジトリーなどの通常アクセスできないリポジトリーへのアクセスを提供するために使用されます。

以下は、サポートされているソースクローンのシークレット設定です。

注記

個別のニーズに対応すべく、これらの設定を 組み合わせて 使用することも可能です。

ビルドは builder サービスアカウントで実行されます。この builder アカウントには、使用するソースクローンのシークレットに対するアクセスが必要です。以下のコマンドを使用してアクセスを付与できます。

$ oc secrets link builder mysecret
注記

シークレットを参照しているサービスアカウントにのみにシークレットを制限することはデフォルトで無効にされています。つまり、serviceAccountConfig.limitSecretReferences がマスター設定ファイルで false (デフォルト設定) に設定されている場合は、サービスにシークレットをリンクする必要はありません。

8.3.4.2.1. ソースクローンシークレットのビルド設定への自動追加

BuildConfig が作成されると、OpenShift Container Platform は自動的にソースクローンのシークレット参照を生成します。この動作により、追加の設定なしに、作成される Builds が参照される Secret に保存された認証情報を自動的に使用して、リモート git リポジトリーへの認証を行います。

この機能を使用するには、git リポジトリーの認証情報を含む SecretBuildConfig が後に作成される namespace になければなりません。この Secret には、プレフィックスbuild.openshift.io/source-secret-match-uri- で開始するアノテーション 1 つ以上含まれている必要もあります。これらの各アノテーションの値には、以下で定義される URI パターンを指定します。ソースクローンのシークレット参照なしに BuildConfig が作成され、git ソースの URI が Secret アノテーションの URI パターンと一致する場合に、OpenShift Container Platform はその Secret への参照を BuildConfig に自動的に挿入します。

URI パターンには以下を含める必要があります。

  • 有効なスキーム (*://git://http://https:// または ssh://)
  • ホスト (* または、有効なホスト名、オプションで *. が先頭に指定された IP アドレス)
  • パス (/* または、/ の後に * などの文字が後に続く文字列)

上記のいずれの場合でも、* 文字はワイルドカードと見なされます。

重要

URI パターンは、RFC3986 に準拠する Git ソースの URI と一致する必要があります。URI パターンのにユーザー名 (またはパスワード) のコンポーネントを含ないようにしてください。

たとえば、git リポジトリーの URL に ssh://git@bitbucket.atlassian.com:7999/ATLASSIAN/jira.git を使用する場合に、ソースのシークレットは ssh://bitbucket.atlassian.com:7999/* として指定する必要があります (ssh://git@bitbucket.atlassian.com:7999/* ではありません)。

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

複数の Secrets が特定の BuildConfig の Git URI と一致する場合は、OpenShift Container Platform は一致する文字列が一番長いシークレットを選択します。これは、以下の例のように基本的な上書きを許可します。

以下の部分的な例では、ソースクローンのシークレットの一部が 2 つ表示されています。1 つ目は、HTTPS がアクセスする mycorp.com ドメイン内のサーバーに一致しており、2 つ目は mydev1.mycorp.com および mydev2.mycorp.com のサーバーへのアクセスを上書きします。

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:
  ...

以下のコマンドを使用して、build.openshift.io/source-secret-match-uri- アノテーションを既存のシークレットに追加します。

$ oc annotate secret mysecret \
    'build.openshift.io/source-secret-match-uri-1=https://*.mycorp.com/*'
8.3.4.2.2. ソースクローンシークレットの手動による追加

ソースクローンのシークレットは、ビルド設定に手動で追加できます。これは、sourceSecret フィールドを BuildConfig 内の source セクションに追加して、これを作成した secret の名前に設定して実行できます (この例では basicsecret)。

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 コマンドを使用して、既存のビルド設定にソースクローンのシークレットを設定することも可能です。

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

BuildConfig でのシークレットの定義」では、このトピックについて詳しく説明しています。

8.3.4.2.3. .gitconfig ファイル

アプリケーションのクローンが .gitconfig ファイルに依存する場合、そのファイルが含まれるシークレットを作成してからこれをビルダーサービスアカウントに追加し、BuildConfig に追加できます。

.gitconfig ファイルからシークレットを作成するには、以下を実行します。

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

.gitconfig ファイルの http セクションが sslVerify=false に設定されている場合は、SSL 認証をオフにすることができます。

[http]
        sslVerify=false
8.3.4.2.4. セキュアな git 用の .gitconfig ファイル

Git サーバーが 2-way SSL、ユーザー名とパスワードでセキュリティー保護されている場合には、ソースビルドに証明書ファイルを追加して、.gitconfig ファイルに証明書ファイルへの参照を追加する必要があります。

  1. client.crtcacert.crt および client.key ファイルを「アプリケーションのソースコード」/var/run/secrets/openshift.io/source/ フォルダーに追加します。
  2. サーバーの .gitconfig ファイルに、以下の例のように [http] セクションを追加します。

    # cat .gitconfig
    [user]
            name = <name>
            email = <email>
    [http]
            sslVerify = false
            sslCert = /var/run/secrets/openshift.io/source/client.crt
            sslKey = /var/run/secrets/openshift.io/source/client.key
            sslCaInfo = /var/run/secrets/openshift.io/source/cacert.crt
  3. シークレットを作成します。

    $ oc create secret generic <secret_name> \
    --from-literal=username=<user_name> \ 1
    --from-literal=password=<password> \ 2
    --from-file=.gitconfig=.gitconfig \
    --from-file=client.crt=/var/run/secrets/openshift.io/source/client.crt \
    --from-file=cacert.crt=/var/run/secrets/openshift.io/source/cacert.crt \
    --from-file=client.key=/var/run/secrets/openshift.io/source/client.key
    1
    ユーザーの git ユーザー名
    2
    このユーザーのパスワード
重要

パスワードを再度入力しないでいいように、ビルド内に S2I イメージを指定するようにしてください。ただし、リポジトリーをクローンできない場合には、ビルドをプロモートするためにユーザー名とパスワードを指定する必要があります。

8.3.4.2.5. Basic 認証

Basic 認証では、SCM サーバーに対して認証する場合に --username--password の組み合わせ、または token が必要です。

secret を先に作成してから、プライベートリポジトリーにアクセスするためのユーザー名とパスワードを使用してください。

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

トークンで Basic 認証のシークレットを作成するには、以下を実行します。

$ oc create secret generic <secret_name> \
    --from-literal=password=<token> \
    --type=kubernetes.io/basic-auth
8.3.4.2.6. SSH キー認証

SSH キーベースの認証では、プライベート SSH キーが必要です。

リポジトリーのキーは通常 $HOME/.ssh/ ディレクトリーにあり、デフォルトで id_dsa.pubid_ecdsa.pubid_ed25519.pub または id_rsa.pub という名前が付けられています。以下のコマンドで、SSH キーの認証情報を生成します。

$ ssh-keygen -t rsa -C "your_email@example.com"
注記

SSH キーのパスフレーズを作成すると、OpenShift Container Platform でビルドができなくなります。パスフレーズを求めるプロンプトが出されても、ブランクのままにします。

パブリックキーと、それに対応するプライベートキーのファイルが 2 つ作成されます (id_dsaid_ecdsaid_ed25519 または id_rsa のいずれか)。これらが両方設定されたら、パブリックキーのアップロード方法についてソースコントロール管理 (SCM) システムのマニュアルを参照してください。プライベートキーは、プライベートリポジトリーにアクセスするために使用されます。

SSHキーを使用してプライベートリポジトリーにアクセスする前に、シークレットを作成します。

$ oc create secret generic <secret_name> \
    --from-file=ssh-privatekey=<path/to/ssh/private/key> \
    --type=kubernetes.io/ssh-auth
8.3.4.2.7. 信頼された証明局

git clone の操作時に信頼される TLS 認証局のセットは OpenShift Container Platform インフラストラクチャーイメージにビルドされます。Git サーバーが自己署名の証明書を使用するか、イメージで信頼されていない認証局により署名された証明書を使用する場合には、その証明書が含まれるシークレットを作成するか、TLS 検証を無効にしてください。

CA 証明書 のシークレットを作成した場合に、OpenShift Container Platform はその証明書を使用して、git clone 操作時に Git サーバーにアクセスします。存在する TLS 証明書をどれでも受け入れてしまう Git の SSL 検証の無効化に比べ、この方法を使用するとセキュリティーが高くなります。

以下のプロセスの 1 つを完了します。

  • CA 証明書ファイルでシークレットを作成する (推奨)

    1. CA が中間証明局を使用する場合には、ca.crt ファイルにすべての CA の証明書を統合します。以下のコマンドを実行してください。

      $ cat intermediateCA.crt intermediateCA.crt rootCA.crt > ca.crt
    2. シークレットを作成します。

      $ oc create secret generic mycert --from-file=ca.crt=</path/to/file> 1
      1
      鍵の名前には ca.crt を使用する必要があります。
  • git TLS 検証を無効にします。

    ビルド設定の適切なストラテジーセクションで GIT_SSL_NO_VERIFY 環境変数を true に設定します。BuildConfig 環境変数を管理するには、oc set env コマンドを使用できます。

8.3.4.2.8. 組み合わせ

ここでは、特定のニーズに対応するために上記の方法を組み合わせてソースクローンのシークレットを作成する方法についての例を紹介します。

  1. .gitconfig ファイルで SSH ベースの認証シークレットを作成するには、以下を実行します。

    $ 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
  2. .gitconfig ファイルと CA 証明書を組み合わせてシークレットを作成するには、以下を実行します。

    $ oc create secret generic <secret_name> \
        --from-file=ca.crt=<path/to/certificate> \
        --from-file=<path/to/.gitconfig>
  3. CA 証明書ファイルで Basic 認証のシークレットを作成するには、以下を実行します。

    $ 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
  4. .gitconfig ファイルで Basic 認証のシークレットを作成するには、以下を実行します。

    $ 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
  5. .gitconfig ファイルと CA 証明書ファイルを合わせて Basic 認証シークレットを作成するには、以下を実行します。

    $ 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

8.3.5. バイナリー (ローカル) ソース

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

このソースタイプは、oc start-build の使用方法に基づき使用される点で独特です。

注記

バイナリータイプのビルドでは、ローカルファイルシステムからコンテンツをストリーミングする必要があります。そのため、バイナリーファイルが提供されないので、バイナリータイプのビルドを自動的にトリガーすること (例: イメージの変更トリガーなど) はできません。同様に、Web コンソールからバイナリータイプのビルドを起動できません。

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

  • --from-file: 指定したファイルのコンテンツはバイナリーストリームとしてビルダーに送信されます。ファイルに URL を指定することもできます。次に、ビルダーはそのデータをビルドコンテキストの上に、同じ名前のファイルに保存します。
  • --from-dir および --from-repo: コンテンツはアーカイブされて、バイナリーストリームとしてバイナリーに送信され、ビルダーはビルドコンテキストディレクトリー内にアーカイブのコンテンツを展開します。--from-dir を使用すると、展開するアーカイブの URL を指定することも可能です。
  • --from-archive: 指定したアーカイブはビルダーに送信され、ビルドコンテキストディレクトリーに展開されます。このオプションは --from-dir と同様に動作しますが、このオプションの引数がディレクトリーの場合には常に、まずアーカイブがホストに作成されます。

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

  • BuildConfigBinary のソースタイプが定義されている場合には、これは事実上無視され、クライアントが送信する内容に置き換えられます。
  • BuildConfigGit のソースタイプが定義されている場合には、BinaryGit は併用できないので、動的に無効にされます。この場合、ビルダーに渡されるバイナリーストリームのデータが優先されます。

ファイル名ではなく、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 フィールドの値はアーカイブ内のサブディレクトリーと見なされます。有効な場合には、ビルド前にビルダーがサブディレクトリーに切り替わります。

8.3.6. 入力シークレット

シナリオによっては、ビルド操作で、依存するリソースにアクセスするための認証情報が必要になる場合がありますが、この認証情報がビルドが生成する最終的なアプリケーションイメージで利用可能になるのは適切ではありません。この目的の場合は、入力シークレット を定義することができます。

たとえば、Node.js アプリケーションのビルド時に、Node.js モジュールのプライベートミラーを設定できます。プライベートミラーからモジュールをダウンロードするには、URL、ユーザー名、パスワードを含む、ビルド用の .npmrc のカスタムファイルを提供する必要があります。セキュリティーの理由上、アプリケーションイメージで認証情報を公開しないようにしてください。

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

8.3.6.1. 入力シークレットの追加

既存の BuildConfig に入力シークレットを追加するには、以下を行います。

  1. シークレットがない場合は作成します。

    $ oc create secret generic secret-npmrc \
        --from-file=.npmrc=<path/to/.npmrc>

    これにより、secret-npmrc という名前の新しいシークレットが作成されます。これには、~/.npmrc ファイルの base64 でエンコードされたコンテンツが含まれます。

  2. 既存の BuildConfigsource セクションにシークレットを追加します。

    source:
      git:
        uri: https://github.com/openshift/nodejs-ex.git
      secrets:
        - secret:
            name: secret-npmrc

新しい BuildConfig にシークレットを追加するには、以下のコマンドを実行します。

$ oc new-build \
    openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git \
    --build-secret secret-npmrc

ビルド時に、.npmrc ファイルはソースコードが配置されているディレクトリーにコピーされます。OpenShift Container Platform の S2I ビルダーイメージでは、これはイメージの作業ディレクトリーで、DockerfileWORKDIR の指示を使用して設定されます。別のディレクトリーを指定するには、シークレットの定義に destinationDir を追加します。

source:
  git:
    uri: https://github.com/openshift/nodejs-ex.git
  secrets:
    - secret:
        name: secret-npmrc
      destinationDir: /etc

新規の BuildConfig を作成時に、宛先のディレクトリーを指定することも可能です。

$ oc new-build \
    openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git \
    --build-secret “secret-npmrc:/etc”

いずれの場合も、.npmrc ファイルがビルド環境の /etc ディレクトリーに追加されます。「Docker ストラテジー」の場合は、宛先のディレクトリーは相対パスでなければならない点に注意してください。

8.3.6.2. Source-to-Image ストラテジー

Source ストラテジーを使用すると、定義された入力シークレットはすべて、適切な destinationDir にコピーされます。destinationDir を空にすると、シークレットはビルダーイメージの作業ディレクトリーに配置されます。

destinationDir が相対バスの場合に同じルールが使用されます。シークレットは、イメージの作業ディレクトリーに対する相対的なパスに配置されます。destinationDir が存在しない場合には、エラーが発生します。コピーのプロセス時にディレクトリーのパスは作成されません。

注記

現在、これらのシークレットが指定されたファイルには全ユーザーに書き込み権限が割り当てられており (0666 のパーミッション)、assemble スクリプトの実行後には、サイズが 0 になるように切り捨てられます。つまり、シークレットファイルは作成されたイメージ内に存在はしますが、セキュリティーの関係上、空になります。

8.3.6.3. Docker ストラテジー

Docker ストラテジーを使用すると、DockerfileADD および COPY の命令 を使用してコンテナーイメージに定義されたすべての入力シークレットを追加できます。

シークレットの destinationDir を指定しない場合は、ファイルは、Dockerfile が配置されているのと同じディレクトリーにコピーされます。相対パスを destinationDir として指定する場合は、シークレットは、Dockerfile と相対的なディレクトリーにコピーされます。これにより、ビルド時に使用するコンテキストディレクトリーの一部として、Docker ビルド操作でシークレットファイルが利用できるようになります。

例8.1 シークレットデータを参照する Dockerfile の例

FROM centos/ruby-22-centos7

USER root
ADD ./secret-dir /secrets
COPY ./secret2 /

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

CMD ["/bin/sh", "-c", "/secret_report.sh"]
注記

通常はシークレットがイメージから実行するコンテナーに存在しないように、入力シークレットを最終的なアプリケーションイメージから削除する必要がありますが、シークレットは、追加した階層にあるイメージ自体に存在し続けます。Dockerfile 自体で、削除を行う必要があります。

8.3.6.4. カスタムストラテジー

Custom ストラテジーを使用する場合、定義された入力シークレットはすべて、/var/run/secrets/openshift.io/build ディレクトリー内のビルダーコンテナーで入手できます。カスタムのビルドイメージは、これらのシークレットを適切に使用する必要があります。また、Custom ストラテジーを使用すると、カスタムストラテジーのオプション で記載されているようにシークレットを定義できます。

既存のストラテジーのシークレットと入力シークレットには技術的な違いはありませんが、ビルダーイメージはそれぞれのシークレットを区別し、ビルドのユースケースに基づいて、異なる方法で使用する場合があります。

入力シークレットは常に /var/run/secrets/openshift.io/build ディレクトリーにマウントされます。そうでない場合には、ビルダーが完全なビルドオブジェクトを含む $BUILD 環境変数を分析できます。

8.3.7. 外部アーティファクトの使用

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

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

.s2i/bin/assemble ファイル

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

.s2i/bin/run ファイル

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

注記

Source ビルドが使用する assemble および run スクリプトを制御する方法に関する情報は、「ビルダーイメージスクリプトの上書き」を参照してください。

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

Dockerfile の抜粋

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

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

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

8.3.8. プライベートレジストリーでの Docker 認証情報の使用

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

注記

OpenShift Container Platform Docker レジストリーでは、OpenShift Container Platform が自動的にシークレットを生成するので、この作業は必要ありません。

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

auths:
  https://index.docker.io/v1/: 1
    auth: "YWRfbGzhcGU6R2labnRib21ifTE=" 2
    email: "user@example.com" 3
1
レジストリーの URL
2
暗号化されたパスワード
3
ログイン用のメールアドレス

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

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

  1. ローカルの .docker/config.json ファイルからシークレットを作成します。

    $ oc create secret generic dockerhub \
        --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
        --type=kubernetes.io/dockerconfigjson

    このコマンドにより、dockerhub という名前のシークレットの JSON 仕様が生成され、オブジェクトが作成されます。

  2. シークレットが作成されたら、これをビルダーサービスアカウントに追加します。ビルドは builder ロールで実行されるので、以下のコマンドでシークレットへのアクセスを設定する必要があります。

    $ oc secrets link builder dockerhub
  3. pushSecret フィールドを BuildConfigoutput セクションに追加し、作成した secret の名前 (上記の例では、dockerhub) に設定します。

    spec:
      output:
        to:
          kind: "DockerImage"
          name: "private.registry.com/org/private-image:latest"
        pushSecret:
          name: "dockerhub"

    oc set build-secret コマンドを使用して、ビルド設定にプッシュするシークレットを設定します。

    $ oc set build-secret --push bc/sample-build dockerhub
  4. ビルドストラテジー定義に含まれる pullSecret を指定して、プライベートの Docker レジストリーからビルダーコンテナーイメージをプルします。

    strategy:
      sourceStrategy:
        from:
          kind: "DockerImage"
          name: "docker.io/user/private_repository"
        pullSecret:
          name: "dockerhub"

    oc set build-secret コマンドを使用して、ビルド設定にプルするシークレットを設定します。

    $ oc set build-secret --pull bc/sample-build dockerhub
注記

以下の例では、ソールビルドに pullSecret を使用しますが、Docker とカスタムビルドにも該当します。

8.4. ビルド出力

8.4.1. ビルド出力の概要

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

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

ImageStreamTag への出力

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

Docker のプッシュ仕様への出力

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

8.4.2. アウトプットイメージの環境変数

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

変数説明

OPENSHIFT_BUILD_NAME

ビルドの名前

OPENSHIFT_BUILD_NAMESPACE

ビルドの namespace

OPENSHIFT_BUILD_SOURCE

ビルドのソース URL

OPENSHIFT_BUILD_REFERENCE

ビルドで使用する git 参照

OPENSHIFT_BUILD_COMMIT

ビルドで使用するソースコミット

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

8.4.3. アウトプットイメージのラベル

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

ラベル説明

io.openshift.build.commit.author

ビルドで使用するソースコミットの作者

io.openshift.build.commit.date

ビルドで使用するソースコミットの日付

io.openshift.build.commit.id

ビルドで使用するソースコミットのハッシュ

io.openshift.build.commit.message

ビルドで使用するソースコミットのメッセージ

io.openshift.build.commit.ref

ソースに指定するブランチまたは参照

io.openshift.build.source-location

ビルドのソース URL

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"

8.4.4. アウトプットイメージのダイジェスト

ビルドイメージは、ダイジェスト で一意に識別して、後に現在のタグとは無関係にこれを使用して ダイジェスト別にイメージをプル することができます。

Docker および Source ビルドは、イメージがレジストリーにプッシュされた後に Build.status.output.to.imageDigest にダイジェストを保存します。このダイジェストはレジストリーで処理されるので、レジストリーがダイジェストを返さない場合や、ビルダーイメージで形式が認識されない場合など、存在しないことがあります。

レジストリーへのプッシュに成功した後のビルドイメージのダイジェスト

status:
  output:
    to:
      imageDigest: sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912

8.4.5. プライベートレジストリーでの Docker 認証情報の使用

シークレットを使用して認証情報を指定することで、プライベートの Docker レジストリーにイメージをプッシュすることができます。方法については、「ビルド入力」を参照してください。

8.5. ビルドストラテジーのオプション

8.5.1. Source-to-Image ストラテジーのオプション

以下は、「S2I ビルドストラテジー」に固有のオプションです。

8.5.1.1. 強制プル

ビルド設定で指定したビルドイメージがノードでローカルに利用できる場合には、デフォルトではそのイメージが使用されます。ただし、ローカルイメージを上書きして、イメージストリームが参照するレジストリーからイメージを更新する場合には、forcePull フラグを true に設定して BuildConfig を作成します。

strategy:
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest" 1
    forcePull: true 2
1
使用するビルダーイメージ。ノードのローカルバージョンは、イメージストリームが参照するレジストリーのバージョンと同様の最新の状態でない可能性があります。
2
このフラグがあると、ローカルのビルダーイメージが無視され、イメージストリームが参照するレジストリーから新しいバージョンがプルされます。forcePullfalse に設定すると、デフォルトの動作として、ローカルに保存されたイメージが使用されます。

8.5.1.2. 増分ビルド

S2I は増分ビルドを実行できるので、以前にビルドされたイメージからのアーティファクトが再利用されます。増分ビルドを作成するには、ストラテジー定義に以下の変更を加えて、BuildConfig を作成します。

strategy:
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "incremental-image:latest" 1
    incremental: true 2
1
増分ビルドをサポートするイメージを指定します。この動作がサポートされているか判断するには、ビルダーイメージのドキュメントを参照してください。
2
このフラグでは、増分ビルドを試行するかどうかを制御します。ビルダーイメージで増分ビルドがサポートされていない場合は、ビルドは成功しますが、save-artifacts スクリプトがないため増分ビルドに失敗したというログメッセージが表示されます。
注記

増分ビルドをサポートするビルダーイメージを作成する方法に関する説明は、「S2I 要件」を参照してください。

8.5.1.3. ビルダーイメージのスクリプトの上書き

ビルダーイメージが提供する assemblerun および save-artifacts「S2I スクリプト」は、以下 2 種類のいずれかの方法で上書きできます。

  1. アプリケーションのソースリポジトリーの .s2i/bin ディレクトリーに assemble, run および/または save-artifacts スクリプトを指定します。
  2. 以下のように、ストラテジー定義の一部として、スクリプトを含むディレクトリーの URL を指定します。
strategy:
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest"
    scripts: "http://somehost.com/scripts_directory" 1
1
このパスに、run, assemble および save-artifacts が追加されます。一部または全スクリプトがある場合、そのスクリプトが、イメージに指定された同じ名前のスクリプトの代わりに使用されます。
注記

scripts URL に配置されているファイルは、ソースリポジトリーの .s2i/bin に配置されているファイルよりも優先されます。S2I スクリプトがどのように使用されるかについては、「S2I 要件」のトピックおよび S2I ドキュメント を参照してください。

8.5.1.4. 環境変数

「ソースビルド」のプロセスと作成されるイメージで環境変数を利用できるようにする方法は 2 種類 (環境ファイル および BuildConfig 環境 の値) あります。指定の変数は、ビルドプロセス中と、アウトプットイメージに表示されます。

8.5.1.4.1. 環境ファイル

ソースビルドでは、ソースリポジトリーの .s2i/environment ファイルに指定することで、アプリケーション内に環境の値 (1 行に 1 つ) を設定できます。このファイルで指定された環境変数は、ビルドプロセスとアウトプットイメージに存在します。サポートされる環境変数の完全な一覧は、各イメージの「ドキュメント」にあります。

ソースリポジトリーに .s2i/environment ファイルを渡すと、S2I はビルド時にこのファイルを読み取ります。これにより assemble スクリプトがこれらの変数を使用できるので、ビルドの動作をカスタマイズできます。

たとえば、Rails アプリケーションのアセットのコンパイルを無効にする場合には、.s2i/environment ファイルに DISABLE_ASSET_COMPILATION=true を追加して、ビルド時にアセットのコンパイルがスキップされるようにします。

ビルド以外に、指定の環境変数も実行中のアプリケーション自体で利用できます。たとえば、.s2i/environment ファイルに RAILS_ENV=development を追加して、Rails アプリケーションが production ではなく development モードで起動できるようにします。

8.5.1.4.2. BuildConfig 環境

環境変数を BuildConfigsourceStrategy 定義に追加できます。ここに定義されている環境変数は、assemble スクリプトの実行時に表示され、アウトプットイメージで定義されるので、run スクリプトやアプリケーションコードでも利用できるようになります。

Rails アプリケーションのアセットコンパイルを無効にする例:

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

ビルド環境 のセクションには、詳細な説明があります。

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

8.5.1.5. Web コンソールを使用したシークレットの追加

プライベートリポジトリーにアクセスできるようにビルド設定にシークレットを追加するには、以下を実行します。

  1. 新規の OpenShift Container Platform プロジェクトを作成します。
  2. プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
  3. 「Source-to-Image (S2I) ビルド設定」を作成します。
  4. ビルド設定のエディターページや、「web コンソール」fromimage ページの create app from builder image ページで ソースシークレット を設定します。
  5. Save ボタンをクリックします。
8.5.1.5.1. プルおよびプッシュの有効化

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

8.5.1.6. ソースファイルの無視

Source to image は .s2iignore ファイルをサポートします。このファイルには、無視すべきファイルパターンの一覧が含まれます。.s2iignore ファイルにあるパターンと一致する、さまざまな 入力ソース で提供されているように、ビルドの作業ディレクトリーにあるファイルは assemble スクリプトでは利用できません。

.s2iignore ファイル形式に関する詳細は、source-to-image ドキュメント を参照してください。

8.5.2. Docker ストラテジーのオプション

以下は、「Docker ビルドストラテジー」に固有のオプションです。

8.5.2.1. FROM イメージ

DockerfileFROM 命令は、BuildConfigfrom に置き換えられます。

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

8.5.2.2. Dockerfile パス

デフォルトでは Docker ビルドは BuildConfig.spec.source.contextDir フィールドで指定されたコンテキストのルートに配置されている Dockerfile (名前付きの Dockerfile) を使用します。

dockerfilePath フィールドでは、異なるパスを使用して Dockerfile の場所 (BuildConfig.spec.source.contextDir フィールドへの相対パス) を特定します。デフォルトの Dockerfile (例: MyDockerfile) とは異なる名前や、サブディレクトリーにある Dockerfile へのパス (例: dockerfiles/app1/Dockerfile) などを単純に設定できます。

strategy:
  dockerStrategy:
    dockerfilePath: dockerfiles/app1/Dockerfile

8.5.2.3. キャッシュなし

Docker ビルドは通常、ビルドを実行するホスト上のキャッシュ階層を再利用します。noCache オプションを true に設定すると、ビルドがキャッシュ階層を無視して、Dockerfile のすべての手順を再実行します。

strategy:
  dockerStrategy:
    noCache: true

8.5.2.4. 強制プル

ビルド設定で指定したビルドイメージがノードでローカルに利用できる場合には、デフォルトではそのイメージが使用されます。ただし、ローカルイメージを上書きして、イメージストリームが参照するレジストリーからイメージを更新する場合には、forcePull フラグを true に設定して BuildConfig を作成します。

strategy:
  dockerStrategy:
    forcePull: true 1
1
このフラグがあると、ローカルのビルダーイメージが無視され、イメージストリームが参照するレジストリーから新しいバージョンがプルされます。forcePullfalse に設定すると、デフォルトの動作として、ローカルに保存されたイメージが使用されます。

8.5.2.5. 環境変数

「Docker ビルド」 ロセスと作成されたイメージで環境変数を利用できるようにするには、BuildConfigdockerStrategy の定義に環境変数を追加します。

ここに定義した環境変数は、Dockerfile 内で後に参照できるように、単一の ENV Dockerfile 命令として FROM 命令の直後に挿入されます。

変数はビルド時に定義され、アウトプットイメージに残るため、そのイメージを実行するコンテナーにも存在します。

たとえば、ビルドやランタイム時にカスタムの HTTP プロキシーを定義するには以下を設定します。

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

クラスター管理者は、「Ansible を使用したグローバルなビルド設定」を実行できます。

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

8.5.2.6. Web コンソールを使用したシークレットの追加

プライベートリポジトリーにアクセスできるように、ビルド設定にシークレットを追加するには、以下を実行します。

  1. 新規の OpenShift Container Platform プロジェクトを作成します。
  2. プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
  3. 「docker のビルド設定」を作成します。
  4. ビルド設定のエディターページまたは、「web コンソール」fromimage ページで、ソースシークレット を設定します。
  5. Save ボタンをクリックします。

8.5.2.7. Docker ビルド引数

Docker ビルドの引数 を設定するには、以下のように BuildArgs 配列にエントリーを追加します。これは、BuildConfigdockerStrategy 定義の中にあります。

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

ビルドの引数は、ビルドが開始された時点で Docker に渡されます。

8.5.2.7.1. プルおよびプッシュの有効化

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

8.5.3. カスタムストラテジーのオプション

以下は、「カスタムビルドストラテジー」に固有のオプションです。

8.5.3.1. FROM イメージ

customStrategy.from セクションを使用して、カスタムビルドに使用するイメージを指定します。

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

8.5.3.2. Docker ソケットの公開

コンテナー内から Docker コマンドを実行して、コンテナーイメージをビルドできるようにするには、アクセス可能なソケットにビルドコンテナーをバインドする必要があります。これには、exposeDockerSocket オプションを true に設定します。

strategy:
  customStrategy:
    exposeDockerSocket: true

8.5.3.3. シークレット

sourceimagessecrets に加え、カスタムストラテジーを使用すると、任意のシークレット一覧をビルダー pod に追加できます。

各シークレットは、特定の場所にマウントできます。

strategy:
  customStrategy:
    secrets:
      - secretSource: 1
          name: "secret1"
        mountPath: "/tmp/secret1" 2
      - secretSource:
          name: "secret2"
        mountPath: "/tmp/secret2"
1
secretSource は、ビルドと同じ namespace にあるシークレットへの参照です。
2
mountPath は、シークレットがマウントされる必要のあるカスタムビルダー内のパスです。
8.5.3.3.1. Web コンソールを使用したシークレットの追加

プライベートリポジトリーにアクセスできるようにビルド設定にシークレットを追加するには、以下を実行します。

  1. 新規の OpenShift Container Platform プロジェクトを作成します。
  2. プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
  3. 「docker のビルド設定」を作成します。
  4. ビルド設定のエディターページまたは、「web コンソール」fromimage ページで、ソースシークレット を設定します。
  5. Save ボタンをクリックします。
8.5.3.3.2. プルおよびプッシュの有効化

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

8.5.3.4. 強制プル

ビルド Pod を設定する場合に、ビルドコントローラーはデフォルトで、ビルド設定で指定したイメージがローカルで使用できるかどうかを確認します。ローカルで利用できる場合にはそのイメージが使用されます。ただし、ローカルイメージを上書きして、イメージストリームが参照するレジストリーからイメージを更新する場合には、forcePull フラグを true に設定して BuildConfig を作成します。

strategy:
  customStrategy:
    forcePull: true 1
1
このフラグがあると、ローカルのビルダーイメージが無視され、イメージストリームが参照するレジストリーから新しいバージョンがプルされます。forcePullfalse に設定すると、デフォルトの動作として、ローカルに保存されたイメージが使用されます。

8.5.3.5. 環境変数

「カスタムビルド」のプロセスで環境変数を利用できるようにするには、環境変数を BuildConfigcustomStrategy 定義に追加します。

ここに定義された環境変数は、カスタムビルドを実行する Pod に渡されます。

たとえば、ビルド時にカスタムの HTTP プロキシーを定義するには以下を設定します。

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

クラスター管理者は、「Ansible を使用したグローバルなビルド設定」を実行できます。

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

8.5.4. Pipeline ストラテジーのオプション

以下は、「Pipeline ビルドストラテジー」に固有のオプションです。

8.5.4.1. Jenkinsfile の提供

Jenkinsfile は、以下の 2 つの方法のどちらかで提供できます。

  1. ビルド設定に Jenkinsfile を埋め込む
  2. Jenkinsfile を含む git リポジトリーへの参照をビルド設定に追加する

埋め込み定義

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')
        }

git リポジトリーへの参照

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

1
オプションの jenkinsfilePath フィールドは、ソース contextDir との関連で使用するファイルの名前を指定します。contextDir が省略される場合、デフォルトはリポジトリーの root に設定されます。jenkinsfilePath が省略される場合、デフォルトは Jenkinsfile に設定されます。

8.5.4.2. 環境変数

「Pipeline ビルド」のプロセスで環境変数を利用できるようにするには、環境変数を BuildConfigjenkinsPipelineStrategy 定義に追加します。

定義した後に、環境変数は BuildConfig に関連する Jenkins ジョブのパラメーターとして設定されます。

以下に例を示します。

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

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

8.5.4.2.1. BuildConfig 環境変数と Jenkins ジョブパラメーター間のマッピング

Pipeline ストラテジーの BuildConfig への変更に従い、Jenkins ジョブが作成/更新されると、BuildConfig の環境変数は Jenkins ジョブパラメーターの定義にマッピングされます。Jenkins ジョブパラメーター定義のデフォルト値は、関連する環境変数の現在の値になります。

Jenkins ジョブの初回作成後に、パラメーターを Jenkins コンソールからジョブに追加できます。パラメーター名は、BuildConfig の環境変数名とは異なります。上記の Jenkins ジョブ用にビルドを開始すると、これらのパラメーターが使用されます。

Jenkins ジョブのビルドを開始する方法により、パラメーターの設定方法が決まります。oc start-build で開始された場合には、BuildConfig の環境変数が対応するジョブインスタンスに設定するパラメーターになります。Jenkins コンソールからパラメーターのデフォルト値に変更を加えても無視され、BuildConfig の値が優先されます。

oc start-build -e で開始すると、-e オプションで指定した環境変数の値が優先されます。また、BuildConfig に記載されていない環境変数を指定した場合には、Jenkins ジョブのパラメーター定義として追加されます。また、Jenkins コンソールから環境変数に対応するパラメーターに対して変更を加えても無視され、BuildConfigoc start-build -e で指定した値が優先されます。

Jenkins コンソールで Jenkins ジョブを開始した場合には、ジョブのビルドを開始する操作の一環として、Jenkins コンソールを使用してパラメーターの設定を制御できます。

8.6. ビルド環境

8.6.1. 概要

Pod 環境と同様に、ビルドの環境変数は、Downward API を使用して他のリソース/変数に対する参照として定義できますが、以下に記載の例外があります。

注記

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

8.6.2. 環境変数としてのビルドフィールドの使用

ビルドオブジェクトの情報は、値を取得するフィールドの JsonPath に、fieldPath 環境変数のソースを設定することで挿入できます。

env:
  - name: FIELDREF_ENV
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
注記

Jenkins Pipeline ストラテジーは、環境変数の valueFrom 構文をサポートしません。

8.6.3. 環境変数としてのコンテナーリソースの使用

参照はコンテナーの作成前に解決されるため、ビルド環境変数の valueFrom を使用したコンテナーリソースの参照はサポートされません。

8.6.4. 環境変数としてのシークレットの使用

valueFrom 構文を使用して、シークレットからの鍵の値を環境変数として利用できます。

apiVersion: v1
kind: BuildConfig
metadata:
  name: secret-example-bc
spec:
  strategy:
    sourceStrategy:
      env:
      - name: MYVAL
        valueFrom:
          secretKeyRef:
            key: myval
            name: mysecret

8.7. ビルドのトリガー

8.7.1. ビルドトリガーの概要

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

8.7.2. Webhook のトリガー

Webhook のトリガーにより、要求を OpenShift Container Platform API エンドポイントに送信して新規ビルドをトリガーできます。GitHubGitLabBitbucket または Generic webhook を使用して、Webhook トリガーを定義できます。

OpenShift Container Platform の webhook は現在、Git ベースのソースコード管理システム (SCM) のそれぞれのプッシュイベントに似たイベントタイプのみサポートしており、その他のイベントタイプは無視されます。

プッシュイベントを処理する場合に、イベント内のブランチ参照が、対応の BuildConfig のブランチ参照と一致しているかどうか確認されます。一致する場合には、webhook イベントに記載されているのと全く同じコミット参照が、OpenShift Container Platform ビルド用にチェックアウトされます。一致しない場合には、ビルドはトリガーされません。

注記

oc new-app および oc new-build は GitHub および Generic webhook トリガーを自動的に作成しますが、それ以外の webhook トリガーが必要な場合には手動で追加する必要があります (「トリガーの設定」を参照)。

Webhook すべてに対して、WebHookSecretKey という名前のキーで、Secret と、Webook の呼び出し時に提供される値を定義する必要があります。webhook の定義で、このシークレットを参照する必要があります。このシークレットを使用することで URL が一意となり、他の URL でビルドがトリガーされないようにします。キーの値は、webhook の呼び出し時に渡されるシークレットと比較されます。

たとえば、mysecret という名前のシークレットを参照する GitHub webhook は以下のとおりです。

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

次に、シークレットは以下のように定義します。シークレットの値は base64 エンコードされており、この値は Secret オブジェクトの data フィールドに必要である点に注意してください。

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

8.7.2.1. GitHub Webhook

GitHub webhook は、リポジトリーの更新時に GitHub からの呼び出しを処理します。トリガーを定義するときに、secret を定義してください。このシークレットは、webhook の設定時に GitHub に渡される URL に追加されます。

GitHub webhook の定義例:

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

webhook トリガーの設定で使用されるシークレットは、GitHub UI で webhook 設定時に表示される secret フィールドとは異なります。Webhook トリガー設定で使用するシークレットは、webhook URL を一意にして推測ができないようにし、GitHub UI のシークレットは、任意の文字列フィールドで、このフィールドを使用して本体の HMAC hex ダイジェストを作成して、X-Hub-Signature ヘッダー として送信します。

oc describe コマンドは、ペイロード URL を GitHub Webhook URL として返します (「Webhook URL の表示 参照)。ペイロード URL は以下のような構成です。

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

GitHub Webhook を設定するには以下を実行します。

  1. GitHub リポジトリーから BuildConfig を作成した後に、以下を実行します。

    $ oc describe bc/<name-of-your-BuildConfig>

    以下のように、上記のコマンドは webhook GitHub URL を生成します。

    <https://api.starter-us-east-1.openshift.com:443/oapi/v1/namespaces/nsname/buildconfigs/bcname/webhooks/<secret>/github>.
  2. GitHub の Web コンソールから、この URL を GitHub にカットアンドペーストします。
  3. GitHub リポジトリーで、Settings → Webhooks & Services から Add Webhook を選択します。
  4. Payload URL フィールドに、(上記と同様の) URL の出力を貼り付けます。
  5. Content Type を GitHub のデフォルト application/x-www-form-urlencoded から application/json に変更します。
  6. Add webhook をクリックします。

webhook の設定が正常に完了したことを示す GitHub のメッセージが表示されます。

これで変更を GitHub リポジトリーにプッシュするたびに新しいビルドが自動的に起動し、ビルドに成功すると新しいデプロイメントが起動します。

注記

Gogs は、GitHub と同じ webhook のペイロードと同じ形式をサポートします。そのため、Gogs サーバーを使用する場合は、GitHub webhook トリガーを BuildConfig に定義すると、Gogs サーバー経由でもトリガーされます。

payload.json などの有効な JSON ペイロードがファイルに含まれる場合には、curl を使用して webhook を手動でトリガーできます。

$ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

-k の引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。

8.7.2.2. GitLab Webhook

GitLab webhook は、リポジトリーの更新時の GitLab による呼び出しを処理します。GitHub トリガーでは、secret を指定する必要があります。以下の例は、BuildConfig 内のトリガー定義の YAML です。

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

oc describe コマンドは、ペイロード URL を GitLab Webhook URL として返します (「Webhook URL の表示 参照)。ペイロード URL は以下のような構成です。

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

GitLab Webhook を設定するには以下を実行します。

  1. ビルド設定を記述して、webhook URL を取得します。

    $ oc describe bc <name>
  2. webhook URL をコピーします。<secret> はシークレットの値に置き換えます。
  3. GitLab の設定手順 に従い、GitLab リポジトリーの設定に webhook URL を貼り付けます。

payload.json などの有効な JSON ペイロードがファイルに含まれる場合には、curl を使用して webhook を手動でトリガーできます。

$ curl -H "X-GitLab-Event: Push Hook" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab

-k の引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。

8.7.2.3. Bitbucket Webhook

Bitbucket webhook リポジトリーの更新時の Bitbucket による呼び出しを処理します。これまでのトリガーと同様に、secret を指定する必要があります。以下の例は、BuildConfig 内のトリガー定義の YAML です。

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

oc describe コマンドは、ペイロード URL を Bitbucket Webhook URL として返します (「Webhook URL の表示 参照)。ペイロード URL は以下のような構成です。

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

Bitbucket Webhook を設定するには以下を実行します。

  1. ビルド設定を記述して、webhook URL を取得します。

    $ oc describe bc <name>
  2. webhook URL をコピーします。<secret> はシークレットの値に置き換えます。
  3. Follow the Bitbucket の設定手順 に従い、Bitbucket リポジトリーの設定に webhook URL を貼り付けます。

payload.json などの有効な JSON ペイロードがファイルに含まれる場合には、curl を使用して webhook を手動でトリガーできます。

$ curl -H "X-Event-Key: repo:push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket

-k の引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。

8.7.2.4. Generic Webhook

Generic webhook は、Web 要求を実行できるシステムから呼び出されます。他の webhook と同様に、シークレットを指定する必要があります。シークレットは、呼び出し元がビルドのトリガーに使用する必要のある URL の一部となります。このシークレットを使用することで URL が一意となり、他の URL でビルドがトリガーされないようにします。以下の例は、BuildConfig 内のトリガー定義の YAML です。

type: "Generic"
generic:
  secretReference:
    name: "mysecret"
  allowEnv: true 1
1
true に設定して、Generic Webhook が環境変数で渡させるようにします。

呼び出し元を設定するには、呼び出しシステムに、ビルドの Generic Webhook エンドポイントの URL を指定します。

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

呼び出し元は、POST 操作として Webhook を呼び出す必要があります。

手動で webhook を呼び出すには、curl を使用します。

$ curl -X POST -k https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

HTTP verb は POST に設定する必要があります。セキュアでない -k フラグを指定して、証明書の検証を無視します。クラスターに正しく署名された証明書がある場合には、2 つ目のフラグは必要ありません。

エンドポイントは、以下の形式で任意のペイロードを受け入れることができます。

git:
  uri: "<url to git repository>"
  ref: "<optional git reference>"
  commit: "<commit hash identifying a specific git commit>"
  author:
    name: "<author name>"
    email: "<author e-mail>"
  committer:
    name: "<committer name>"
    email: "<committer e-mail>"
  message: "<commit message>"
env: 1
   - name: "<variable name>"
     value: "<variable value>"
1
BuildConfig の環境変数 と同様に、ここで定義されている環境変数は、ビルドで利用できます。これらの変数が BuildConfig の環境変数と競合する場合には、これらの変数が優先されます。デフォルトでは、webhook 経由で渡された環境変数は無視されます。Webhook 定義の allowEnv フィールドを true に設定して、この動作を有効にします。

curl を使用してこのペイロードを渡すには、payload_file.yaml という名前のファイルにペイロードを定義して実行します。

$ curl -H "Content-Type: application/yaml" --data-binary @payload_file.yaml -X POST -k https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

引数は、ヘッダーとペイロードを追加した以前の例と同じです。 -H の引数は、ペイロードの形式により Content-Type ヘッダーを application/yaml または application/json に設定します。--data-binary の引数を使用すると、POST 要求では、改行を削除せずにバイナリーペイロードを送信します。

注記

OpenShift Container Platform は、要求のペイロードが無効な場合でも (例: 無効なコンテンツタイプ、解析不可能または無効なコンテンツなど)、Generic Webhook 経由でビルドをトリガーできます。この動作は、後方互換性を確保するために継続されています。無効な要求ペイロードがある場合には、OpenShift Container Platform は、HTTP 200 OK 応答の一部として JSON 形式で警告を返します。

8.7.2.5. Webhook URL の表示

以下のコマンドを使用して、ビルド設定に関連する webhook URL を表示します。

$ oc describe bc <name>

上記のコマンドで webhook URL が表示されない場合には、対象のビルド設定に webhook トリガーが定義されていないことになります。トリガーの設定 を参照して、トリガーを手動で追加してください。

8.7.3. イメージ変更のトリガー

イメージ変更のトリガーを使用すると、アップストリームで新規バージョンが利用できるようになるとビルドが自動的に呼び出されます。たとえば、RHEL イメージ上にビルドが設定されている場合には、RHEL のイメージが変更された時点でビルドの実行をトリガーできます。その結果、アプリケーションイメージは常に最新の RHEL ベースイメージ上で実行されるようになります。

イメージ変更のトリガーを設定するには、以下のアクションを実行する必要があります。

  1. トリガーするアップストリームイメージを参照するように、ImageStream を定義します。

    kind: "ImageStream"
    apiVersion: "v1"
    metadata:
      name: "ruby-20-centos7"

    この定義では、イメージストリームが <system-registry>/<namespace>/ruby-20-centos7 に配置されているコンテナーイメージリポジトリーに紐付けられます。<system-registry> は、OpenShift Container Platform で実行する docker-registry の名前で、サービスとして定義されます。

  2. イメージストリームがビルドのベースイメージの場合には、ビルドストラテジーの From フィールドを設定して、イメージストリームを参照します。

    strategy:
      sourceStrategy:
        from:
          kind: "ImageStreamTag"
          name: "ruby-20-centos7:latest"

    上記の例では、sourceStrategy の定義は、この namespace 内に配置されている ruby-20-centos7 という名前のイメージストリームの latest タグを使用します。

  3. イメージストリームを参照する 1 つまたは複数のトリガーでビルドを定義します。

    type: "imageChange" 1
    imageChange: {}
    type: "imagechange" 2
    imageChange:
      from:
        kind: "ImageStreamTag"
        name: "custom-image:latest"
    1
    ビルドストラテジーの from フィールドに定義されたように ImageStream および Tag を監視するイメージ変更トリガー。ここの imageChange オブジェクトは空でなければなりません。
    2
    任意のイメージストリームを監視するイメージ変更トリガー。この例に含まれる imageChange の部分には from フィールドを追加して、監視する ImageStreamTag を参照させる必要があります。

ストラテジーイメージストリームにイメージ変更トリガーを使用する場合は、生成されたビルドに不変な Docker タグが付けられ、そのタグに対応する最新のイメージを参照させます。この新規イメージ参照は、ビルド用に実行するときに、ストラテジーにより使用されます。

ストラテジーイメージストリームを参照しない、他のイメージ変更トリガーの場合は、新規ビルドが開始されますが、一意のイメージ参照で、ビルドストラテジーは更新されません。

ストラテジーにイメージ変更トリガーが含まれる上記の例では、作成されるビルドは以下のようになります。

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

これにより、トリガーされたビルドは、リポジトリーにプッシュされたばかりの新しいイメージを使用して、ビルドが同じインプットでいつでも再実行できるようにします。

カスタムビルドの場合、すべての Strategy タイプにイメージフィールドを設定するだけでなく、OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE の環境変数もチェックされます。この環境変数が存在しない場合は、不変のイメージ参照で作成されます。存在する場合には、この不変のイメージ参照で更新されます。

ビルドが webhook トリガーまたは手動の要求でトリガーされた場合に、作成されるビルドは、Strategy が参照する ImageStream から解決する <immutableid> を使用します。これにより、簡単に再現できるように、一貫性のあるイメージタグを使用してビルドが実行されるようになります。

注記

v1 Docker レジストリー のコンテナーイメージを参照するイメージストリームは、「イメージストリームタグ」が利用できるようになった時点でビルドが 1 度だけトリガーされ、後続のイメージ更新ではトリガーされません。これは、v1 Docker レジストリーに一意で識別可能なイメージがないためです。

8.7.4. 設定変更のトリガー

設定変更のトリガーは、BuildConfig がされると同時に自動的にビルドが呼び出されます。以下の例は、BuildConfig 内のトリガー定義の YAML です。

  type: "ConfigChange"
注記

設定変更のトリガーは新しい BuildConfig が作成された場合のみ機能します。今後のリリースでは、設定変更トリガーは、BuildConfig が更新されるたびにビルドを起動できるようになります。

8.7.4.1. トリガーの手動設定

トリガーは、oc set triggers でビルド設定に対して追加/削除できます。たとえば、GitHub webhook トリガーをビルド設定に追加するには以下を使用します。

$ oc set triggers bc <name> --from-github

イメージ変更トリガーを設定するには以下を使用します。

$ oc set triggers bc <name> --from-image='<image>'

トリガーを削除するには --remove を追加します。

$ oc set triggers bc <name> --from-bitbucket --remove
注記

webhook トリガーがすでに存在する場合には、トリガーをもう一度追加すると、webhook のシークレットが再生成されます。

詳細情報は、oc set triggers --help のヘルプドキュメントを参照してください。

8.8. ビルドフック

8.8.1. ビルドフックの概要

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

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

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

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

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

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

8.8.2. コミット後のビルドフックの設定

ビルド後のフックを設定する方法は複数あります。以下の例に出てくるすべての形式は同等で、bundle exec rake test --verbose を実行します。

  • シェルスクリプト:

    postCommit:
      script: "bundle exec rake test --verbose"

    script の値は、/bin/sh -ic で実行するシェルスクリプトです。上記のように単体テストを実行する場合など、シェルスクリプトがビルドフックの実行に適している場合に、これを使用します。イメージのエントリーポイントを制御するか、イメージに /bin/sh がない場合に、command and/or args を使用します。

    注記

    CentOS や RHEL イメージでの作業を改善するために、追加で -i フラッグが導入されましたが、今後のリリースで削除される可能性があります。

  • イメージエントリーポイントとしてのコマンド:

    postCommit:
      command: ["/bin/bash", "-c", "bundle exec rake test --verbose"]

    この形式では command は、実行するコマンドで、Dockerfile 参照 に記載されている、実行形式のイメージエントリーポイントを上書きします。Command は、イメージに /bin/sh がない、またはシェルを使用しない場合に必要です。他の場合は、script を使用するほうが便利でしょう。

  • デフォルトのエントリーポイントに渡す引数:

    postCommit:
      args: ["bundle", "exec", "rake", "test", "--verbose"]

    この形式では、args はイメージのデフォルトエントリーポイントに渡される引数一覧です。イメージのエントリーポイントは、引数を処理できる必要があります。

  • 引数を指定したシェルスクリプト:

    postCommit:
      script: "bundle exec rake test $1"
      args: ["--verbose"]

    引数を渡す必要があるが、シェルスクリプトで正しく引用するのが困難な場合に、この形式を使用します。上記の script では、$0 は "/bin/sh" で、$1$2 などは args の位置引数となります。

  • 引数のあるコマンド:

    postCommit:
      command: ["bundle", "exec", "rake", "test"]
      args: ["--verbose"]

    この形式は command に引数を追加するのと同じです。

注記

scriptcommand を同時に指定すると、無効なビルドフックが作成されてしまいます。

8.8.2.1. CLI の使用

oc set build-hook コマンドを使用して、ビルド設定のビルドフックを設定することができます。

コミット後のビルドフックとしてコマンドを設定します。

$ oc set build-hook bc/mybc \
    --post-commit \
    --command \
    -- bundle exec rake test --verbose

コミット後のビルドフックとしてスクリプトを設定します。

$ oc set build-hook bc/mybc --post-commit --script="bundle exec rake test --verbose"

8.9. ビルド実行ポリシー

8.9.1. ビルド実行ポリシーの概要

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

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

  • Parallel から SerialSerialLatestOnly に変更して、この設定から新規ビルドをトリガーすると、新しいビルドは並列ビルドすべてが完了するまで待機します。これは、順次ビルドは、一度に 1 つしか実行できないためです。
  • SerialSerialLatestOnly に変更して、新規ビルドをトリガーすると、現在実行中のビルドと直近で作成されたビルド以外には、キューにある既存のビルドがすべてキャンセルされます。最新のビルドが次に実行されます。

8.9.2. 順次実行ポリシー

runPolicy フィールドを Serial に設定すると、Build ビルドから作成される新しいビルドはすべて 順次実行になります。つまり、1 度に実行されるビルドは 1 つだけで、新しいビルドは、前のビルドが完了するまで待機します。このポリシーを使用すると、一貫性があり、予測可能なビルドが出力されます。これは、デフォルトの runPolicy です。

Serial ポリシーで sample-build 設定から 3 つのビルドをトリガーすると以下のようになります。

NAME             TYPE      FROM          STATUS    STARTED          DURATION
sample-build-1   Source    Git@e79d887   Running   13 seconds ago   13s
sample-build-2   Source    Git           New
sample-build-3   Source    Git           New

sample-build-1 ビルドが完了すると、sample-build-2 ビルドが実行されます。

NAME             TYPE      FROM          STATUS    STARTED          DURATION
sample-build-1   Source    Git@e79d887   Completed 43 seconds ago   34s
sample-build-2   Source    Git@1aa381b   Running   2 seconds ago    2s
sample-build-3   Source    Git           New

8.9.3. SerialLatestOnly 実行ポリシー

runPolicy フィールドを SerialLatestOnly に設定すると、Serial 実行ポリシーと同様に、Build 設定から作成される新規ビルドすべてが順次実行されます。相違点は、現在実行中のビルドの完了後に、実行される次のビルドが作成される最新ビルドになるという点です。言い換えると、キューに入っているビルドはスキップされるので、これらの実行を待機しないということです。スキップされたビルドは Cancelled としてマークされます。このポリシーは、反復的な開発を迅速に行う場合に使用できます。

SerialLatestOnly ポリシーで sample-build 設定から 3 つのビルドをトリガーすると以下のようになります。

NAME             TYPE      FROM          STATUS    STARTED          DURATION
sample-build-1   Source    Git@e79d887   Running   13 seconds ago   13s
sample-build-2   Source    Git           Cancelled
sample-build-3   Source    Git           New

sample-build-2 のビルドはキャンセル (スキップ) され、sample-build-1 の完了後に、sample-build-3 ビルドが次のビルドとして実行されます。

NAME             TYPE      FROM          STATUS    STARTED          DURATION
sample-build-1   Source    Git@e79d887   Completed 43 seconds ago   34s
sample-build-2   Source    Git           Cancelled
sample-build-3   Source    Git@1aa381b   Running   2 seconds ago    2s

8.9.4. 並列実行ポリシー

runPolicy フィールドを Parallel に設定すると、Build 設定から作成される新規ビルドはすべて並列で実行されます。この設定では、最初に作成されるビルドが完了するのが最後になる可能性があり、最新のイメージで生成され、プッシュされたコンテナーイメージが先に完了してしまい、置き換わる可能性があるので、結果が予想できません。

ビルドの完了する順番が問題とはならない場合には、並列実行ポリシーを使用してください。

Parallel ポリシーで sample-build 設定から 3 つのビルドをトリガーすると、3 つのビルドが同時に実行されます。

NAME             TYPE      FROM          STATUS    STARTED          DURATION
sample-build-1   Source    Git@e79d887   Running   13 seconds ago   13s
sample-build-2   Source    Git@a76d881   Running   15 seconds ago   3s
sample-build-3   Source    Git@689d111   Running   17 seconds ago   3s

完了する順番は保証されません。

NAME             TYPE      FROM          STATUS    STARTED          DURATION
sample-build-1   Source    Git@e79d887   Running   13 seconds ago   13s
sample-build-2   Source    Git@a76d881   Running   15 seconds ago   3s
sample-build-3   Source    Git@689d111   Completed 17 seconds ago   5s

8.10. 高度なビルド操作

8.10.1. ビルドリソースの設定

デフォルトでは、ビルドは、メモリーや CPU など、バインドされていないリソースを使用して Pod により完了されます。プロジェクトのデフォルトのコンテナー制限に、リソースの制限を指定すると、これらのリソースを制限できます。

ビルド設定の一部にリソース制限を指定して、リソースの使用を制限することも可能です。以下の例では、resourcescpu および memory の各パラメーターはオプションです。

apiVersion: "v1"
kind: "BuildConfig"
metadata:
  name: "sample-build"
spec:
  resources:
    limits:
      cpu: "100m" 1
      memory: "256Mi" 2
1
cpu は CPU のユニットで、100m は 0.1 CPU ユニット (100 * 1e-3) を表します。
2
memory はバイト単位です。256Mi は 268435456 バイトを表します (256 * 2 ^ 20)。

ただし、「クォータ」がプロジェクトに定義されている場合には、以下の 2 つの項目のいずれかが必要です。

  • 明示的な requests で設定した resources セクション :

    resources:
      requests: 1
        cpu: "100m"
        memory: "256Mi"
    1
    requests オブジェクトは、クォータ内のリソース一覧に対応するリソース一覧を含みます。
  • プロジェクトに定義されている「制限の範囲」LimitRange オブジェクトからのデフォルト値がビルドプロセス時に作成される Pod に適用されます。

適用されない場合は、クォータ基準を満たさないために失敗したというメッセージが出され、ビルド Pod の作成は失敗します。

8.10.2. 最長期間の設定

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

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

以下の例は BuildConfig の一部で、completionDeadlineSeconds フィールドを 30 分に指定しています。

spec:
  completionDeadlineSeconds: 1800
注記

この設定は、Pipeline ストラテジーオプションではサポートされていません。

8.10.3. 特定のノードへのビルドの割り当て

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

apiVersion: "v1"
kind: "BuildConfig"
metadata:
  name: "sample-build"
spec:
  nodeSelector:1
    key1: value1
    key2: value2
1
このビルド設定に関連するビルドは、key1=value2key2=value2 ラベルが指定されたノードでのみ実行されます。

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

詳細情報は、「グローバルビルドのデフォルト設定および上書きの設定」を参照してください。

注記

指定の NodeSelector がこれらのラベルが指定されているノードに一致しない場合には、ビルドは Pending の状態が無限に続きます。

8.10.4. チェーンビルド

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

これらの問題を回避するには、2 つのビルドをチェーンでつなげることができます。1 つ目のビルドでコンパイルしたアーティファクトを作成し、2 つ目のビルドで、アーティファクトを実行する別のイメージにそのアーティファクトを配置します。「Source-to-Image」ビルドは「Docker」ビルドと組み合わせて、アーティファクトをコンパイルし、別のランタイムイメージに配置します。

注記

この例では、Source-to-Image ビルドと Docker ビルドをチェーンでつないでいますが、1 つ目のビルドは、任意のアーティファクトを含むイメージを生成するストラテジーを使用し、2 つ目のビルドは、イメージからの入力コンテンツを使用可能なストラテジーを使用できます。

Chained Build

最初のビルドは、アプリケーションソースを取得して、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
    type: Git
  strategy:
    sourceStrategy:
      from:
        kind: ImageStreamTag
        name: wildfly:10.1
        namespace: openshift
    type: Source

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

apiVersion: v1
kind: BuildConfig
metadata:
  name: image-build
spec:
  output:
    to:
      kind: ImageStreamTag
      name: image-build:latest
  source:
    type: Dockerfile
    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
    type: Docker
  triggers:
  - imageChange: {}
    type: ImageChange
1
from は、Docker ビルドに、以前のビルドのターゲットであった artifact-image イメージストリームからのイメージの出力を追加する必要があることを指定します。
2
paths は、現在の Docker ビルドに追加するターゲットイメージからのパスを指定します。
3
ランタイムのイメージは、Docker ビルドのソースイメージとして使用します。

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

8.10.5. ビルドのプルーニング

デフォルトでは、ライフサイクルが完了したビルドは、無限に永続します。以下のビルド設定例にあるように、successfulBuildsHistoryLimit または failedBuildsHistoryLimit を正の整数に指定すると、以前のビルドを保持する数を制限することができます。

apiVersion: "v1"
kind: "BuildConfig"
metadata:
  name: "sample-build"
spec:
  successfulBuildsHistoryLimit: 2 1
  failedBuildsHistoryLimit: 2 2
1
successfulBuildsHistoryLimit は、completed のステータスのビルドを最大 2 つまで保持します。
2
failedBuildsHistoryLimit はステータスが failedcancelled または error のビルドを最大 2 つまで保持します。

ビルドプルーニングは、以下のアクションによりトリガーされます。

  • ビルド設定が更新された場合
  • ビルドのライフサイクルが完了した場合

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

注記

管理者は、「'oc adm' オブジェクトのプルーニングコマンド」を使用して、ビルドを手動でプルーニングできます。

8.11. ビルドのトラブルシューティング

8.11.1. 拒否されたリソースへのアクセス要求

問題

ビルドが以下のエラーで失敗します。

requested access to the resource is denied
解決策

プロジェクトに設定されている イメージのクォータ のいずれからの上限を超えています。現在のクォータを確認して、適用されている制限数と、使用中のストレージを確認してください。

$ oc describe quota

第9章 デプロイメント

9.1. デプロイメントの仕組み

9.1.1. デプロイメントの概要

OpenShift Container Platform デプロイメントでは、一般的なユーザーアプリケーションに対して詳細にわたる管理ができます。デプロイメントは、3 つの異なる API オブジェクトを使用して記述します。

  • デプロイメント設定。Pod テンプレートとして、アプリケーションの特定のコンポーネントに対する任意の状態を記述します。
  • 1 つまたは複数のレプリケーションコントローラー。このコントローラーには、Pod テンプレートとしてデプロイメント設定のある時点の状態が含まれます。
  • 1 つまたは複数の Pod。特定バージョンのアプリケーションのインスタンスを表します。
重要

デプロイメント設定が所有するレプリケーションコントローラーまたは Pod を操作する必要はありません。デプロイメントシステムにより、デプロイメント設定への変更は適切に伝搬されます。既存のデプロイメントストラテジーがユースケースに適さない場合や、デプロイメントのライフサイクルで手動の手順を実行する必要がある場合には、「カスタムストラテジー」の作成を検討してください。

デプロイメント設定を作成すると、レプリケーションコントローラーが、デプロイメント設定の Pod テンプレートとして作成されます。デプロイメント設定が変更されると、最新の Pod テンプレートで新しいレプリケーションコントローラーが作成され、デプロイメントプロセスが実行され、以前のレプリケーションコントローラーにスケールダウンされるか、新しいレプリケーションコントローラーにスケールアップされます。

アプリケーションのインスタンスは、作成時に、サービスローダーバランサーやルーターに対して自動的に追加/削除されます。アプリケーションが 正常なシャットダウン機能 をサポートしている限り、アプリケーションが TERM シグナルを受け取ると、実行中のユーザー接続が通常通り完了できるようにすることができます。

デプロイメントシステムで提供される機能:

  • 実行中のアプリケーションのテンプレートとなる デプロイメント設定
  • イベントに対応するために自動デプロイメントを駆動するトリガー
  • 以前のバージョンから新しいバージョンに移行するための、ユーザーによるカスタマイズが可能な ストラテジー。ストラテジーは、デプロイメントプロセスと一般的に呼ばれる Pod 内で実行されます。
  • デプロイメントのライフサイクル中のさまざまなポイントで、カスタムの動作を実行するための フック セット。
  • デプロイメントが失敗した場合に手動または自動で ロールバック ができるようにするためのアプリケーションのバージョン。
  • 手動のレプリケーションのスケーリング および 自動スケーリング

9.1.2. デプロイメント設定の作成

デプロイメント設定は、OpenShift Container Platform API リソースの deploymentConfig で、他のリソースのように oc コマンドで管理できます。以下は、deploymentConfig リソースの例です。

kind: "DeploymentConfig"
apiVersion: "v1"
metadata:
  name: "frontend"
spec:
  template: 1
    metadata:
      labels:
        name: "frontend"
    spec:
      containers:
        - name: "helloworld"
          image: "openshift/origin-ruby-sample"
          ports:
            - containerPort: 8080
              protocol: "TCP"
  replicas: 5 2
  triggers:
    - type: "ConfigChange" 3
    - type: "ImageChange" 4
      imageChangeParams:
        automatic: true
        containerNames:
          - "helloworld"
        from:
          kind: "ImageStreamTag"
          name: "origin-ruby-sample:latest"
  strategy: 5
    type: "Rolling"
  paused: false 6
  revisionHistoryLimit: 2 7
  minReadySeconds: 0 8
1
単純な Ruby アプリケーションを記述する frontend デプロイメント設定
2
frontend のレプリカは 5 つとなります。
3
pod テンプレートが変更されるたびに、新規レプリケーションコントローラーが作成されるようにする 設定変更トリガー
4
origin-ruby-sample:latest イメージストリームタグの新規バージョンが利用できるようになると、新しいレプリケーションコントローラーが作成されるようにする イメージ変更トリガー
5
ローリングストラテジー。このストラテジーは、pod をデプロイするデフォルトの方法で、省略可能です。
6
デプロイメント設定を一時停止します。これにより、すべてのトリガー機能が無効になり、実際にロールアウトされる前に pod テンプレートに複数の変更を加えることができます。
7
改訂履歴の制限。ロールバック用に保持する、以前のレプリケーションコントローラー数の上限で、省略可能です。省略した場合には、以前のレプリケーションコントローラーは消去されません。
8
(Readiness チェックにパスした後) pod が利用可能とみなされるまでに待機する最低期間 (秒)。デフォルト値は 0 です。

9.2. 基本のデプロイメント操作

9.2.1. デプロイメントの開始

Web コンソールまたは CLI を使用して手動で新規デプロイメントプロセスを開始できます。

$ oc rollout latest dc/<name>
注記

デプロイメントプロセスが進行中の場合には、このコマンドを実行すると、メッセージが表示され、新規レプリケーションコントローラーがデプロイされません。

9.2.2. デプロイメントの表示

アプリケーションで利用可能な全リビジョンの基本情報を取得します。

$ oc rollout history dc/<name>

このコマンドでは、現在実行中のデプロイメントプロセスなど、指定したデプロイメント設定用に、最近作成されたすべてのレプリケーションコントローラーの詳細を表示します。

--revision フラグを使用すると、リビジョン固有の詳細情報が表示されます。

$ oc rollout history dc/<name> --revision=1

デプロイメント設定および最新のリビジョンに関する詳細情報は、以下を実行してください。

$ oc describe dc <name>
注記

「Web コンソール」では、Browse タブにデプロイメントが表示されます。

9.2.3. デプロイメントのロールバック

ロールバックすると、アプリケーションを以前のリビジョンに戻します。この操作は、REST API、CLI または Web コンソールで実行できます。

最後にデプロイして成功した設定のリビジョンにロールバックするには以下を実行します。

$ oc rollout undo dc/<name>

デプロイして設定にテンプレートは、undo コマンドで指定してデプロイメントのリビジョンと一致するように元に戻され、新しいレプリケーションコントローラーが起動します。--to-revision でリビジョンが指定されていない場合には、最後に成功したデプロイメントのバージョンが使用されます。

ロールバックの完了直後に新規デプロイメントプロセスが誤って開始されないように、ロールバックの一部として、デプロイメント設定のイメージ変更トリガーは無効になります。イメージ変更トリガーをもう一度有効にするには、以下を実行します。

$ oc set triggers dc/<name> --auto
注記

最新のデプロイメントプロセスに失敗した場合に、デプロイメント設定は、最後に成功したリビジョンの設定に自動的にロールバックする機能をサポートします。この場合に、デプロイに失敗した最新のテンプレートはシステムで修正されないので、設定の修正はユーザーが行う必要があります。

9.2.4. コンテナー内でのコマンドの実行

コンテナーにコマンドを追加して、イメージの ENTRYPOINT を却下して、コンテナーの起動動作を変更することができます。これは、指定したタイミングでデプロイメントごとに 1 回実行できる ライフサイクルフック とは異なります。

command パラメーターを、デプロイメントの spec フィールドを追加します。commandコマンドを変更する args フィールドも追加できます (または command コマンドが存在しない場合には、ENTRYPOINT)。

...
spec:
  containers:
    -
    name: <container_name>
    image: 'image'
    command:
      - '<command>'
    args:
      - '<argument_1>'
      - '<argument_2>'
      - '<argument_3>'
...

たとえば、-jar および /opt/app-root/springboots2idemo.jar 引数を指定して、java コマンドを実行します。

...
spec:
  containers:
    -
    name: example-spring-boot
    image: 'image'
    command:
      - java
    args:
      - '-jar'
      - /opt/app-root/springboots2idemo.jar
...

9.2.5. デプロイメントログの表示

指定のデプロイメント設定に関する最新リビジョンのログをストリームします。

$ oc logs -f dc/<name>

最新のリビジョンが実行中または失敗した場合には、oc logs は、pod のデプロイを行うプロセスのログが返されます。成功した場合には、oc logs は、アプリケーションの pod からのログを返します。

以前に失敗したデプロイメントプロセスからのログを表示することも可能です。ただし、これらのプロセス (以前のレプリケーションコントローラーおよびデプロイヤーの Pod) が存在し、手動でプルーニングまたは削除されていない場合に限ります。

$ oc logs --version=1 dc/<name>

ログの取得に関する他のオプションについては、以下を参照してください。

$ oc logs --help

9.2.6. デプロイメントトリガーの設定

デプロイメント設定には、クラスター内のイベントに対応する新規デプロイメントプロセスの作成を駆動するトリガーを含めることができます。

警告

トリガーがデプロイメント設定に定義されていない場合は、ConfigChange トリガーがデフォルトで追加されます。トリガーが空のフィールドとして定義されている場合には、デプロイメントは 手動で起動 する必要があります。

9.2.6.1. 設定変更トリガー

ConfigChange トリガーにより、デプロイメント設定の Pod テンプレートに変更があると検出されるたびに、新規のレプリケーションコントローラーが作成されます。

注記

ConfigChange トリガーがデプロイメント設定に定義されている場合は、デプロイメント設定自体が作成された直後に、最初のレプリケーションコントローラーは自動的に作成され、一時停止されません。

例9.1 ConfigChange トリガー

triggers:
  - type: "ConfigChange"

9.2.6.2. ImageChange トリガー

ImageChange トリガーにより、「イメージストリームタグ」の内容が変更されるたびに、(イメージの新規バージョンがプッシュされるタイミングで) 新規レプリケーションコントローラーが作成されます。

例9.2 ImageChange トリガー

triggers:
  - type: "ImageChange"
    imageChangeParams:
      automatic: true 1
      from:
        kind: "ImageStreamTag"
        name: "origin-ruby-sample:latest"
        namespace: "myproject"
      containerNames:
        - "helloworld"
1
imageChangeParams.automatic フィールドが false に設定されると、トリガーが無効になります。

上記の例では、origin-ruby-sample イメージストリームの latest タグの値が変更され、新しいイメージの値がデプロイメント設定の helloworld コンテナーに指定されている現在のイメージと異なる場合に、helloworld コンテナーの新規イメージを使用して、新しいレプリケーションコントローラーが 作成されます。

注記

ImageChange とライガーがデプロイメント設定 (ConfigChange トリガーと automatic=false、または automatic=true) で定義されていて、ImageChange トリガーで参照されている ImageStreamTag がまだ存在していない場合には、ビルドにより、イメージが、ImageStreamTag にインポートまたはプッシュされた直後に初回のデプロイメントプロセスが自動的に開始されます。

9.2.6.2.1. コマンドラインの使用

oc set triggers コマンドでは、デプロイメント設定にデプロイメントトリガーを設定するために使用できます。上記の例では、次のコマンドを使用して ImageChangeTrigger を設定できます。

$ oc set triggers dc/frontend --from-image=myproject/origin-ruby-sample:latest -c helloworld

詳細は、以下を参照してください。

$ oc set triggers --help

9.2.7. デプロイメントリソースの設定

注記

このリソースは管理者が OpenShift Container Platform 3.10 でテクノロジープレビューとして提供されている一時ストレージを有効化した場合にのみ利用できます。この機能はデフォルトでは無効になっています。

デプロイメントは、ノードでリソース (メモリーおよび一時ストレージ) を消費する Pod を使用して完了します。デフォルトでは、Pod はバインドされていないノードのリソースを消費しますが、プロジェクトにデフォルトでコンテナー制限が指定されている場合には、Pod はその上限分までリソースを消費します。

デプロイメント設定の一部にリソース制限を指定して、リソースの使用を制限することも可能です。デプロイメントリソースは、Recreate (再作成)、Rolling (ローリング) または Custom (カスタム) のデプロイメントストラテジーで使用できます。

以下の例では、resourcescpumemory および ephemeral-storage はそれぞれオプションです。

type: "Recreate"
resources:
  limits:
    cpu: "100m" 1
    memory: "256Mi" 2
    ephemeral-storage: "1Gi" 3
1
cpu は CPU のユニットで、100m は 0.1 CPU ユニット (100 * 1e-3) を表します。
2
memory はバイト単位です。256Mi は 268435456 バイトを表します (256 * 2 ^ 20)。
3
ephemeral-storage はバイト単位で指定します。1Gi は 1073741824 bytes (2 ^ 30) を表します。この項目は、管理者が OpenShift Container Platform 3.10 で一時ストレージのテクノロジープレビュー機能を有効化している場合のみ該当します。

ただし、クォータがプロジェクトに定義されている場合には、以下の 2 つの項目のいずれかが必要です。

  • 明示的な requests で設定した resources セクション :

      type: "Recreate"
      resources:
        requests: 1
          cpu: "100m"
          memory: "256Mi"
          ephemeral-storage: "1Gi"
    1
    requests オブジェクトは、クォータ内のリソース一覧に対応するリソース一覧を含みます。

コンピュートリソースや、要求と制限の相違点についての詳しい情報は、「クォータと制限の範囲」を参照してください。

  • プロジェクトに定義されている「制限の範囲」LimitRange オブジェクトからのデフォルト値がデプロイメントプロセス中に作成される Pod に適用されます。

適用されない場合は、クォータ基準を満たさないために失敗したというメッセージを表示し、デプロイメントの Pod 作成は失敗します。

9.2.8. 手動のスケーリング

ロールバック以外に、Web コンソールまたは oc scale コマンドを使用して、レプリカの数を細かく管理できます。たとえば、以下のコマンドは、デプロイメント設定の frontend を 3 に設定します。

$ oc scale dc frontend --replicas=3

レプリカの数は最終的に、デプロイメント設定の frontend で設定した希望のデプロイメントの状態と現在のデプロイメントの状態に伝搬されます。

注記

Pod は oc autoscale コマンドを使用して自動スケーリングすることも可能です。詳細は「Pod の自動スケーリング」を参照してください。

9.2.9. 特定のノードへの Pod の割り当て

ラベル付きのノードと合わせてノードセレクターを使用し、Pod の割当を制御することができます。

注記

OpenShift Container Platform 管理者は、「クラスターをインストールする時」 または 「インストール後にノードを追加する時」にラベルを割り当てることができます。

クラスターの管理者は、プロジェクトに対して「デフォルトのノードセレクターを設定して」、特定のノードに Pod の配置を制限できます。OpenShift Container Platform の開発者は、Pod 設定にノードセレクターを設定して、ノードをさらに制限することができます。

Pod の作成時にノードセレクターを追加するには、Pod の設定を編集し、nodeSelector の値を追加します。以下の内容は、単一の Pod 設定や、Pod テンプレートに追加できます。

apiVersion: v1
kind: Pod
spec:
  nodeSelector:
    disktype: ssd
...

ノードセレクターの割当時に作成された Pod は、指定したラベルのノードに割り当てられます。

ここで指定したラベルは、「クラスター管理者が追加した」ラベルと併用されます。

たとえば、プロジェクトに type=user-noderegion=east のラベルがクラスター管理者により追加され、上記の disktype: ssd ラベルを Pod に追加した場合に、Pod は 3 つのラベルすべてが含まれるノードにのみスケジュールされます。

注記

ラベルには値を 1 つしか設定できないので、region=east が管理者によりデフォルト設定されている Pod 設定に region=west のノードセレクターを設定すると、Pod が全くスケジュールされなくなります。

9.2.10. 異なるサービスアカウントでの Pod の実行

デフォルト以外のサービスアカウントで Pod を実行できます。

  1. デプロイメント設定を編集します。

    $ oc edit dc/<deployment_config>
  2. serviceAccountserviceAccountName パラメーターを spec フィールドに追加し、使用するサービスアカウントを指定します。

    spec:
      securityContext: {}
      serviceAccount: <service_account>
      serviceAccountName: <service_account>

9.2.11. Web コンソールを使用してデプロイメント設定にシークレットを追加する手順

プライベートリポジトリーにアクセスできるように、デプロイメント設定にシークレットを追加します。

  1. 新規の OpenShift Container Platform プロジェクトを作成します。
  2. プライベートのイメージリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
  3. デプロイメント設定を作成します。
  4. デプロイメント設定のエディターページまたは、「web コンソール」fromimage ページで、プルシークレット を設定します。
  5. Save ボタンをクリックします。

9.3. デプロイメントストラテジー

9.3.1. デプロイメントストラテジーの概要

アプリケーションを変更またはアップグレードする手段として、デプロイメントストラテジーを使用します。デプロイメントストラテジーの目的は、ユーザーには改善が加えられていることが分からないように、ダウンタイムなしに変更を加えることです。

最も一般的なストラテジーとして blue-green デプロイメント を使用します。新規バージョン (blue バージョン) を、テストと評価用に起動しつつ、安定版 (green バージョン) をユーザーが継続して使用します。準備が整ったら、Blue バージョンに切り替えられます。問題が発生した場合には、Green バージョンに戻すことができます。

一般的な別のストラテジーとして、A/B バージョンがいずれも、同時にアクティブな状態で、A バージョンを使用するユーザーも、B ユーザーを使用するユーザーもいるという方法です。これは、ユーザーインターフェースや他の機能の変更をテストして、ユーザーのフィードバックを取得するために使用できます。また、ユーザーに対する問題の影響が限られている場合に、実稼働のコンテキストで操作が正しく行われていることを検証するのに使用することもできます。

カナリアリリースデプロイメントでは、新規バージョンをテストしますが、問題が検出されると、すぐに以前のバージョンにフォールバックされます。これは、上記のストラテジーどちらでも実行できます。

ルートベースのデプロイメントストラテジーでは、サービス内の Pod 数はスケーリングされません。希望とするパフォーマンスの特徴を維持するには、デプロイメント設定をスケーリングする必要があります。

デプロイメントストラテジーを選択する場合に、考慮するべき事項があります。

  • 長期間実行される接続は正しく処理される必要があります。
  • データベースの変換は複雑になる可能性があり、アプリケーションと共に変換し、ロールバックする必要があります。
  • アプリケーションがマイクロサービスと従来のコンポーネントを使用するハイブリッドの場合には、移行の完了時にダウンタイムが必要になる場合があります。
  • これを実行するためのインフラストラクチャーが必要です。
  • テスト環境が分離されていない場合は、新規バージョンと以前のバージョン両方が破損してしまう可能性があります。

通常、エンドユーザーはルーターが取り扱うルート経由でアプリケーションにアクセスするので、デプロイメントストラテジーは、デプロイメント設定機能またはルーティング機能にフォーカスできます。

デプロイメント設定にフォーカスするストラテジーは、アプリケーションを使用するすべてのルートに影響を与えます。ルーター機能を使用するストラテジーは個別のルートをターゲットに設定します。

デプロイメントストラテジーの多くは、デプロイメント設定でサポートされ、追加のストラテジーはルーター機能でサポートされます。このセクションでは、デプロイメント設定をベースにするストラテジーについて説明します。

ローリングストラテジー は、ストラテジーがデプロイメント設定に指定されていない場合にデフォルトで使用するストラテジーです。

デプロイメントストラテジーは、Readiness チェック を使用して、新しい Pod の使用準備ができているかを判断します。Readiness チェックに失敗すると、デプロイメント設定は、タイムアウトするまで pod の実行を再試行します。デフォルトのタイムアウトは、10m で、値は dc.spec.strategy.*paramsTimeoutSeconds で設定します。

9.3.2. ローリングストラテジー

ローリングデプロイメントは、以前のバージョンのアプリケーションインスタンスを、新しいバージョンのアプリケーションインスタンスに徐々に置き換えます。ローリングデプロイメントは、新規 Pod がreadiness チェックready になるまで待機してから、以前のコンポーネントをスケールダウンします。大きな問題が発生した場合には、ローリングデプロイメントは中断される可能性があります。

9.3.2.1. カナリアリリースデプロイメント

OpenShift Container Platform のローリングデプロイメントは、カナリアリリース デプロイメントで、新規バージョン (カナリアリリース) をテストしてから、以前の全インスタンスを置き換えます。Readiness チェックに成功しない場合には、カナリアリリースのインスタンスが削除され、デプロイメント設定は自動的にロールバックされます。Readiness チェックはアプリケーションコードの一部で、新規インスタンスの使用準備が確実に整うように、必要に応じて改善されます。より複雑なアプリケーションチェックを実装する必要がある場合には (新規インスタンスに実際のユーザーワークロードを送信するなど)、カスタムデプロイメントの実装や、blue-green デプロイメントストラテジーの使用を検討してください。

9.3.2.2. ローリングデプロイメントの使用のタイミング

  • ダウンタイムを発生させずに、アプリケーションの更新を行う場合
  • 以前のコードと新しいコードの同時実行がアプリケーションでサポートされている場合

ローリングデプロイメントとは、以前のバージョンと新しいバージョンのコードを同時に実行するという意味です。これは通常、アプリケーションで「N-1 互換性」に対応する必要があります。

以下は、ローリングストラテジーの例です。

strategy:
  type: Rolling
  rollingParams:
    updatePeriodSeconds: 1 1
    intervalSeconds: 1 2
    timeoutSeconds: 120 3
    maxSurge: "20%" 4
    maxUnavailable: "10%" 5
    pre: {} 6
    post: {}
1
各 Pod が次に更新されるまで待機する時間。指定されていない場合、デフォルト値は 1 となります。
2
更新してからデプロイメントステータスをポーリングするまでの間待機する時間。指定されていない場合、デフォルト値は 1 となります。
3
イベントのスケーリングを中断するまでの待機時間。この値はオプションです。デフォルトは 600 です。ここでの 中断 とは、自動的に以前の完全なデプロイメントにロールバックされるという意味です。
4
maxSurge はオプションで、指定されていない場合には、デフォルト値は 25% となります。以下の手順の次にある情報を参照してください。
5
maxUnavailable はオプションで、指定されていない場合には、デフォルト値は 25% となります。以下の手順の次にある情報を参照してください。
6
pre および post はいずれも ライフサイクルフック です。

ローリングストラテジーは以下を行います。

  1. pre ライフサイクルフックを実行します。
  2. サージ数に基づいて新しいレプリケーションコントローラーをスケールアップします。
  3. 最大利用不可数に基づいて以前のレプリケーションコントローラーをスケールダウンします。
  4. 新しいレプリケーションコントローラーが希望のレプリカ数に到達して、以前のレプリケーションコントローラーの数がゼロになるまで、このスケーリングを繰り返します。
  5. post ライフサイクルフックを実行します。
重要

スケールダウン時には、ローリングストラテジーは Pod の準備ができるまで待機し、スケーリングを行うことで可用性に影響が出るかどうかを判断します。Pod をスケールアップしたにもかかわらず、準備が整わない場合には、デプロイメントプロセスは最終的にタイムアウトして、デプロイメントに失敗します。

maxUnavailable パラメーターは、更新時に利用できない Pod 最大数で、maxSurge パラメーターは、元の pod 数を超えてスケジュールできる最大数のことです。いずれのパラメーターも、パーセント (例: 10%) または絶対値 (例: 2) を指定できます。これらのパラメーターのデフォルト値はいずれも、25% です。

以下のパラメーターを使用して、デプロイメントの可用性やスピードを調整できます。以下に例を示します。

  • maxUnavailable=0 および maxSurge=20% が指定されていると、更新時および急速なスケールアップ時に完全なキャパシティーが維持されるようになります。
  • maxUnavailable=10% および maxSurge=0 が指定されていると、追加のキャパシティーを使用せずに更新が実行されます (インプレース更新)。
  • maxUnavailable=10% および maxSurge=10% が指定されている場合には、キャパシティーが一部失われる可能性がありますが、迅速にスケールアップおよびスケールダウンを行います。

一般的に、迅速にロールアウトする場合は maxSurge を使用します。リソースのクォータを考慮して、一部に利用不可の状態が発生してもかまわない場合には、maxUnavailable を使用します。

9.3.2.3. ローリングの例

OpenShift Container Platform では、ローリングデプロイメントはデフォルト設定です。ローリングアップデートを行うには、以下の手順に従います。

  1. DockerHub にあるデプロイメントイメージの例を基にアプリケーションを作成します。

    $ oc new-app openshift/deployment-example

    ルーターをインストールしている場合は、ルートを使用してアプリケーションを利用できるようにしてください (または、サービス IP を直接使用してください)。

    $ oc expose svc/deployment-example

    deployment-example.<project>.<router_domain> でアプリケーションを参照し、v1 イメージが表示されることを確認します。

  2. レプリカが最大 3 つになるまで、デプロイメント設定をスケーリングします。

    $ oc scale dc/deployment-example --replicas=3
  3. 新しいバージョンの例を latest とタグ付けして、新規デプロイメントを自動的にトリガーします。

    $ oc tag deployment-example:v2 deployment-example:latest
  4. ブラウザーで、v2 イメージが表示されるまでページを更新します。
  5. CLI を使用している場合は、以下のコマンドで、バージョン 1 に Pod がいくつあるか、バージョン 2 にはいくつあるかを表示します。Web コンソールでは、徐々に v2 に追加される Pod、v1 から削除される Pod が確認できるはずです。

    $ oc describe dc deployment-example

デプロイメントプロセスで、新しいレプリケーションコントローラーが漸増的にスケールアップします。新しい Pod が (readiness チェックをパスして) ready とマークされたら、デプロイメントプロセスが継続されます。Pod の準備が整わない場合には、プロセスが中断され、デプロイメント設定が以前のバージョンにロールバックされます。

9.3.3. 再作成ストラテジー

再作成ストラテジーは、基本的なロールアウト動作で、デプロイメントプロセスにコードを挿入する ライフサイクルフック をサポートします。

以下は、再作成ストラテジーの例です。

strategy:
  type: Recreate
  recreateParams: 1
    pre: {} 2
    mid: {}
    post: {}
1
recreateParams はオプションです。
2
premid および post は、ライフサイクルフック です。

再作成ストラテジーは以下を行います。

  1. pre ライフサイクルフックを実行します。
  2. 以前のデプロイメントをゼロにスケールダウンします。
  3. mid ライフサイクルフックを実行します。
  4. 新規デプロイメントをスケールアップします。
  5. post ライフサイクルフックを実行します。
重要

スケールアップ中に、デプロイメントのレプリカ数が複数ある場合は、デプロイメントの最初のレプリカが準備できているかどうかが検証されてから、デプロイメントが完全にスケールアップされます。最初のレプリカの検証に失敗した場合には、デプロイメントは失敗とみなされます。

9.3.3.1. 再作成デプロイメントの使用のタイミング

  • 新規コードを起動する前に、移行または他のデータの変換を行う必要がある場合
  • 以前のバージョンと新しいバージョンのアプリケーションコードの同時使用をサポートしていない場合
  • 複数のレプリカ間での共有がサポートされていない、RWO ボリュームを使用する場合

再作成デプロイメントでは、短い期間にアプリケーションのインスタンスが実行されなくなるので、ダウンタイムが発生します。ただし、以前のコードと新しいコードは同時には実行されません。

9.3.4. カスタムストラテジー

カスタムストラテジーでは、独自のデプロイメントの動作を提供できるようになります。

以下は、カスタムストラテジーの例です。

strategy:
  type: Custom
  customParams:
    image: organization/strategy
    command: [ "command", "arg1" ]
    environment:
      - name: ENV_1
        value: VALUE_1

上記の例では、organization/strategy コンテナーイメージにより、デプロイメントの動作が提供されます。オプションの command 配列は、イメージの Dockerfile で指定した CMD ディレクティブを上書きします。指定したオプションの環境変数は、ストラテジープロセスの実行環境に追加されます。

さらに、OpenShift Container Platform は以下の環境変数もデプロイメントプロセスに提供します。

環境変数説明

OPENSHIFT_DEPLOYMENT_NAME

新規デプロイメント名 (レプリケーションコントローラー)

OPENSHIFT_DEPLOYMENT_NAMESPACE

新規デプロイメントの namespace

新規デプロイメントのレプリカ数は最初はゼロです。ストラテジーの目的は、ユーザーのニーズに最適な仕方で対応するロジックを使用して新規デプロイメントをアクティブにすることにあります。

詳細は、高度なデプロイメントストラテジーを参照してください。

または customParams を使用して、カスタムのデプロイメントロジックを、既存のデプロイメントストラテジーに挿入します。カスタムのシェルロジックを指定して、openshift-deploy バイナリーを呼び出します。カスタムのデプロイヤーコンテナーイメージを用意する必要はありません。ここでは、代わりにデフォルトの OpenShift Container Platform デプロイヤーイメージが使用されます。

strategy:
  type: Rolling
  customParams:
    command:
    - /bin/sh
    - -c
    - |
      set -e
      openshift-deploy --until=50%
      echo Halfway there
      openshift-deploy
      echo Complete

このストラテジーの設定では、以下のようなデプロイメントになります。

Started deployment #2
--> Scaling up custom-deployment-2 from 0 to 2, scaling down custom-deployment-1 from 2 to 0 (keep 2 pods available, don't exceed 3 pods)
    Scaling custom-deployment-2 up to 1
--> Reached 50% (currently 50%)
Halfway there
--> Scaling up custom-deployment-2 from 1 to 2, scaling down custom-deployment-1 from 2 to 0 (keep 2 pods available, don't exceed 3 pods)
    Scaling custom-deployment-1 down to 1
    Scaling custom-deployment-2 up to 2
    Scaling custom-deployment-1 down to 0
--> Success
Complete

カスタムデプロイメントストラテジーのプロセスでは、OpenShift Container Platform API または Kubernetes API へのアクセスが必要な場合には、ストラテジーを実行するコンテナーは、認証用のコンテナーで利用可能なサービスアカウントのトークンを使用できます。

9.3.5. ライフサイクルフック

再作成 および ローリング ストラテジーは、ストラテジーで事前に定義したポイントでデプロイメントプロセスに動作を挿入できるようにするライフサイクルフックをサポートします。

以下は pre ライフサイクルフックの例です。

pre:
  failurePolicy: Abort
  execNewPod: {} 1

フックにはすべて、フックに問題が発生した場合にストラテジーが取るべきアクションを定義する failurePolicy が含まれます。

Abort

フックに失敗すると、デプロイメントプロセスも失敗とみなされます。

Retry

フックの実行は、成功するまで再試行されます。

Ignore

フックの失敗は無視され、デプロイメントは続行されます。

フックには、フックの実行方法を記述するタイプ固有のフィールドがあります。現在、フックタイプとしてサポートされているのは Pod ベースのフック のみで、このフックは execNewPod フィールドで指定します。

9.3.5.1. Pod ベースのライフサイクルフック

Pod ベースのライフサイクルフックは、デプロイメント設定のテンプレートをベースとする新しい Pod でフックコードを実行します。

以下のデプロイメント設定例は簡素化されており、この例では「ローリングストラテジー」を使用します。トリガーおよびその他の詳細は省略し、簡潔化しています。

kind: DeploymentConfig
apiVersion: v1
metadata:
  name: frontend
spec:
  template:
    metadata:
      labels:
        name: frontend
    spec:
      containers:
        - name: helloworld
          image: openshift/origin-ruby-sample
  replicas: 5
  selector:
    name: frontend
  strategy:
    type: Rolling
    rollingParams:
      pre:
        failurePolicy: Abort
        execNewPod:
          containerName: helloworld 1
          command: [ "/usr/bin/command", "arg1", "arg2" ] 2
          env: 3
            - name: CUSTOM_VAR1
              value: custom_value1
          volumes:
            - data 4
1
helloworld の名前は spec.template.spec.containers[0].name を参照します。
2
この command は、openshift/origin-ruby-sample イメージで定義される ENTRYPOINT を上書きします。
3
env は、フックコンテナーの環境変数です (任意)。
4
volumes は、フックコンテナーのボリューム参照です (任意)。

この例では pre フックは、helloworld からの openshift/origin-ruby-sample イメージを使用して新規 Pod で実行されます。フック Pod には以下のプロパティーが設定されます。

  • フックコマンドは /usr/bin/command arg1 arg2 となります。
  • フックコンテナーには CUSTOM_VAR1=custom_value1 環境変数が含まれます。
  • フックの失敗ポリシーは Abort で、フックが失敗するとデプロイメントプロセスも失敗します。
  • フック Pod は、設定 Pod から data ボリュームを継承します。

9.3.5.2. コマンドラインの使用

oc set deployment-hook コマンドは、デプロイメント構成にデプロイメントフックを設定するのに使用できます。上記の例では、以下のコマンドでプリデプロイメントフックを設定できます。

$ oc set deployment-hook dc/frontend --pre -c helloworld -e CUSTOM_VAR1=custom_value1 \
  -v data --failure-policy=abort -- /usr/bin/command arg1 arg2

9.4. 高度なデプロイメントストラテジー

9.4.1. 高度なデプロイメントストラテジー

デプロイメントストラテジー は、アプリケーションを進化させる手段として使用します。一部のストラテジーは デプロイメント設定 を使用して変更を加えます。これらの変更は、アプリケーションを解決する全ルートのユーザーに表示されます。ここで説明している他のストラテジーは、ルート機能を使用して固有のルートに影響を与えます。

9.4.2. Blue-Green デプロイメント

Blue-green デプロイメントでは、同時に 2 つのバージョンを実行し、実稼働版 (green バージョン) からより新しいバージョン (blue バージョン) にトラフィックを移動します。ルートで ローリングストラテジー または切り替えサービスを使用できます。

注記

多くのアプリケーションは永続データに依存するので、N-1 互換性 をサポートするアプリケーションが必要です。つまり、データを共有して、データ層を 2 つ作成し、データベース、ストアまたはディスク間のライブマイグレーションを実装します。

新規バージョンのテストに使用するデータについて考えてみてください。実稼働データの場合には、新規バージョンのバグにより、実稼働版を破損してしまう可能性があります。

9.4.2.1. Blue-Green デプロイメントの使用

Blue-Green デプロイメントは 2 つのデプロイメント設定を使用します。いずれも実行され、実稼働のデプロイメントはルートが指定するルートによって変わります。この際、各デプロイメント設定は異なるサービスに公開されます。新しいバージョンに新規ルートを作成して、これをテストすることができます。準備が整うと、実稼働ルートのサービスを新規サービスを参照するように変更し、新しい blue バージョンがライブになります。

必要に応じて以前のバージョンにサービスを切り替えて、以前の green バージョンにロールバックすることができます。

ルートと 2 つのサービスの使用

以下の例は、2 つのデプロイメント設定を行います。1 つは、安定版 (green バージョン) で、もう 1 つは新規バージョン (blue バージョン) です。

ルートは、サービスを参照し、いつでも別のサービスを参照するように変更できます。開発者は、実稼働トラフィックが新規サービスにルーティングされる前に、新規サービスに接続して、コードの新規バージョンをテストできます。

ルートは、web (HTTP および HTTPS) トラフィックを対象としているので、この手法は Web アプリケーションに最適です。

  1. アプリケーションサンプルを 2 つ作成します。

    $ oc new-app openshift/deployment-example:v1 --name=example-green
    $ oc new-app openshift/deployment-example:v2 --name=example-blue

    上記のコマンドにより、独立したアプリケーションコンポーネントが 2 つ作成されます。1 つは、example-green サービスで v1 イメージを実行するコンポーネントと、もう 1 つは example-blue サービスで v2 イメージを実行するコンポーネントです。

  2. 以前のサービスを参照するルートを作成します。

    $ oc expose svc/example-green --name=bluegreen-example
  3. bluegreen-example.<project>.<router_domain> で、アプリケーションを参照して v1 イメージが表示されることを確認します。

    注記

    OpenShift Container Platform v3.0.1 以前のバージョンでは、このコマンドは、上記の場所ではなく example-green.<project>.<router_domain> にルートを生成します。

  4. ルートを編集して、サービス名を example-blue に変更します。

    $ oc patch route/bluegreen-example -p '{"spec":{"to":{"name":"example-blue"}}}'
  5. ルートが変更されたことを確認するには、v2 イメージが表示されるまで、ブラウザーを更新します。

9.4.3. A/B デプロイメント

A/B デプロイメントストラテジー では、新しいバージョンのアプリケーションを実稼働環境での制限された方法で試すことができます。実稼働バージョンは、ユーザーの要求の大半に対応し、要求の一部が新しいバージョンに移動されるように指定できます。各バージョンへの要求の部分を制御できるので、テストが進むにつれ、新しいバージョンへの要求を増やし、最終的に以前のバージョンの使用を停止することができます。各バージョン要求負荷を調整するにつれ、期待どおりのパフォーマンスを出せるように、各サービスの Pod 数もスケーリングする必要があります。

ソフトウェアのアップグレードに加え、この機能を使用してユーザーインターフェースのバージョンを検証することができます。以前のバージョンを使用するユーザーと、新しいバージョンを使用するユーザーが出てくるので、異なるバージョンに対するユーザーの反応を評価して、デザインの意思決定を行うことができます。

このデプロイメントの効果を発揮するには、以前のバージョンと新しいバージョンは同時に実行できるほど類似している必要があります。これは、バグ修正リリースや新機能が以前の機能と干渉しないようにする場合の一般的なポイントになります。これらのバージョンが正しく連携するには N-1 互換性 が必要です。

OpenShift Container Platform は、Web コンソールとコマンドラインインターフェースで N-1 互換性をサポートします。

9.4.3.1. A/B テスト用の負荷分散

「複数のサービスでルート」を設定します。各サービスは、アプリケーションの 1 つのバージョンを処理します。

各サービスには weight が割り当てられ、各サービスへの要求の部分については service_weightsum_of_weights で除算します。エンドポイントの weights の合計がサービスの weight になるように、サービスごとの weight がサービスのエンドポイントに分散されます。

ルートにはサービスを 4 つ含めることができます。サービスの weight は、0 から 256 で指定してください。weight0 の場合は、新しい要求はサービスに移動せずに、既存の接続がアクティブのままになります。サービスの weight0 でない場合は、エンドポイントの最小 weight1 となります。これにより、エンドポイントが多数含まれるサービスは、最終的に希望の weight よりも多くなってしまう可能性があります。このような場合は、希望とする負荷分散の weight になるように、Pod の数を減らしてください。詳しい情報は、「別のバックエンドおよび Weight」のセクションを参照してください。

Web コンソールでは、重みを設定したり、各サービス間の重みの分散を表示したりできます。

Visualization of Alternate Back Ends in the Web Console

A/B 環境を設定するには以下を行います。

  1. 2 つのアプリケーションを作成して、異なる名前を指定します。それぞがデプロイメント設定を作成します。これらのアプリケーションは同じアプリケーションのバージョンであり、通常 1 つは現在の実稼働バージョンで、もう 1 つは提案される新規バージョンとなります。

    $ oc new-app openshift/deployment-example1 --name=ab-example-a
    $ oc new-app openshift/deployment-example2 --name=ab-example-b
  2. デプロイメント設定を公開してサービスを作成します。

    $ oc expose dc/ab-example-a --name=ab-example-A
    $ oc expose dc/ab-example-b --name=ab-example-B

    この時点で、いずれのアプリケーションもデプロイ、実行され、サービスが追加されています。

  3. ルート経由でアプリケーションを外部から利用できるようにします。この時点でサービスを公開できます。現在の実稼働バージョンを公開してから、後でルートを編集して新規バージョンを追加すると便利です。

    $ oc expose svc/ab-example-A

    ab-example.<project>.<router_domain> でアプリケーションを参照して、希望とするバージョンが表示されていることを確認します。

  4. ルートをデプロイする場合には、ルーターはサービスに指定した weights に従って「トラフィックを分散します」。この時点では、デフォルトの weight=1 と指定されたサービスが 1 つ存在するので、すべての要求がこのサービスに送られます。他のサービスを alternateBackends として追加し、weights を調整すると、A/B 設定が機能するようになります。これは、oc set route-backends コマンドを実行するか、ルートを編集して実行できます。

    注記

    ルートに変更を加えると、さまざまなサービスへのトラフィックの部分だけが変更されます。デプロイメント設定をスケーリングして、必要な負荷を処理できるように Pod 数を調整する必要がある場合があります。

    ルートを編集するには、以下を実行します。

    $ oc edit route <route-name>
    ...
    metadata:
      name: route-alternate-service
      annotations:
        haproxy.router.openshift.io/balance: roundrobin
    spec:
      host: ab-example.my-project.my-domain
      to:
        kind: Service
        name: ab-example-A
        weight: 10
      alternateBackends:
      - kind: Service
        name: ab-example-B
        weight: 15
    ...
9.4.3.1.1. Web コンソールを使用した重みの管理
  1. Route の詳細ページ (アプリケーション/ルート) に移動します。
  2. アクションメニューから Edit を選択します。
  3. Split traffic across multiple services にチェックを入れます。
  4. Service Weights スライダーで、各サービスに送信するトラフィックの割合を設定します。

    Service Weights

    2 つ以上のサービスにトラフィックを分割する場合には、各サービスに 0 から 256 の整数を使用して、相対的な重みを指定します。

    Weights specified by integers

    トラフィックの重みは、トラフィックを分割したアプリケーションの行を展開すると Overview に表示されます。

9.4.3.1.2. CLI を使用した重みの管理

このコマンドは、ルートでサービスと対応する重みの「負荷分散」を管理します。

$ oc set route-backends ROUTENAME [--zero|--equal] [--adjust] SERVICE=WEIGHT[%] [...] [options]

たとえば、以下のコマンドは ab-example-Aweight=198 を指定して主要なサービスとし、ab-example-Bweight=2 を指定して 1 番目の代用サービスとして設定します。

$ oc set route-backends web ab-example-A=198 ab-example-B=2

つまり、99% のトラフィックはサービス ab-example-A に、1% はサービス ab-example-B に送信されます。

このコマンドでは、デプロイメント設定はスケーリングされません。要求の負荷を処理するのに十分な pod がある状態でこれを実行する必要があります。

フラグなしのコマンドでは、現在の設定が表示されます。

$ oc set route-backends web
NAME                    KIND     TO           WEIGHT
routes/web              Service  ab-example-A 198 (99%)
routes/web              Service  ab-example-B 2   (1%)

--adjust フラグを使用すると、個別のサービスの重みを、それ自体に対して、または主要なサービスに対して相対的に変更できます。割合を指定すると、主要サービスまたは 1 番目の代用サービス (主要サービスを設定している場合) に対して相対的にサービスを調整できます。他にバックエンドがある場合には、重みは変更に比例した状態になります。

$ oc set route-backends web --adjust ab-example-A=200 ab-example-B=10
$ oc set route-backends web --adjust ab-example-B=5%
$ oc set route-backends web --adjust ab-example-B=+15%

--equal フラグでは、全サービスの weight が 100 になるように設定します。

$ oc set route-backends web --equal

--zero フラグは、全サービスの weight を 0 に設定します。すべての要求に対して 503 エラーが返されます。

注記

ルートによっては、複数のバックエンドたは重みが設定されたバックエンドをサポートしないものがあります。

9.4.3.1.3. 1 サービス、複数のデプロイメント設定

ルーターをインストールしている場合は、ルートを使用してアプリケーションを利用できるようにしてください (または、サービス IP を直接使用してください)。

$ oc expose svc/ab-example

ab-example.<project>.<router_domain> でアプリケーションを参照し、v1 イメージが表示されることを確認します。

  1. 1 つ目のシャードと同じだが別のバージョンがタグ付けされたソースイメージを基に 2 つ目のシャードを作成して、一意の値を設定します。

    $ oc new-app openshift/deployment-example:v2 --name=ab-example-b --labels=ab-example=true SUBTITLE="shard B" COLOR="red"
  2. 新たに作成したシャードを編集して、全シャードに共通の ab-example=true ラベルを設定します。

    $ oc edit dc/ab-example-b

    エディターで、spec.selectorspec.template.metadata.labels の下に、既存の deploymentconfig=ab-example-b ラベルと一緒に ab-example: "true" の行を追加して保存し、エディターを終了します。

  3. 2 番目のシャードの再デプロイメントをトリガーして、新規ラベルを取得します。

    $ oc rollout latest dc/ab-example-b
  4. この時点で、いずれの Pod もルートでサービスが提供されますが、両ブラウザー (接続を開放) とルート (デフォルトでは cookie を使用) で、バックエンドサーバーへの接続を保存するように試行するので、シャードが両方返されない可能性があります。ブラウザーからいずれかのシャードを表示させるようにするには、scale コマンドを使用します。

    $ oc scale dc/ab-example-a --replicas=0

    ブラウザーを更新すると、 v2 および shard B (赤字) が表示されているはずです。

    $ oc scale dc/ab-example-a --replicas=1; oc scale dc/ab-example-b --replicas=0

    ブラウザーを更新すると、v1shard A (青字) が表示されているはずです。

    いずれかのシャードでデプロイメントをトリガーした場合には、そのシャード内の Pod のみが影響を受けます。いずれかのデプロイメント設定で SUBTITLE 環境変数を変更して (oc edit dc/ab-example-a または oc edit dc/ab-example-b)、デプロイメントを簡単にトリガーできます。ステップ 5-7 を繰り返すと、別のシャードを追加できます。

    注記

    これらの手順は、今後の OpenShift Container Platform バージョンでは簡素化される予定です。

9.4.4. プロキシーシャード/トラフィックスプリッター

実稼働環境で、特定のシャードに到達するトラフィックの分散を正確に制御できます。多くのインスタンスを扱う場合は、各シャードに相対的なスケールを使用して、割合ベースのトラフィックを実装できます。これは、他の場所で実行中の別のサービスやアプリケーションに転送または分割する プロキシーシャード とも適切に統合されます。

最も単純な設定では、プロキシーは要求を変更せずに転送します。より複雑な設定では、受信要求を複製して、別のクラスターだけでなく、アプリケーションのローカルインスタンスにも送信して、結果を比較することができます。他のパターンとしては、DR のインストールのキャッシュを保持したり、分析目的で受信トラフィックをサンプリングすることができます。

実装がこの例のスコープ外の場合でも、TCP (または UDP) のプロキシーは必要なシャードで実行できます。oc scale コマンドを使用して、プロキシーシャードで要求に対応するインスタンスの相対数を変更してください。より複雑なトラフィックを管理する場合には、OpenShift Container Platform ルーターを比例分散機能でカスタマイズすることを検討してください。

9.4.5. N-1 互換性

新規コードと以前のコードが同時に実行されるアプリケーションの場合は、新規コードで記述されたデータが、以前のコードで読み込みや処理 (または正常に無視) できるように注意する必要があります。これは、スキーマの進化 と呼ばれ、複雑な問題です。

これは、ディスクに保存したデータ、データベース、一時的なキャッシュ、ユーザーのブラウザーセッションの一部など、多数の形式を取ることができます。多くの Web アプリケーションはローリングデプロイメントをサポートできますが、アプリケーションをテストし、設計してこれに対応させることが重要です。

アプリケーションによっては、新規と旧コードが並行的に実行されている期間が短いため、バグやユーザーのトランザクションに失敗しても許容範囲である場合があります。別のアプリケーションでは失敗したパターンが原因で、アプリケーション全体が機能しなくなる場合もあります。

N-1 互換性を検証する 1 つの方法として、A/B デプロイメント があります。制御されたテスト環境で、以前のコードと新しいコードを同時に実行して、新規デプロイメントに流れるトラフィックが以前のデプロイメントで問題を発生させないかを確認します。

9.4.6. 正常な終了

OpenShift Container Platform および Kubernetes は、負荷分散のローテーションから削除する前にアプリケーションインスタンスがシャットダウンする時間を設定します。ただし、アプリケーションでは、終了前にユーザー接続が正常に中断されていることを確認する必要があります。

シャットダウン時に、OpenShift Container Platform はコンテナーのプロセスに TERM シグナルを送信します。SIGTERM を受信すると、アプリケーションコードは、新規接続の受け入れを停止する必要があります。こうすることで、ロードバランサーにより、他のアクティブなインスタンスにトラフィックをルーティングされるようになります。アプリケーションコードは、開放されている接続がすべて終了する (または、次の機会に個別接続が正常に終了される) まで待機してから終了します。

正常に終了する期間が終わると、終了されていないプロセスに KILL シグナルが送信され、プロセスが即座に終了されます。Pod の terminationGracePeriodSeconds 属性または Pod テンプレートが正常に終了する期間 (デフォルト 30 秒) を制御し、必要に応じてアプリケーションごとにカスタマイズすることができます。

9.5. Kubernetes デプロイメントサポート

9.5.1. デプロイメントオブジェクトタイプ

Kubernetes には、OpenShift Container Platform では デプロイメント と呼ばれるファーストクラスのオブジェクトタイプがあります。このオブジェクトタイプ (ここでは区別するために Kubernetes デプロイメント と呼びます) は、デプロイメント設定オブジェクトタイプの派生タイプとして機能します。

デプロイメント設定と同様に、Kubernetes デプロイメントは Pod テンプレートとして、アプリケーションの特定のコンポーネントの必要とされる状態を記述します。Kubernetes デプロイメントは レプリカセット (「レプリケーションコントローラー」の反復) を作成して、Pod ライフサイクルをオーケストレーションします。

たとえば、Kubernetes デプロイメントのこの定義は、レプリカセットを作成して hello-openshift pod を 1 つ起動します。

例: Kubernetes デプロイメント定義 hello-openshift-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-openshift
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello-openshift
  template:
    metadata:
      labels:
        app: hello-openshift
    spec:
      containers:
      - name: hello-openshift
        image: openshift/hello-openshift:latest
        ports:
        - containerPort: 80

ローカルファイルに定義を保存した後に、Kubernetes デプロイメントの作成にこのファイルを使用できます。

$ oc create -f hello-openshift-deployment.yaml

CLI を使用して、getdescribe などの「一般的な操作」で記載されているように、Kubernetes デプロイメントと、他のオブジェクトタイプなどのレプリカセットを検証して、操作します。オブジェクトタイプの場合、Kubernetes デプロイメントには deployments または deploy を、レプリカセットには replicasets または rs を使用します。

デプロイメント および レプリカセット に関する詳細は、Kubernetes のドキュメントを参照してください。CLI の使用方法の例で、ockubectl に置き換えてください。

9.5.2. Kubernetes デプロイメント 対 デプロイメント設定

デプロイメントが Kurbernetes 1.2 に追加される前にデプロイメント設定が OpenShift Container Platform に存在していたために、Kurbenetes のオブジェクトタイプは OpenShift Container Platform の設定とは若干異なっています。OpenShift Container Platform の長期的な目標は、Kubernetes デプロイメントと全く同等な機能を実現し、アプリケーションの詳細な管理を可能にする単一オブジェクトタイプとしてそれらのデプロイメントを使用する方法に切り替えることにあります。

新規オブジェクトタイプを使用するアップストリームのプロジェクトや例が OpenShift Container Platform でスムーズに実行できるように、Kubernetes デプロイメントはサポートされます。Kubernetes デプロイメントの現在の機能を考慮すると、特に以下のいずれかを使用する予定がない場合には、OpenShift Container Platform のデプロイメント設定の代わりに、Kubernetes デプロイメントを使用すると良いでしょう。

以下のセクションでは、2 つのオブジェクトタイプの相違点に関してさらに扱います。これは、デプロイメント設定ではなく、Kubernetes デプロイメントを使用する場合を判別するのに役立ちます。

9.5.2.1. デプロイメント設定固有の機能

9.5.2.1.1. 自動ロールバック

Kubernetes デプロイメントは、問題が発生した場合に、最後に正常にデプロイされたレプリカセットに自動的にロールバックされません。この機能は近日追加される予定です。

9.5.2.1.2. トリガー

Kubernetes デプロイメントには、デプロイメントの Pod テンプレートに変更があるたびに、新しいロールアウトが自動的にトリガーされるので、暗黙的な ConfigChange トリガーが含まれています。Pod テンプレートの変更時に新たにロールアウトしない場合には、デプロイメントを以下のように停止します。

$ oc rollout pause deployments/<name>

現在、Kubernetes デプロイメントでは ImageChange トリガーはサポートされません。汎用的なトリガーの仕組みがアップストリームでは提案されていますが、この提案が受け入れられるのか、また受け入れられるタイミングは不明です。最終的には、OpenShift Container Platform 固有の仕組みが、Kubernetes デプロイメントの階層の上に実装される可能性がありますが、Kubernetes コアの一部として存在させる方が適しています。

9.5.2.1.3. ライフサイクルフック

Kubernetes デプロイメントではライフサイクルフックがサポートされません。

9.5.2.1.4. カスタムストラテジー

Kubernetes デプロイメントでは、ユーザーが指定するカスタムデプロイメントストラテジーはまだサポートされていません。

9.5.2.1.5. カナリアリリースデプロイメント

Kubernetes デプロイメントでは、新規ロールアウトの一部としてカナリアリリースは実行されません。

9.5.2.1.6. テストデプロイメント

Kubernetes デプロイメントでは、実行中のテストトラックはサポートされません。

9.5.2.2. Kubernetes デプロイメント固有の機能

9.5.2.2.1. ロールオーバー

Kubernetes デプロイメントのデプロイメントプロセスは、コントローラーループで駆動されますが、デプロイメント設定は、新しいロールアウトごとにデプロイヤー Pod を使用します。つまり、Kubernetes デプロイメントはできるだけアクティブなレプリカセットを指定することができ、最終的にデプロイメントコントローラーが以前のレプリカセットをスケールダウンし、最新のものをスケールアップします。

デプロイメント設定で、実行できるデプロイヤー Pod は最大 1 つとなっています。デプロイヤーが 2 つある場合は、他のデプロイヤーと競合して、それぞれが最新のレプリケーションコントローラーであると考えるコントローラーをスケールアップしようとします。これにより、一度にアクティブにできるのは、レプリケーションコントローラー 2 つだけで、最終的に、Kubernetes デプロイヤーのロールアウトが加速します。

9.5.2.2.2. 比例スケーリング

Kubernetes デプロイメントコントローラーのみがデプロイメントが所有する新旧レプリカセットのサイズについての信頼できる情報源であるため、継続中のロールアウトのスケーリングできます。追加のレプリカはレプリカセットのサイズに比例して分散されます。

デプロイメント設定は、デプロイメント設定コントローラーが新規レプリケーションコントローラーのサイズに関してデプロイヤープロセスと競合するためにロールアウトが続行されている場合はスケーリングできません。

9.5.2.2.3. ロールアウト中の一時停止

Kubernetes デプロイメントはいつでも一時停止できます。つまり、継続中のロールアウトも一時停止できます。反対に、デプロイヤー Pod は現時点で一時停止できないので、ロールアウト時にデプロイメント設定を一時停止しようとしても、デプロイヤープロセスはこの影響を受けず、完了するまで続行されます。

第10章 Templates (テンプレート)

10.1. 概要

テンプレートでは、パラメーター化や処理可能な「オブジェクト」を記述し、OpenShift Container Platform で構築するためのオブジェクト一覧を生成します。テンプレートは、「サービス」「ビルド設定」および「デプロイメント設定」など、プロジェクト内で作成パーミッションがあるすべてのものを作成するために処理できます。また、テンプレートでは、「ラベル」のセットを定義して、これをテンプレート内に定義された全オブジェクトに適用できます。

CLI を使用する か、プロジェクトまたはグローバルテンプレートライブラリーに テンプレートがアップロードされている場合 には、Web コンソール を使用して、テンプレートからオブジェクト一覧を作成できます。キュレートされたテンプレートの場合は、OpenShift イメージストリームおよびテンプレートライブラリー を参照してください。

10.2. テンプレートのアップロード

テンプレートを定義する JSON または YAML ファイルがある場合は、「この例」にあるように、CLI を使用してプロジェクトに、テンプレートをアップロードできます。こうすることで、プロジェクトにテンプレートが保存され、対象のプロジェクトに対して適切なアクセス権があるユーザーにより、繰り返し使用できます。「独自のテンプレートの記述」については、このトピックで後ほど説明します。

現在のプロジェクトのテンプレートライブラリーにテンプレートをアップロードするには、JSON または YAML ファイルを以下のコマンドで渡します。

$ oc create -f <filename>

-n オプションを使用してプロジェクト名を指定することで、別のプロジェクトにテンプレートをアップロードできます。

$ oc create -f <filename> -n <project>

テンプレートは、Web コンソールまたは CLI を使用して選択できるようになりました。

10.3. Web コンソールを使用してテンプレートから作成する手順

Web コンソールを使用したアプリケーションの作成」を参照してください。

10.4. CLI を使用してテンプレートから作成する手順

CLI を使用して、テンプレートを処理し、オブジェクトを作成するために生成された設定を使用できます。

10.4.1. ラベル

「ラベル」は Pod などの生成されるオブジェクトを管理し、整理するのに使用されます。テンプレートで指定したラベルはテンプレートから生成されるすべてのオブジェクトに適用されます。

コマンドラインからテンプレートにラベルを追加する機能もあります。

$ oc process -f <filename> -l name=otherLabel

10.4.2. パラメーター

上書き可能なパラメーターの一覧は、テンプレートのparameters セクション」に記載されています。以下のコマンドで使用するファイルを指定して、CLI でパラメーター一覧を追加できます。

$ oc process --parameters -f <filename>

または、テンプレートがすでにアップロードされている場合には、以下を実行します。

$ oc process --parameters -n <project> <template_name>

たとえば、デフォルトの openshift プロジェクトにあるクイックスタートテンプレートのいずれかに対してパラメーターを追加した場合に、以下のような出力が表示されます。

$ oc process --parameters -n openshift rails-postgresql-example
NAME                         DESCRIPTION                                                                                              GENERATOR           VALUE
SOURCE_REPOSITORY_URL        The URL of the repository with your application source code                                                                  https://github.com/sclorg/rails-ex.git
SOURCE_REPOSITORY_REF        Set this to a branch name, tag or other ref of your repository if you are not using the default branch
CONTEXT_DIR                  Set this to the relative path to your project if it is not in the root of your repository
APPLICATION_DOMAIN           The exposed hostname that will route to the Rails service                                                                    rails-postgresql-example.openshiftapps.com
GITHUB_WEBHOOK_SECRET        A secret string used to configure the GitHub webhook                                                     expression          [a-zA-Z0-9]{40}
SECRET_KEY_BASE              Your secret key for verifying the integrity of signed cookies                                            expression          [a-z0-9]{127}
APPLICATION_USER             The application user that is used within the sample application to authorize access on pages                                 openshift
APPLICATION_PASSWORD         The application password that is used within the sample application to authorize access on pages                             secret
DATABASE_SERVICE_NAME        Database service name                                                                                                        postgresql
POSTGRESQL_USER              database username                                                                                        expression          user[A-Z0-9]{3}
POSTGRESQL_PASSWORD          database password                                                                                        expression          [a-zA-Z0-9]{8}
POSTGRESQL_DATABASE          database name                                                                                                                root
POSTGRESQL_MAX_CONNECTIONS   database max connections                                                                                                     10
POSTGRESQL_SHARED_BUFFERS    database shared buffers                                                                                                      12MB

この出力から、テンプレートの処理時に正規表現のようなジェネレーターで生成された複数のパラメーターを特定できます。

10.4.3. オブジェクト一覧の生成

CLI を使用して、標準出力にオブジェクト一覧を返すテンプレートを定義するファイルを処理できます。

$ oc process -f <filename>

または、テンプレートがすでに現在のプロジェクトにアップロードされている場合には以下を実行します。

$ oc process <template_name>

テンプレートを処理し、oc create の出力をパイプして、テンプレートからオブジェクトを作成することができます。

$ oc process -f <filename> | oc create -f -

または、テンプレートがすでに現在のプロジェクトにアップロードされている場合には以下を実行します。

$ oc process <template> | oc create -f -

上書きする <name>=<value> の各ペアに、-p オプションを追加することで、ファイルに定義された パラメーター の値を上書きできます。パラメーター参照は、テンプレートアイテム内のテキストフィールドに表示される場合があります。

たとえば、テンプレート内の以下の POSTGRESQL_USER および POSTGRESQL_DATABASE パラメーターを上書きし、カスタマイズされた環境変数での設定を出力します。

例10.1 テンプレートからのオブジェクト一覧の作成

$ oc process -f my-rails-postgresql \
    -p POSTGRESQL_USER=bob \
    -p POSTGRESQL_DATABASE=mydatabase

JSON ファイルは、ファイルにリダイレクトすることも、oc create コマンドで、処理済みの出力をパイプして、テンプレートをアップロードせずに直接適用することも可能です。

$ oc process -f my-rails-postgresql \
    -p POSTGRESQL_USER=bob \
    -p POSTGRESQL_DATABASE=mydatabase \
    | oc create -f -

多数のパラメーターがある場合は、それらをファイルに保存してからそのファイルを oc process に渡すことができます。

$ cat postgres.env
POSTGRESQL_USER=bob
POSTGRESQL_DATABASE=mydatabase
$ oc process -f my-rails-postgresql --param-file=postgres.env

--param-file の引数として "-" を使用して、標準入力から環境を読み込むこともできます。

$ sed s/bob/alice/ postgres.env | oc process -f my-rails-postgresql --param-file=-

10.5. アップロードしたテンプレートの変更

以下のコマンドを使用して、すでにプロジェクトにアップロードされているテンプレートを編集できます。

$ oc edit template <template>

10.6. インスタントアプリおよびクイックスタートテンプレートの使用

OpenShift Container Platform では、デフォルトで、インスタントアプリとクイックスタートテンプレートを複数提供しており、各種言語で簡単に新規アプリの構築を開始できます。Rails (Ruby)、Django (Python)、Node.js、CakePHP (PHP) および Dancer (Perl) 用のテンプレートを利用できます。クラスター管理者は、これらのテンプレートを利用できるようにデフォルトのグローバル openshift プロジェクトにこれらのテンプレートを作成しているはずです。デフォルトで利用可能なインスタントアプリやクイックスタートテンプレートを一覧表示するには、以下を実行します。

$ oc get templates -n openshift

見つからない場合には、クラスター管理者に「デフォルトのイメージストリームとテンプレートの読み込み」のトピックを参照してもらうようにしてください。

デフォルトでは、テンプレートビルドは GitHub の公開ソースリポジトリーを使用し、これには必要なアプリケーションコードが含まれます。ソースを変更して、独自のバージョンのアプリケーションをビルドするには、以下を実行する必要があります。

  1. テンプレートのデフォルト SOURCE_REPOSITORY_URL パラメーターが参照するリポジトリーをフォークします。
  2. テンプレートから作成する場合には、SOURCE_REPOSITORY_URL パラメーターの値を上書きします。デフォルト値ではなく、フォークを指定してください。

これにより、テンプレートで作成したビルド設定はアプリケーションコードのフォークを参照するようになり、コードを更新して、自由にアプリケーションをリビルドできます。

Web コンソールを使用してこのプロセスを行う場合は、「開発者向けのスタートガイド: Web コンソール」を参照してください。

注記

インスタンスアプリおよびクイックスタートアプリのテンプレートで、データベースの「デプロイメント設定」を定義するものもあります。テンプレートが定義する設定では、データベースコンテンツ用に一時ストレージを使用します。データベース Pod が何らかの理由で再起動されると、データベースの全データが失われてしまうので、これらのテンプレートは、デモ目的でのみ使用する必要があります。

10.7. テンプレートの記述

アプリケーションの全オブジェクトを簡単に再作成するために、新規テンプレートを定義できます。テンプレートでは、作成するオブジェクトと、これらのオブジェクトの作成をガイドするメタデータを定義します。

例10.2 シンプルなテンプレートオブジェクト定義 (YAML)

apiVersion: v1
kind: Template
metadata:
  name: redis-template
  annotations:
    description: "Description"
    iconClass: "icon-redis"
    tags: "database,nosql"
objects:
- apiVersion: v1
  kind: Pod
  metadata:
    name: redis-master
  spec:
    containers:
    - env:
      - name: REDIS_PASSWORD
        value: ${REDIS_PASSWORD}
      image: dockerfile/redis
      name: master
      ports:
      - containerPort: 6379
        protocol: TCP
parameters:
- description: Password used for Redis authentication
  from: '[A-Z0-9]{8}'
  generate: expression
  name: REDIS_PASSWORD
labels:
  redis: master

10.7.1. 説明

テンプレートの説明では、テンプレートの内容に関する情報を提供でき、Web コンソールでの検索時に役立ちます。テンプレート名以外のメタデータは任意ですが、使用すると便利です。メタデータには、一般的な説明などの情報以外にタグのセットも含まれます。便利なタグにはテンプレートで使用する言語名などがあります (例: javaphpruby )。

例10.3 テンプレート記述メタデータ

kind: Template
apiVersion: v1
metadata:
  name: cakephp-mysql-example 1
  annotations:
    openshift.io/display-name: "CakePHP MySQL Example (Ephemeral)" 2
    description: >-
      An example CakePHP application with a MySQL database. For more information
      about using this template, including OpenShift considerations, see
      https://github.com/sclorg/cakephp-ex/blob/master/README.md.


      WARNING: Any data stored will be lost upon pod destruction. Only use this
      template for testing." 3
    openshift.io/long-description: >-
      This template defines resources needed to develop a CakePHP application,
      including a build configuration, application deployment configuration, and
      database deployment configuration.  The database is stored in
      non-persistent storage, so this configuration should be used for
      experimental purposes only. 4
    tags: "quickstart,php,cakephp" 5
    iconClass: icon-php 6
    openshift.io/provider-display-name: "Red Hat, Inc." 7
    openshift.io/documentation-url: "https://github.com/sclorg/cakephp-ex" 8
    openshift.io/support-url: "https://access.redhat.com" 9
message: "Your admin credentials are ${ADMIN_USERNAME}:${ADMIN_PASSWORD}" 10
1
テンプレートの一意名
2
ユーザーインターフェースで利用できるように、ユーザーに分かりやすく、簡単な名前。
3
テンプレートの説明。デプロイされる内容、デプロイ前に知っておく必要のある注意点をユーザーができるように詳細を追加します。README など、追加情報へのリンクも追加できます。パラグラフを作成するには、改行を追加できます。
4
追加の説明。たとえば、サービスカタログに表示されます。
5
検索とグループ化ができるように、テンプレートに関連付けるタグ。指定のカタログカテゴリーの 1 つに含まれるように、タグを追加します。コンソールの constants ファイル で、CATALOG_CATEGORIESidcategoryAliases を参照してください。カテゴリーは、クラスター全体用に「カスタマイズ」することも可能です。
6
Web コンソールでテンプレートと一緒に表示されるアイコン。可能な場合は、既存の ロゴアイコン から選択します。また、FontAwesomePatternFly からもアイコンを使用できます。または、テンプレートを使用する OpenShift Container Platform クラスターに「CSS カスタマイズ」を追加できるので、CSS カスタマイズ経由でアイコンを提供します。存在するアイコンクラスを指定するようにしてください。指定しないと、汎用アイコンにフォールバックできなくなります。
7
テンプレートを提供する人または組織の名前
8
テンプレートに関する他のドキュメントを参照する URL
9
テンプレートに関するサポートを取得できる URL
10
テンプレートがインスタンス化された時に表示される説明メッセージ。このフィールドで、新規作成されたリソースの使用方法を通知します。生成された認証情報や他のパラメーターが出力に追加できるように、メッセージの表示前に、パラメーターの置換が行われます。ユーザーが従うべき次の手順が記載されたドキュメントへのリンクを追加してください。

10.7.2. ラベル

テンプレートには「ラベル」のセットを追加できます。これらのラベルは、テンプレートがインスタンス化される時に作成されるオブジェクトごとに追加します。このようにラベルを定義すると、特定のテンプレートから作成された全オブジェクトの検索、管理が簡単になります。

例10.4 テンプレートオブジェクトのラベル

kind: "Template"
apiVersion: "v1"
...
labels:
  template: "cakephp-mysql-example" 1
  app: "${NAME}" 2
1
このテンプレートから作成する全オブジェクトに適用されるラベル
2
パラメーター化されたラベル。このラベルは、このテンプレートを基に作成された全オブジェクトに適用されます。パラメーターは、ラベルキーおよび値の両方で拡張されます。

10.7.3. パラメーター

パラメーターにより、テンプレートがインスタンス化される時に値を生成するか、ユーザーが値を指定できるようになります。値は、パラメーターが参照されると、置換されます。参照は、オブジェクト一覧フィールドであればどこでも定義できます。これは、無作為にパスワードを作成したり、テンプレートのカスタマイズに必要なユーザー固有の値やホスト名を指定したりできるので便利です。パラメーターは、2 種類の方法で参照可能です。

  • 文字列の値として、テンプレートも文字列フィールドに ${PARAMETER_NAME} の形式で配置する
  • json/yaml の値として、テンプレートのフィールドに ${{PARAMETER_NAME}} の形式で配置する

${PARAMETER_NAME} 構文を使用すると、複数のパラメーター参照を 1 つフィールドに統合でき、"http://${PARAMETER_1}${PARAMETER_2}" などのように、参照を固定のデータ内に埋め込むことができます。どちらのパラメーター値も置換されて、引用された文字列が最終的な値になります。

${{PARAMETER_NAME}} 構文のみを使用する場合は、単一のパラメーター参照のみが可能で、先頭文字や終了文字は使用できません。結果値は、置換した後に結果が有効な json オブジェクトでない限り、引用されません。結果が有効な json 値でない場合に、結果値は引用され、標準の文字列として処理されます。

単一のパラメーターは、テンプレート内で複数回参照でき、また、1 つのテンプレート内で両方の置換構文を使用して参照することができます。

デフォルト値を指定でき、ユーザーが別の値を指定していない場合に使用されます。

例10.5 デフォルト値として明示的な値の設定

parameters:
  - name: USERNAME
    description: "The user name for Joe"
    value: joe

パラメーター値は、パラメーター定義に指定したルールを基に生成することも可能です。

例10.6 パラメーター値の生成

parameters:
  - name: PASSWORD
    description: "The random user password"
    generate: expression
    from: "[a-zA-Z0-9]{12}"

上記の例では、処理後に、大文字、小文字、数字すべてを含む 12 文字長のパスワードが無作為に作成されます。

利用可能な構文は、完全な正規表現の構文ではありませんが、\w\d および \a 修飾子を使用することができます。

  • [\w]{10} は、英数字、アンダースコア 10 桁を生成します。これは、PCRE 標準に準拠し、[a-zA-Z0-9_]{10} に相当します。
  • [\d]{10} は 10 桁の数字を生成します。これは [0-9]{10} に相当します。
  • [\a]{10} は 10 桁の英数字を生成します。これは、[a-zA-Z]{10} に相当します。

以下は、パラメーター定義と参照を含む完全なテンプレートの例です。

例10.7 パラメーター定義と参照を含む完全なテンプレート

kind: Template
apiVersion: v1
metadata:
  name: my-template
objects:
  - kind: BuildConfig
    apiVersion: v1
    metadata:
      name: cakephp-mysql-example
      annotations:
        description: Defines how to build the application
    spec:
      source:
        type: Git
        git:
          uri: "${SOURCE_REPOSITORY_URL}" 1
          ref: "${SOURCE_REPOSITORY_REF}"
        contextDir: "${CONTEXT_DIR}"
  - kind: DeploymentConfig
    apiVersion: v1
    metadata:
      name: frontend
    spec:
      replicas: "${{REPLICA_COUNT}}" 2
parameters:
  - name: SOURCE_REPOSITORY_URL 3
    displayName: Source Repository URL 4
    description: The URL of the repository with your application source code 5
    value: https://github.com/sclorg/cakephp-ex.git 6
    required: true 7
  - name: GITHUB_WEBHOOK_SECRET
    description: A secret string used to configure the GitHub webhook
    generate: expression 8
    from: "[a-zA-Z0-9]{40}" 9
  - name: REPLICA_COUNT
    description: Number of replicas to run
    value: "2"
    required: true
message: "... The GitHub webhook secret is ${GITHUB_WEBHOOK_SECRET} ..." 10
1
この値は、テンプレートがインスタンス化された時点で SOURCE_REPOSITORY_URL パラメーターに置き換えられます。
2
この値は、テンプレートがインスタンス化された時点で、REPLICA_COUNT パラメーターの引用なしの値に置き換えられます。
3
パラメーター名。この値は、テンプレート内でパラメーターを参照するのに使用します。
4
分かりやすいパラメーターの名前。これは、ユーザーに表示されます。
5
パラメーターの説明。期待値に対する制約など、パラメーターの目的を詳細にわたり説明します。説明には、コンソールの テキスト表示 に従い、完全な文章を使用するようにしてください。表示名と同じ内容を使用しないでください。
6
テンプレートをインスタンス化する時に、ユーザーにより値が上書きされない場合に使用されるパラメーターのデフォルト値。パスワードなどはデフォルト値の使用を避けるようにしてください。シークレットと組み合わせた生成パラメーターを使用するようにしてください。
7
このパラメーターが必須であることを指定します。つまり、ユーザーは空の値で上書きできません。パラメーターで、デフォルト値または生成値が指定されていない場合には、ユーザーは値を指定する必要があります。
8
値が生成されるパラメーター
9
生成器への入力。この場合、生成器は、大文字、小文字を含む 40 桁の英数字を生成します。
10
パラメーターは、テンプレートメッセージに追加できるので、メッセージで、生成した値をユーザーに通知します。

10.7.4. オブジェクト一覧

テンプレートの主な部分は、テンプレートがインスタンス化される時に作成されるオブジェクトの一覧です。これには、BuildConfigDeploymentConfigService など、「有効な API オブジェクト」を使用できます。オブジェクトは、ここで定義された通りに作成され、パラメーターの値は作成前に置換されます。これらの定義は、以前に定義したパラメーターを参照できます。

kind: "Template"
apiVersion: "v1"
metadata:
  name: my-template
objects:
  - kind: "Service" 1
    apiVersion: "v1"
    metadata:
      name: "cakephp-mysql-example"
      annotations:
        description: "Exposes and load balances the application pods"
    spec:
      ports:
        - name: "web"
          port: 8080
          targetPort: 8080
      selector:
        name: "cakephp-mysql-example"
1
Service の定義。このテンプレートにより作成されます。
注記

オブジェクト定義のメタデータに namespace フィールドの値が含まれる場合には、テンプレートのインスタンス化時にフィールドは定義から取り除かれます。namespace フィールドにパラメーター参照が含まれる場合には、通常のパラメーター置換が行われ、パラメーター置換が値を解決した namespace で、オブジェクトが作成されます。この際、ユーザーは対象の namespace でオブジェクトを作成するパーミッションがあることが前提です。

10.7.5. バインド可能なテンプレートの作成

テンプレートサービスブローカーは、認識されているテンプレートオブジェクトごとに、カタログ内にサービスを 1 つ公開します。デフォルトでは、これらのサービスはそれぞれ、「バインド可能」として公開され、エンドユーザーがプロビジョンしたサービスに対してバインドできるようにします。

テンプレートの作成者は、template.openshift.io/bindable: "false" のアノテーションをテンプレートに追加して、エンドユーザーが、指定のテンプレートからプロビジョニングされるサービスをバインドできないようにできます。

10.7.6. オブジェクトフィールドの公開

テンプレートの作成者は、テンプレートに含まれる特定のオブジェクトのフィールドを公開すべきかどうかを指定できます。テンプレートサービスのブローカーは、ConfigMap、Secret、Service、Route オブジェクトに公開されたフィールドを認識し、ユーザーがブローカーでバックされているサービスをバンドした場合に公開されたフィールドの値を返します。

オブジェクトのフィールドを 1 つまたは複数公開するには、テンプレート内のオブジェクトに、プレフィックスが template.openshift.io/expose- または template.openshift.io/base64-expose- のアノテーションを追加します。

各アノテーションキーは、bind 応答のキーになるように、プレフィックスが削除されてパススルーされます。

各アノテーションの値は Kubernetes JSONPath 表現 で、バインド時に解決され、bind 応答で返すべき値が含まれるオブジェクトフィールドを指定します。

注記

Bind 応答のキー/値のペアは、環境変数として、システムの他の場所で使用できるので、アノテーションキーでプレフィックスを取り除いた値を有効な環境変数名として使用することが推奨されます。先頭にA-Za-z またはアンダースコアを指定して、その後に、ゼロか、他の文字 A-Za-z0-9 またはアンダースコアを指定してください。

template.openshift.io/expose- アノテーションを使用して、文字列としてフィールドの値を返します。これは、任意のバイナリーデータを処理しませんが、使用すると便利です。バイナリーデータを返す場合には、バイナリーデータを返す前にデータのエンコードに base64b を使用するのではなく、template.openshift.io/base64-expose- アノテーションを使用します。

注記

バックスラッシュでエスケープしない限り、Kubernetes の JSONPath 実装は表現内のどの場所に使用されていても、.@ などはメタ文字として解釈されます。そのため、たとえば、my.key という名前の ConfigMap のデータを参照するには、JSONPath 表現は {.data['my\.key']} とする必要があります。JSONPath 表現が YAML でどのように記述されているかによって、"{.data['my\\.key']}" などのように、追加でバックスラッシュが必要な場合があります。.

以下は、公開されるさまざまなオブジェクトのフィールドの例です。

kind: Template
apiVersion: v1
metadata:
  name: my-template
objects:
- kind: ConfigMap
  apiVersion: v1
  metadata:
    name: my-template-config
    annotations:
      template.openshift.io/expose-username: "{.data['my\\.username']}"
  data:
    my.username: foo
- kind: Secret
  apiVersion: v1
  metadata:
    name: my-template-config-secret
    annotations:
      template.openshift.io/base64-expose-password: "{.data['password']}"
  stringData:
    password: bar
- kind: Service
  apiVersion: v1
  metadata:
    name: my-template-service
    annotations:
      template.openshift.io/expose-service_ip_port: "{.spec.clusterIP}:{.spec.ports[?(.name==\"web\")].port}"
  spec:
    ports:
    - name: "web"
      port: 8080
- kind: Route
  apiVersion: v1
  metadata:
    name: my-template-route
    annotations:
      template.openshift.io/expose-uri: "http://{.spec.host}{.spec.path}"
  spec:
    path: mypath

上記の部分的なテンプレートでの bind 操作に対する応答例は以下のようになります。

{
  "credentials": {
    "username": "foo",
    "password": "YmFy",
    "service_ip_port": "172.30.12.34:8080",
    "uri": "http://route-test.router.default.svc.cluster.local/mypath"
  }
}

10.7.7. テンプレートの準備ができるまで待機

テンプレートの作成者は、テンプレート内の特定のオブジェクトがサービスカタログ、Template Service Broker または TemplateInstance API によるテンプレートのインスタンス化が完了したとされるまで待機する必要があるかを指定できます。

この機能を使用するには、テンプレート内の BuildBuildConfigDeploymentDeploymentConfigJob または StatefulSet のオブジェクト 1 つ以上に、次のアノテーションでマークを付けてください。

"template.alpha.openshift.io/wait-for-ready": "true"

テンプレートのインスタンス化は、アノテーションのマークが付けられたすべてのオブジェクトが準備できたと報告されるまで、完了しません。同様に、アノテーションが追加オブジェクトが失敗したと報告されるか、固定タイムアウトである 1 時間以内にテンプレートの準備が整わなかった場合に、テンプレートのインスタンス化は失敗します。

インスタンス化の目的で、各オブジェクトの種類の準備状態および失敗は以下のように定義されます。

種類準備状態 (Readines)失敗 (Failure)

Build

オブジェクトでフェーズが完了したと報告される

オブジェクトで、フェーズがキャンセル、エラー、または失敗と報告される

BuildConfig

関連付けられた最新のビルドオブジェクトで、フェーズが完了したと報告される

関連付けられた最新のビルドオブジェクトで、フェーズがキャンセル、エラー、または失敗と報告される

Deployment

オブジェクトで、新しい ReplicaSet やデプロイメントが利用可能であると報告される (これは、オブジェクトに定義された readiness プローブに従う)

オブジェクトで、進捗中の状態が false であると報告される

DeploymentConfig

オブジェクトで、新しい ReplicaController やデプロイメントが利用可能であると報告される (これは、オブジェクトに定義された readiness プローブに従う)

オブジェクトで、進捗中の状態が false であると報告される

Job

オブジェクトでフェーズが完了したと報告される

オブジェクトで失敗が 1 つ以上発生したと報告される

StatefulSet

オブジェクトですべてのレプリカの準備ができていると報告される (プローブがオブジェクトで定義する readiness に従う)

該当なし

以下は、テンプレートサンプルを一部抜粋したものです。この例では、wait-for-ready アノテーションが使用されています。他のサンプルは、OpenShift クイックスタートテンプレートにあります。

kind: Template
apiVersion: v1
metadata:
  name: my-template
objects:
- kind: BuildConfig
  apiVersion: v1
  metadata:
    name: ...
    annotations:
      # wait-for-ready used on BuildConfig ensures that template instantiation
      # will fail immediately if build fails
      template.alpha.openshift.io/wait-for-ready: "true"
  spec:
    ...
- kind: DeploymentConfig
  apiVersion: v1
  metadata:
    name: ...
    annotations:
      template.alpha.openshift.io/wait-for-ready: "true"
  spec:
    ...
- kind: Service
  apiVersion: v1
  metadata:
    name: ...
  spec:
    ...

10.7.8. その他の推奨事項

  • アプリケーションをスムーズに実行するのに十分なリソースを割り当てられるように、「メモリー、CPU」および「ストレージ」をデフォルトサイズに設定します。
  • latest タグが複数のメジャーバージョンで使用されている場合には、イメージからこのタグを参照しないようにします。新規イメージがそのタグにプッシュされると、実行中のアプリケーションが破損してしまう可能性があります。
  • 適切なテンプレートの場合、テンプレートのデプロイ後に変更の必要なく、クリーンにビルド、デプロイが行われます。

10.7.9. 既存オブジェクトからのテンプレートの作成

テンプレートをゼロから作成するのではなく、プロジェクトから既存のオブジェクトをテンプレート形式でエクスポートして、パラメーターを追加したり、カスタマイズしたりして、テンプレートを変更することもできます。プロジェクトのオブジェクトをテンプレート形式でエクスポートするには、以下を実行します。

$ oc export all --as-template=<template_name> > <template_filename>

all ではなく、特定のリソースタイプや複数のリソースを置き換えることも可能です。他の例については、oc export -h を実行してください。

以下は、oc export all に含まれるオブジェクトタイプです。

  • BuildConfig
  • Build
  • DeploymentConfig
  • ImageStream
  • Pod
  • ReplicationController
  • ルート
  • サービス

第11章 コンテナーへのリモートシェルを開く

11.1. 概要

oc rsh コマンドを使用すると、システム上にある各種のツールにローカルでアクセスし、管理することができます。セキュアシェル (SSH) は、アプリケーションへのセキュアな接続を提供する基礎となるテクノロジーであり、これは業界標準になっています。シェル環境を使ったアプリケーションへのアクセスは Security-Enhanced Linux (SELinux) ポリシーで保護され、制限されます。

11.2. セキュアなシェルセッションの開始

コンテナーへのリモートシェルセッションを開きます。

$ oc rsh <pod>

リモートシェルの使用時には、コンテナー内で実行しているかのようにコマンドを実行でき、モニタリングやデバッグ、およびコンテナー内で実行されているものに固有の CLI コマンドの使用などのローカルの操作を実行できます。

たとえば MySQL コンテナーの場合、mysql コマンド」を起動し、プロンプトを使用して SELECT コマンドを入力することでデータベース内のレコード数をカウントできます。また、検証には ps(1) および ls(1) などのコマンドを使用することもできます。

BuildConfigs および DeployConfigs は内容の表示方法や、(コンテナーを内部に含む) Pod を必要に応じて作成し、取り外す方法を定義します。加えられる変更は永続化しません。コンテナー内で直接変更を加えても、そのコンテナーが破棄され再ビルドされると加えた変更は存在しなくなります。

注記

oc exec はコマンドをリモートで実行するために使用できます。しかしながら、oc rsh コマンドの使用がリモートシェルを永続的に開いた状態にするより簡単な方法になります。

11.3. セキュアなシェルセッションのヘルプ

使用方法やオプションについてのヘルプ、例を参照するには、以下を実行します。

$ oc rsh -h

第12章 サービスアカウント

12.1. 概要

ユーザーが OpenShift Container Platform CLI または web コンソールを使用する場合、API トークンは OpenShift API に対して認証を行いますが、一般ユーザーの認証情報が利用できない場合、通常各種コンポーネントが API 呼び出しを別個に実行します。以下はその例になります。

  • レプリケーションコントローラーが Pod を作成するか、または削除するために API 呼び出しを実行する。
  • コンテナー内のアプリケーションが検出の目的で API 呼び出しを実行する。
  • 外部アプリケーションがモニタリングおよび統合目的で API 呼び出しを実行する。

サービスアカウントは、一般ユーザーの認証情報を共有せずに API アクセスをより柔軟に制御する方法を提供します。

12.2. ユーザー名およびグループ

すべてのサービスアカウントには、一般ユーザーのようにロールを付与できるユーザー名が関連付けられています。ユーザー名はそのプロジェクトおよび名前から派生します。

system:serviceaccount:<project>:<name>

たとえば、view (表示) ロールを top-secret プロジェクトの robot サービスアカウントに追加するには、以下を実行します。

$ oc policy add-role-to-user view system:serviceaccount:top-secret:robot
重要

プロジェクトで特定のサービスアカウントにアクセスを付与する必要がある場合は、-z フラグを使用できます。サービスアカウントが属するプロジェクトから -z フラグを使用し、<serviceaccount_name> を指定します。これによりタイプミスの発生する可能性が減り、アクセスを指定したサービスアカウントのみに付与できるため、この方法を使用することを強くお勧めします。以下は例になります。

 $ oc policy add-role-to-user <role_name> -z <serviceaccount_name>

プロジェクトから実行しない場合は、以下の例に示すように -n オプションを使用してこれが適用されるプロジェクトの namespace を指定します。

すべてのサービスアカウントは以下の 2 つのグループのメンバーでもあります。

system:serviceaccount
システムのすべてのサービスアカウントが含まれます。
system:serviceaccount:<project>
指定されたプロジェクトのすべてのサービスアカウントが含まれます。

たとえば、すべてのプロジェクトのすべてのサービスアカウントが top-secret プロジェクトのリソースを表示できるようにするには、以下を実行します。

$ oc policy add-role-to-group view system:serviceaccount -n top-secret

managers プロジェクトのすべてのサービスアカウントが top-secret プロジェクトのリソースを編集できるようにするには、以下を実行します。

$ oc policy add-role-to-group edit system:serviceaccount:managers -n top-secret

12.3. デフォルトのサービスアカウントおよびロール

3 つのサービスアカウントがすべてのプロジェクトで自動的に作成されます。

サービスアカウント使用法

builder

ビルド Pod で使用されます。これには system:image-builder ロールが付与されます。このロールは、内部 Docker レジストリーを使用してイメージをプロジェクトのイメージストリームにプッシュすることを可能にします。

deployer

デプロイメント Pod で使用され、system:deployer ロールが付与されます。このロールは、プロジェクトでレプリケーションコントローラーや Pod を表示したり、変更したりすることを可能にします。

default

別のサービスアカウントが指定されていない限り、その他すべての Pod を実行するために使用されます。

プロジェクトのすべてのサービスアカウントには system:image-puller ロールが付与されます。このロールは、内部 Docker レジストリーを使用してプロジェクトのイメージストリームからイメージをプルすることを可能にします。

12.4. サービスアカウントの管理

サービスアカウントは、各プロジェクトに存在する API オブジェクトです。サービスアカウントを管理するには、sa または serviceaccount オブジェクトタイプと共に oc コマンドを使用するか、または web コンソールを使用することができます。

現在のプロジェクトの既存のサービスアカウントの一覧を取得するには、以下を実行します。

$ oc get sa
NAME       SECRETS   AGE
builder    2         2d
default    2         2d
deployer   2         2d

新規のサービスアカウントを作成するには、以下を実行します。

$ oc create sa robot
serviceaccount "robot" created

サービスアカウントの作成後すぐに、以下の 2 つのシークレットが自動的に追加されます。

  • API トークン
  • OpenShift Container レジストリーの認証情報

これらはサービスアカウントを記述すると表示できます。

$ oc describe sa robot
Name:		robot
Namespace:	project1
Labels:		<none>
Annotations:	<none>

Image pull secrets:	robot-dockercfg-qzbhb

Mountable secrets: 	robot-token-f4khf
                   	robot-dockercfg-qzbhb

Tokens:            	robot-token-f4khf
                   	robot-token-z8h44

システムはサービスアカウントに API トークンとレジストリーの認証情報が常にあることを確認します。

生成される API トークンとレジストリーの認証情報は期限切れになることはありませんが、シークレットを削除することで取り消すことができます。シークレットが削除されると、新規のシークレットが自動生成され、これに置き換わります。

12.5. 許可されたシークレットの管理

API 認証情報を提供するほかに、Pod のサービスアカウントは Pod が使用できるシークレットを決定します。

Pod は以下の 2 つの方法でシークレットを使用します。

  • イメージプルシークレットの使用: Pod のコンテナーのイメージをプルするために使用される認証情報を提供します。
  • マウント可能なシークレットの使用。シークレットの内容をファイルとしてコンテナーに挿入します。

サービスアカウントの Pod がシークレットをイメージプルシークレットとして使用できるようにするには、以下を実行します。

$ oc secrets link --for=pull <serviceaccount-name> <secret-name>

サービスアカウントの Pod がシークレットをマウントできるようにするには、以下を実行します。

$ oc secrets link --for=mount <serviceaccount-name> <secret-name>
注記

シークレットをそれらを参照するサービスアカウントのみに制限することはデフォルトで無効にされています。これは、serviceAccountConfig.limitSecretReferences がマスター設定ファイルで false (デフォルト設定) に設定されている場合はシークレットを --for=mount オプションを使ってサービスアカウントの Pod にマウントする必要がないことを意味します。ただし serviceAccountConfig.limitSecretReferences の値にかかわらず、--for=pull オプションを使用してイメージプルシークレットの使用を有効にする必要はあります。

以下の例では、シークレットを作成し、これをサービスアカウントに追加しています。

$ oc create secret generic secret-plans \
    --from-file=plan1.txt \
    --from-file=plan2.txt
secret/secret-plans

$ oc create secret docker-registry my-pull-secret \
    --docker-username=mastermind \
    --docker-password=12345 \
    --docker-email=mastermind@example.com
secret/my-pull-secret

$ oc secrets link robot secret-plans --for=mount

$ oc secrets link robot my-pull-secret --for=pull

$ oc describe serviceaccount robot
Name:               robot
Labels:             <none>
Image pull secrets:	robot-dockercfg-624cx
                   	my-pull-secret

Mountable secrets: 	robot-token-uzkbh
                   	robot-dockercfg-624cx
                   	secret-plans

Tokens:            	robot-token-8bhpp
                   	robot-token-uzkbh

12.6. コンテナー内でのサービスアカウントの認証情報の使用

Pod が作成されると、Pod はサービスアカウントを指定し (またはデフォルトのサービスアカウントを使用し)、サービスアカウントの API 認証情報と参照されるシークレットを使用することができます。

Pod のサービスアカウントの API トークンが含まれるファイルは /var/run/secrets/kubernetes.io/serviceaccount/token に自動的にマウントされます。

このトークンは Pod のサービスアカウントとして API 呼び出しを実行するために使用できます。以下の例では、トークンによって識別されるユーザーについての情報を取得するために users/~ API を呼び出しています。

$ TOKEN="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)"

$ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
    "https://openshift.default.svc.cluster.local/oapi/v1/users/~" \
    -H "Authorization: Bearer $TOKEN"

kind: "User"
apiVersion: "user.openshift.io/v1"
metadata:
  name: "system:serviceaccount:top-secret:robot"
  selflink: "/oapi/v1/users/system:serviceaccount:top-secret:robot"
  creationTimestamp: null
identities: null
groups:
  - "system:serviceaccount"
  - "system:serviceaccount:top-secret"

12.7. サービスアカウントの認証情報の外部での使用

同じトークンを、API に対して認証する必要のある外部アプリケーションに配布することができます。

以下の構文を使用してサービスアカウントの API トークンを表示します。

$ oc describe secret <secret-name>

以下に例を示します。

$ oc describe secret robot-token-uzkbh -n top-secret
Name:		robot-token-uzkbh
Labels:		<none>
Annotations:	kubernetes.io/service-account.name=robot,kubernetes.io/service-account.uid=49f19e2e-16c6-11e5-afdc-3c970e4b7ffe

Type:	kubernetes.io/service-account-token

Data

token:	eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

$ oc login --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Logged into "https://server:8443" as "system:serviceaccount:top-secret:robot" using the token provided.

You don't have any projects. You can try to create a new project, by running

    $ oc new-project <projectname>

$ oc whoami
system:serviceaccount:top-secret:robot

第13章 イメージの管理

13.1. 概要

「イメージストリーム」は、タグで識別される数多くの「コンテナーイメージ」で構成されます。これは Docker イメージリポジトリーのような関連イメージの単一仮想ビューを提供します。

イメージストリームの監視により、ビルドおよびデプロイメントは新規イメージの追加または変更時に通知を受信し、それぞれビルドまたはデプロイメントを実行してこれに対応します。

イメージのレジストリーが置かれる場所やレジストリー関連の認証要件、およびビルドやデプロイメントで必要とされる動作が何であるかによって、イメージと対話し、イメージストリームをセットアップする方法は異なり、数多くの方法でこれらを実行することができます。以下のセクションではこれらのトピックについて扱います。

13.2. イメージのタグ付け

OpenShift Container Platform イメージストリームとそのタグを使用する前に、コンテナーイメージのコンテキストにおけるイメージタグ全般について理解しておくと便利です。

コンテナーイメージにはその内容を直感的に判別できるようにする名前 (タグ) を追加できます。タグの一般的な使用例として、イメージに含まれるもののバージョンを指定するために使用できます。ruby という名前のイメージがある場合、Ruby の 2.0 バージョン用に 2.0 という名前のタグを使用したり、リポジトリー全体における最新のビルドされたイメージを示す latest というタグを使用したりすることができます。

docker CLI を使用してイメージと直接対話する場合、docker tag コマンドを使用してタグを追加できます。基本的に、この操作は複数の部分で構成されるエイリアスをイメージに追加する操作です。これらの複数の部分には以下が含まれます。

<registry_server>/<user_name>/<image_name>:<tag>

上記の <user_name> の部分は、イメージが内部レジストリー (OpenShift Container レジストリー) を使用して OpenShift Container Platform 環境に保存される場合には、「プロジェクト」または「namespace」も参照することがあります。

OpenShift Container Platform は docker tag コマンドに似た oc tag コマンドを提供しますが、これらはイメージ上で直接動作するのではなくイメージストリームで動作します。

注記

docker CLI を使用してイメージに直接タグ付けする方法についての詳細は、Red Hat Enterprise Linux 7 の『Getting Started with Containers』ドキュメントを参照してください。

13.2.1. タグのイメージストリームへの追加

OpenShift Container Platform のイメージストリームはタグで識別されるゼロまたは 1 つ以上のコンテナーイメージで構成されることに留意した上で、oc tag コマンドを使用してタグをイメージストリームに追加することができます。

$ oc tag <source> <destination>

たとえば、ruby イメージストリームの static-2.0 タグを ruby イメージストリーム 2.0 タグの現行のイメージを常に参照するように設定するには、以下を実行します。

$ oc tag ruby:2.0 ruby:static-2.0

これにより、ruby イメージストリームに static-2.0 という名前のイメージストリームタグが新たに作成されます。この新規タグは、oc tag の実行時に ruby:2.0 イメージストリームタグが参照したイメージ ID を直接参照し、これが参照するイメージが変更されることがありません。

各種のタグを利用できます。デフォルト動作では、特定の時点の特定のイメージを参照する 永続 タグを使用します。ソースが変更されても新規 (宛先) タグは変更されません。

トラッキング タグの場合は、宛先タグのメタデータがソースタグのインポート時に更新されます。宛先タグがソースタグの変更時に常に更新されるようにするには、--alias=true フラグを使用します。

$ oc tag --alias=true <source> <destination>
注記

永続的なエイリアス (latest または stable など) を作成するには トラッキング タグを使用します。このタグは単一イメージストリーム内で のみ 適切に機能します。複数のイメージストリーム間で使用されるエイリアスを作成しようとするとエラーが生じます。

さらに --scheduled=true フラグを追加して宛先タグが定期的に更新 (再インポートなど) されるようにできます。期間はシステムレベルで「グローバルに設定」できます。詳細は、「タグおよびイメージメタデータのインポート」を参照してください。

--reference フラグはインポートされないイメージストリームを作成します。このタグは単にソースの場所を参照しますが、これを永続的に参照します。

Docker に対して、統合レジストリーからタグ付けされたイメージを常にフェッチするよう指示するには、--reference-policy=local を使用します。レジストリーは「プルスルー (pull-through) 機能」を使用してイメージをクライアントに提供します。デフォルトで、イメージ Blob はレジストリーによってローカルにミラーリングされるので、イメージ Blob が次回必要になると、より早くプルされます。またこのフラグは --insecure-registry を Docker デーモンに指定しなくても、イメージストリームに「セキュアでないアノテーション」があるか、またはタグに「セキュアでないインポートポリシー」がある限り、セキュアでないレジストリーからもプルできます。

13.2.2. 推奨されるタグ付け規則

イメージは時間の経過と共に変化するもので、それらのタグはその変化を反映します。イメージタグはビルドされる最新イメージを常に参照します。

タグ名にあまりにも多くの情報が組み込まれる場合には (例: v2.0.1-may-2016)、タグはイメージの 1 つのリビジョンのみを参照し、更新されることがなくなります。デフォルトのイメージのプルーニングオプションを使用しても、このようなイメージは削除されません。非常に大規模なクラスターでは、イメージが修正されるたびに新規タグが作成される設定の場合に、古くなって久しいイメージのタグメタデータが過剰になり、etcd データストアがいっぱいになる可能性があります。

一方、タグの名前が v2.0 である場合はイメージリビジョンの数が多くなることが予想されます。これにより「タグ履歴」が長くなるため、イメージプルーナーが、過去の使われなくなったイメージを削除する可能性が高くなります。詳細は、「イメージのプルーニング」を参照してください。

タグの名前付け規則は各自で定めることができますが、ここでは <image_name>:<image_tag> 形式のいくつかの例を見てみましょう。

表13.1 イメージタグの名前付け規則

説明

リビジョン

myimage:v2.0.1

アーキテクチャー

myimage:v2.0-x86_64

ベースイメージ

myimage:v1.2-centos7

最新 (不安定な可能性がある)

myimage:latest

最新 (安定性がある)

myimage:stable

タグ名に日付を含める必要がある場合、古くなり使用されなくなったイメージおよび istags を定期的に検査し、これらを削除してください。そうしないと、古いイメージによるリソース使用量が増大する可能性があります。

13.2.3. タグのイメージストリームからの削除

タグをイメージストリームから完全に削除するには、以下を実行します。

$ oc delete istag/ruby:latest

または以下を実行します。

$ oc tag -d ruby:latest

13.2.4. イメージストリームでのイメージの参照

以下の参照タイプを使用して、イメージをイメージストリームで参照できます。

  • ImageStreamTag は、所定のイメージストリームおよびタグのイメージを参照し、取得するために使用されます。この名前は以下の規則に基づいて付けられます。

    <image_stream_name>:<tag>
  • ImageStreamImage は、所定のイメージストリームおよびイメージ名のイメージを参照し、取得するために使用されます。この名前は以下の規則に基づいて付けられます。

    <image_stream_name>@<id>

    <id> は、ダイジェストとも呼ばれる特定イメージのイミュータブルな ID です。

  • DockerImage は、所定の外部レジストリーのイメージを参照し、取得するために使用されます。この名前は、以下のような標準の Docker プル仕様 に基づいて付けられます。

    openshift/ruby-20-centos7:2.0
    注記

    タグが指定されていない場合、latest タグが使用されることが想定されます。

    サードパーティーのレジストリーを参照することもできます。

    registry.access.redhat.com/rhel7:latest

    またはダイジェストでイメージを参照できます。

    centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e

CentOS イメージストリームのサンプル などのイメージストリーム定義のサンプルを表示する場合、それらには ImageStreamTag の定義や DockerImage の参照が含まれる一方で、ImageStreamImage に関連するものは何も含まれていないことに気づかれることでしょう。

これは、イメージストリームでのイメージのインポートまたはイメージのタグ付けを行う場合は常に ImageStreamImage オブジェクトが OpenShift Container Platform に自動的に作成されるためです。イメージストリームを作成するために使用するイメージストリーム定義で ImageStreamImage オブジェクトを明示的に定義する必要はありません。

イメージのオブジェクト定義は、イメージストリーム名および ID を使用し、ImageStreamImage 定義を取得して確認することができます。

$ oc export isimage <image_stream_name>@<id>
注記

以下を実行して所定のイメージストリームの有効な <id> 値を確認することができます。

$ oc describe is <image_stream_name>

たとえば、ruby イメージストリームから ruby@3a335d7 の名前および ID を使って ImageStreamImage を検索します。

ImageStreamImage で取得されるイメージオブジェクトの定義

$ oc export isimage ruby@3a335d7

apiVersion: v1
image:
  dockerImageLayers:
  - name: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
    size: 0
  - name: sha256:ee1dd2cb6df21971f4af6de0f1d7782b81fb63156801cfde2bb47b4247c23c29
    size: 196634330
  - name: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
    size: 0
  - name: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
    size: 0
  - name: sha256:ca062656bff07f18bff46be00f40cfbb069687ec124ac0aa038fd676cfaea092
    size: 177723024
  - name: sha256:63d529c59c92843c395befd065de516ee9ed4995549f8218eac6ff088bfa6b6e
    size: 55679776
  dockerImageMetadata:
    Architecture: amd64
    Author: SoftwareCollections.org <sclorg@redhat.com>
    Config:
      Cmd:
      - /bin/sh
      - -c
      - $STI_SCRIPTS_PATH/usage
      Entrypoint:
      - container-entrypoint
      Env:
      - PATH=/opt/app-root/src/bin:/opt/app-root/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
      - STI_SCRIPTS_URL=image:///usr/libexec/s2i
      - STI_SCRIPTS_PATH=/usr/libexec/s2i
      - HOME=/opt/app-root/src
      - BASH_ENV=/opt/app-root/etc/scl_enable
      - ENV=/opt/app-root/etc/scl_enable
      - PROMPT_COMMAND=. /opt/app-root/etc/scl_enable
      - RUBY_VERSION=2.2
      ExposedPorts:
        8080/tcp: {}
      Image: d9c3abc5456a9461954ff0de8ae25e0e016aad35700594714d42b687564b1f51
      Labels:
        build-date: 2015-12-23
        io.k8s.description: Platform for building and running Ruby 2.2 applications
        io.k8s.display-name: Ruby 2.2
        io.openshift.builder-base-version: 8d95148
        io.openshift.builder-version: 8847438ba06307f86ac877465eadc835201241df
        io.openshift.s2i.scripts-url: image:///usr/libexec/s2i
        io.openshift.tags: builder,ruby,ruby22
        io.s2i.scripts-url: image:///usr/libexec/s2i
        license: GPLv2
        name: CentOS Base Image
        vendor: CentOS
      User: "1001"
      WorkingDir: /opt/app-root/src
    ContainerConfig: {}
    Created: 2016-01-26T21:07:27Z
    DockerVersion: 1.8.2-el7
    Id: 57b08d979c86f4500dc8cad639c9518744c8dd39447c055a3517dc9c18d6fccd
    Parent: d9c3abc5456a9461954ff0de8ae25e0e016aad35700594714d42b687564b1f51
    Size: 430037130
    apiVersion: "1.0"
    kind: DockerImage
  dockerImageMetadataVersion: "1.0"
  dockerImageReference: centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e
  metadata:
    creationTimestamp: 2016-01-29T13:17:45Z
    name: sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e
    resourceVersion: "352"
    uid: af2e7a0c-c68a-11e5-8a99-525400f25e34
kind: ImageStreamImage
metadata:
  creationTimestamp: null
  name: ruby@3a335d7
  namespace: openshift
  selflink: /oapi/v1/namespaces/openshift/imagestreamimages/ruby@3a335d7

13.3. Kubernetes リソースでのイメージストリームの使用

OpenShift Container Platform のネイティブリソースであるイメージストリームは、「ビルド」または「デプロイメント」などの OpenShift Container Platform で利用可能なネイティブリソースの残りすべてと、追加設定なしで連携します。現時点で、イメージストリームは「ジョブ」「レプリケーションコントローラー」、レプリカセットまたは「Kubernetes デプロイメント」などのネイティブの Kubernetes リソースと連携させることも可能です。

クラスター管理者は使用可能な「リソースを正確に設定」することができます。

この機能が有効な場合、リソースの image フィールドにイメージストリームの参照を配置することができます。この機能を使用する場合、リソースと同じプロジェクトにあるイメージストリームのみを参照することができます。イメージストリームの参照は、単一セグメントの値で構成される必要があります。たとえば ruby:2.4 の場合、ruby2.4 という名前のタグを持ち、参照するリソースと同じプロジェクトにあるイメージストリームの名前になります。

この機能を有効にする 2 つの方法があります。

  1. 特定のリソースでイメージストリームの解決を有効にする。これにより、このリソースのみがイメージフィールドのイメージストリーム名を使用できます。
  2. イメージストリームでイメージストリームの解決を有効にする。これにより、このイメージストリームを参照するすべてのリソースがイメージフィールドのイメージストリーム名を使用できます。

上記の操作のいずれも oc set image-lookup を使用して実行できます。たとえば、以下のコマンドはすべてのリソースが mysql という名前のイメージストリームを参照できるようにします。

$ oc set image-lookup mysql

これにより、Imagestream.spec.lookupPolicy.local フィールドが true に設定されます。

イメージルックアップが有効なイメージストリーム

apiVersion: v1
kind: ImageStream
metadata:
  annotations:
    openshift.io/display-name: mysql
  name: mysql
  namespace: myproject
spec:
  lookupPolicy:
    local: true

有効な場合には、この動作はイメージストリーム内のすべてのタグに対して有効化されます。

以下を使用してイメージストリームをクエリーし、このオプションが設定されているかどうかを確認できます。

$ oc set image-lookup

さらに、特定のリソースでイメージルックアップを有効にすることもできます。以下のコマンドは mysql という名前の Kubernetes デプロイメントがイメージストリームを使用できるようにします。

$ oc set image-lookup deploy/mysql

これにより、alpha.image.policy.openshift.io/resolve-names アノテーションがデプロイメントに設定されます。

イメージルックアップが有効にされたデプロイメント

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
  namespace: myproject
spec:
  replicas: 1
  template:
    metadata:
      annotations:
        alpha.image.policy.openshift.io/resolve-names: '*'
    spec:
      containers:
      - image: mysql:latest
        imagePullPolicy: Always
        name: mysql

イメージルックアップを無効にするには、--enabled=false を渡します。

$ oc set image-lookup deploy/mysql --enabled=false

13.4. イメージプルポリシー

Pod のそれぞれのコンテナーにはコンテナーイメージがあります。イメージを作成し、これをレジストリーにプッシュすると、イメージを Pod で参照できます。

OpenShift Container Platform はコンテナーを作成すると、コンテナーの imagePullPolicy を作成して、コンテナーの起動前にイメージをプルする必要があるかどうかを決定します。imagePullPolicy には以下の 3 つの値を使用できます。

  • Always: 常にイメージをプルします。
  • IfNotPresent: イメージがノード上にない場合にのみイメージをプルします。
  • Never: イメージをプルしません。

コンテナーの imagePullPolicy パラメーターが指定されていない場合、OpenShift Container Platform はイメージのタグに基づいてこれを設定します。

  1. タグが 最新 の場合、OpenShift Container Platform は imagePullPolicyAlways にデフォルト設定します。
  2. それ以外の場合に、OpenShift Container Platform は imagePullPolicyIfNotPresent にデフォルト設定します。

13.5. 内部レジストリーへのアクセス

イメージのプッシュまたはプルを実行するために OpenShift Container Platform の内部レジストリーに直接アクセスできます。たとえば、これは イメージの手動プッシュによってイメージストリームを作成する場合や、単にイメージに対して docker pull を直接実行する場合に役立ちます。

内部レジストリーは OpenShift Container Platform API と同じ「トークン」を使用して認証します。内部レジストリーに対して docker login を実行するには、任意のユーザー名およびメールを選択できますが、パスワードは有効な OpenShift Container Platform トークンである必要があります。

内部レジストリーにログインするには、以下を実行します。

  1. OpenShift Container Platform にログインします。

    $ oc login
  2. アクセストークンを取得します。

    $ oc whoami -t
  3. トークンを使用して内部レジストリーにログインします。docker をシステムにインストールしておく必要があります。

    $ docker login -u <user_name> -e <email_address> \
        -p <token_value> <registry_server>:<port>
    注記

    使用するレジストリー IP またはホスト名およびポートが不明な場合は、クラスター管理者に問い合わせてください。

イメージをプルするには、要求される imagestreams/layers に対する get 権限が、この認証済みのユーザーに割り当てられている必要があります。また、イメージをプッシュするには、認証済みのユーザーに、要求される imagestreams/layers に対する update 権限が割り当てられている必要があります。

デフォルトで、プロジェクトのすべてのサービスアカウントは同じプロジェクトの任意のイメージをプルする権限を持ち、builder サービスアカウントには同じプロジェクトの任意のイメージをプッシュする権限を持ちます。

13.6. イメージプルシークレットの使用

承認されていないユーザーが特定イメージにアクセスできないように、「Docker レジストリー」のセキュリティー保護することができます。「OpenShift Container Platform の内部レジストリーを使用」し、同じプロジェクトにあるイメージストリームからプルしている場合は、Pod のサービスアカウントに適切なパーミッションがすでに設定されているので、追加のアクションは不要です。

ただし、OpenShift Container Platform プロジェクト全体でイメージを参照する場合や、セキュリティー保護されたレジストリーからイメージを参照するなどの他のシナリオでは、追加の設定手順が必要になります。以下のセクションでは、それらのシナリオと必要な手順について詳しく説明します。

13.6.1. Pod が複数のプロジェクト間でのイメージを参照できるようにする設定

内部レジストリーを使用している場合で project-a の Pod が project-b のイメージを参照できるようにするには、project-a のサービスアカウントが project-bsystem:image-puller ロールにバインドされている必要があります。

$ oc policy add-role-to-user \
    system:image-puller system:serviceaccount:project-a:default \
    --namespace=project-b

このロールを追加した後に、デフォルトのサービスアカウントを参照する project-a の Pod は project-b からイメージをプルできるようになります。

project-a のすべてのサービスアカウントにアクセスを許可するには、グループを使用します。

$ oc policy add-role-to-group \
    system:image-puller system:serviceaccounts:project-a \
    --namespace=project-b

13.6.2. Pod が他のセキュアなレジストリーからイメージを参照できるようにする設定

.dockercfg ファイル (または新規 Docker クライアントの場合は $HOME/.docker/config.json) は、ユーザーがセキュア/非セキュアなレジストリーに事前にログインしている場合にそのユーザーの情報を保存する Docker 認証情報ファイルです。

OpenShift Container Platform の内部レジストリーにないセキュリティー保護されたコンテナーイメージをプルするには、Docker 認証情報で プルシークレット を作成し、これをサービスアカウントに追加する必要があります。

セキュリティー保護されたレジストリーの .dockercfg ファイルがある場合、以下を実行してそのファイルからシークレットを作成できます。

$ oc create secret generic <pull_secret_name> \
    --from-file=.dockercfg=<path/to/.dockercfg> \
    --type=kubernetes.io/dockercfg

または、$HOME/.docker/config.json ファイルがある場合は以下を実行します。

$ oc create secret generic <pull_secret_name> \
    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    --type=kubernetes.io/dockerconfigjson

セキュリティー保護されたレジストリーの Docker 認証情報がない場合は、以下を実行してシークレットを作成できます。

$ oc create secret docker-registry <pull_secret_name> \
    --docker-server=<registry_server> \
    --docker-username=<user_name> \
    --docker-password=<password> \
    --docker-email=<email>

Pod のイメージをプルするためのシークレットを使用するには、そのシークレットをサービスアカウントに追加する必要があります。この例では、サービスアカウントの名前は Pod が使用するサービスアカウントの名前に一致している必要があります。default はデフォルトのサービスアカウントです。

$ oc secrets link default <pull_secret_name> --for=pull

ビルドイメージのプッシュおよびプルにシークレットを使用するには、シークレットは Pod 内でマウント可能である必要があります。以下でこれを実行できます。

$ oc secrets link builder <pull_secret_name>

13.6.2.1. 委任された認証を使用したプライベートレジストリーからのプル

プライベートレジストリーは認証を別個のサービスに委任できます。この場合、イメージプルシークレットは認証およびレジストリーのエンドポイントの両方に対して定義されている必要があります。

注記

Red Hat Container Catalog のサードパーティーのイメージは Red Hat Connect Partner Registry (registry.connect.redhat.com) から提供されます。このレジストリーは認証を sso.redhat.com に委任するため、以下の手順が適用されます。

  1. 委任された認証サーバーのシークレットを作成します。

    $ oc create secret docker-registry \
        --docker-server=sso.redhat.com \
        --docker-username=developer@example.com \
        --docker-password=******** \
        --docker-email=unused \
        redhat-connect-sso
    
    secret/redhat-connect-sso
  2. プライベートレジストリーのシークレットを作成します。

    $ oc create secret docker-registry \
        --docker-server=privateregistry.example.com \
        --docker-username=developer@example.com \
        --docker-password=******** \
        --docker-email=unused \
        private-registry
    
    secret/private-registry
注記

Red Hat Connect Partner Registry (registry.connect.redhat.com) は自動生成される dockercfg シークレットタイプを受け入れません (BZ#1476330)。汎用のファイルベースのシークレットは docker login コマンドで生成されるファイルを使用して作成する必要があります。

$ docker login registry.connect.redhat.com --username developer@example.com

Password: *************
Login Succeeded

$ oc create secret generic redhat-connect --from-file=.dockerconfigjson=.docker/config.json

$ oc secrets link default redhat-connect --for=pull

13.7. タグおよびイメージメタデータのインポート

イメージストリームは、外部 Docker イメージレジストリーのイメージリポジトリーからタグおよびイメージメタデータをインポートするように設定できます。これは複数の異なる方法で実行できます。

  • oc import-image コマンドで --from オプションを使用してタグとイメージ情報を手動でインポートできます。

    $ oc import-image <image_stream_name>[:<tag>] --from=<docker_image_repo> --confirm

    以下に例を示します。

    $ oc import-image my-ruby --from=docker.io/openshift/ruby-20-centos7 --confirm
    The import completed successfully.
    
    Name:			my-ruby
    Created:		Less than a second ago
    Labels:			<none>
    Annotations:		openshift.io/image.dockerRepositoryCheck=2016-05-06T20:59:30Z
    Docker Pull Spec:	172.30.94.234:5000/demo-project/my-ruby
    
    Tag	Spec					Created			PullSpec							Image
    latest	docker.io/openshift/ruby-20-centos7	Less than a second ago	docker.io/openshift/ruby-20-centos7@sha256:772c5bf9b2d1e8...	<same>

    また、latest だけではなくイメージのすべてのタグをインポートするには --all フラグを追加することもできます。

  • OpenShift Container Platform のほとんどのオブジェクトの場合と同様に、CLI を使用して JSON または YAML 定義を作成し、これをファイルに保存してからオブジェクトを作成できます。spec.dockerImageRepository フィールドをイメージの Docker プル仕様に設定します。

    apiVersion: "v1"
    kind: "ImageStream"
    metadata:
      name: "my-ruby"
    spec:
      dockerImageRepository: "docker.io/openshift/ruby-20-centos7"

    次にオブジェクトを作成します。

    $ oc create -f <file>

外部 Docker レジストリーのイメージを参照するイメージストリームを作成する場合、OpenShift Container Platform は短時間で外部レジストリーと通信し、イメージについての最新情報を取得します。

タグおよびイメージメタデータの同期後に、イメージストリームオブジェクトは以下のようになります。

apiVersion: v1
kind: ImageStream
metadata:
  name: my-ruby
  namespace: demo-project
  selflink: /oapi/v1/namespaces/demo-project/imagestreams/my-ruby
  uid: 5b9bd745-13d2-11e6-9a86-0ada84b8265d
  resourceVersion: '4699413'
  generation: 2
  creationTimestamp: '2016-05-06T21:34:48Z'
  annotations:
    openshift.io/image.dockerRepositoryCheck: '2016-05-06T21:34:48Z'
spec:
  dockerImageRepository: docker.io/openshift/ruby-20-centos7
  tags:
    -
      name: latest
      annotations: null
      from:
        kind: DockerImage
        name: 'docker.io/openshift/ruby-20-centos7:latest'
      generation: 2
      importPolicy: {  }
status:
  dockerImageRepository: '172.30.94.234:5000/demo-project/my-ruby'
  tags:
    -
      tag: latest
      items:
        -
          created: '2016-05-06T21:34:48Z'
          dockerImageReference: 'docker.io/openshift/ruby-20-centos7@sha256:772c5bf9b2d1e8e80742ed75aab05820419dc4532fa6d7ad8a1efddda5493dc3'
          image: 'sha256:772c5bf9b2d1e8e80742ed75aab05820419dc4532fa6d7ad8a1efddda5493dc3'
          generation: 2

タグおよびイメージメタデータを同期するため、タグをスケジュールに応じて外部レジストリーのクエリーを実行できるよう設定できます。これは、「タグのイメージストリームへの追加」で説明されているように --scheduled=true フラグを oc tag コマンドに設定して実行できます。

または、タグの定義で importPolicy.scheduledtrue に設定することもできます。

apiVersion: v1
kind: ImageStream
metadata:
  name: ruby
spec:
  tags:
  - from:
      kind: DockerImage
      name: openshift/ruby-20-centos7
    name: latest
    importPolicy:
      scheduled: true

13.7.1. 非セキュアなレジストリーからのイメージのインポート

イメージストリームは、自己署名型の証明書を使って署名されたものを使用する場合や、HTTPS ではなく単純な HTTP を使用する場合など、非セキュアなイメージレジストリーからタグおよびイメージメタデータをインポートするように設定できます。

これを設定するには、openshift.io/image.insecureRepository アノテーションを追加し、これを true に設定します。この設定はレジストリーへの接続時の証明書の検証をバイパスします。

kind: ImageStream
apiVersion: v1
metadata:
  name: ruby
  annotations:
    openshift.io/image.insecureRepository: "true" 1
  spec:
    dockerImageRepository: my.repo.com:5000/myimage
1
openshift.io/image.insecureRepository アノテーション true に設定します。
重要

このオプションは統合レジストリーに対して、イメージの提供時にイメージストリームでタグ付けされた外部イメージについて非セキュアなトランスポートにフォールバックするよう指示しますが、これにはリスクが伴います。可能な場合には、istag にのみ非セキュアのマークを付けてこのリスクを回避します。

重要

上記の定義はタグおよびイメージメタデータのインポートのみに適用されます。このイメージがクラスターで使用されるようにするには (docker pull を実行できるようにするには)、以下のいずれかが該当している必要があります。

  1. 各ノードには Docker が dockerImageRepository のレジストリーの部分に一致する --insecure-registry フラグで設定されている。詳細は、「ホストの準備」を参照してください。
  2. istag 仕様では referencePolicy.typeLocal に設定されている。詳細は、「参照ポリシー」を参照してください。

13.7.1.1. イメージストリームタグのポリシー

13.7.1.1.1. 非セキュアなタグのインポートポリシー

上記のアノテーションは、特定の ImageStream のすべてのイメージおよびタグに適用されます。より詳細な制御を実行するために、ポリシーをistagsに設定できます。タグの定義の importPolicy.insecuretrue に設定すると、このタグが付けられたイメージについてのみセキュアでないトランスポートへのフォールバックが許可されます。

注記

特定の istag 下のイメージについてのセキュアでないトランスポートへのフォールバックは、イメージストリームにセキュアでないアノテーションが付けられるか、または istag にセキュアでないインポートポリシーが設定されている場合に有効になります。importPolicy.insecure`false に設定されていると、イメージストリームのアノテーションは上書きできません。

13.7.1.1.2. 参照ポリシー

参照ポリシーにより、このイメージストリームタグを参照するリソースがどこからイメージをプルするかを指定できます。これはリモートイメージ (外部レジストリーからインポートされるもの) にのみ適用されます。LocalSource のオプションから選択できます。

Source ポリシーはクライアントに対し、イメージのソースレジストリーから直接プルするように指示します。統合レジストリーは、イメージがクラスターによって管理されていない限り使用されません (これは外部イメージではありません)。このポリシーがデフォルトポリシーになります。

Local ポリシーはクライアントに対し、常に統合レジストリーからプルするように指示します。これは Docker デーモンの設定を変更せずに外部の非セキュアなレジストリーからプルする場合に役立ちます。

このポリシーはイメージストリームタグの使用にのみ適用されます。外部レジストリーの場所を使用してイメージを直接参照したり、プルしたりするコンポーネントまたは操作は内部レジストリーにリダイレクトされません。

「プルスルー (pull-through) 機能」:

このレジストリーの機能はリモートイメージをクライアントに提供します。この機能はデフォルトで有効にされており、ローカルの参照ポリシーが使用されるようにするには有効にされている必要があります。さらにすべての Blob は後のアクセスを速めるためにミラーリングされます。

イメージストリームタグの仕様でポリシーを referencePolicy.type として設定できます。

ローカル参照ポリシーが設定されたセキュアでないタグの例

kind: ImageStream
apiVersion: v1
metadata:
  name: ruby
  tags:
  - from:
      kind: DockerImage
      name: my.repo.com:5000/myimage
    name: mytag
    importPolicy:
      insecure: true 1
    referencePolicy:
      type: Local 2

1
該当レジストリーへの非セキュアな接続を使用するようタグ mytag を設定します。
2
外部イメージをプルするために統合レジストリーを使用するよう mytag を設定します。参照ポリシータイプが Source に設定されている場合、クライアントはイメージを my.repo.com:5000/myimage から直接フェッチします。

13.7.2. プライベートレジストリーからのイメージのインポート

イメージストリームは、プライベートレジストリーからタグおよびイメージメタデータをインポートするように設定できます。これには認証が必要です。

これを設定するには、認証情報を保存するために使用されるシークレットを作成する必要があります。oc create secret コマンドを使用してシークレットを作成する方法については、「Pod が他のセキュリティー保護されたレジストリーからイメージを参照できるようにする」を参照してください。

シークレットが設定されたら、次に新規イメージストリームを作成するか、または oc import-image コマンドを使用します。インポートプロセスで OpenShift Container Platform はシークレットを取得してリモートパーティーに提供します。

注記

セキュアでないレジストリーからインポートする場合には、シークレットに定義されたレジストリーの URL に :80 ポートのサフィックスを追加するようにしてください。追加していない場合にレジストリーからインポートしようとすると、このシークレットは使用されません。

13.7.3. 外部レジストリーの信頼される証明書の追加

インポート元となっているレジストリーが標準の認証局で署名されていない証明書を使用している場合に、システムがレジストリーの証明書または署名認証局を信頼するように明示的に設定する必要があります。これには 、レジストリーインポートコントローラーを実行するホストシステム (通常はマスターノード) に CA 証明書またはレジストリー証明書を追加してください。

証明書または CA 証明書は、ホストシステムの /etc/pki/tls/certs または /etc/pki/ca-trust にそれぞれ追加する必要があります。また証明書の変更を反映するには、update-ca-trust コマンドを Red Hat ディストリビューションで実行して、マスターサービスを再起動する必要があります。

13.7.4. 複数のプロジェクト間でのイメージのインポート

イメージストリームは、異なるプロジェクトから内部レジストリーのタグおよびイメージメタデータをインポートするように設定できます。推奨される方法としては、「タグのイメージストリーム」で説明されている oc tag コマンドを使用できます。

$ oc tag <source_project>/<image_stream>:<tag> <new_image_stream>:<new_tag>

別の方法として、プル仕様を使用して他のプロジェクトからイメージを手動でインポートすることもできます。

警告

以下の方法については使用しないことを強く推奨します。この使用は oc tag の使用だけでは不十分な場合にのみに使用する必要があります。

  1. 最初に、他のプロジェクトにアクセスするために必要なポリシーを追加します。

    $ oc policy add-role-to-group \
        system:image-puller \
        system:serviceaccounts:<destination_project> \
        -n <source_project>

    これにより、<destination_project><source_project> からイメージをプルできます。

  2. ポリシーが有効な場合、イメージを手動でインポートできます。

    $ oc import-image <new_image_stream> --confirm \
        --from=<docker_registry>/<source_project>/<image_stream>

13.7.5. イメージの手動プッシュによるイメージストリームの作成

イメージストリームはイメージを内部レジストリーに手動でプッシュすると自動的に作成されます。これは OpenShift Container Platform 内部レジストリーを使用している場合にのみ可能です。

この手順を実行する前に、以下の条件を満たしている必要があります。

  • プッシュ先となる宛先プロジェクトがすでに存在している必要がある。
  • ユーザーはそのプロジェクトで {get, update} "imagestream/layers" を実行する権限がある必要があります。さらに、イメージストリームが存在していない場合、ユーザーはそのプロジェクトで {create} "imagestream" を実行する権限がなければなりません。プロジェクト管理者にはこれらを実行するパーミッションがあります。
注記

system:image-pusher ロールは新規イメージストリームの作成パーミッションを付与せず、既存イメージストリームにイメージをプッシュするパーミッションのみを付与するため、ユーザーに追加パーミッションが付与されない場合、存在していないイメージストリームにイメージをプッシュするためにこのパーミッションを使用することはできません。

イメージを手動でプッシュしてイメージストリームを作成するには、以下を実行します。

  1. まず、内部レジストリーにログインします
  2. 次に、適切な内部レジストリーの場所を使用してイメージにタグを付けます。たとえば、docker.io/centos:centos7 イメージをローカルにプルしている場合は以下を実行します。

    $ docker tag docker.io/centos:centos7 172.30.48.125:5000/test/my-image
  3. 最後に、イメージを内部レジストリーにプッシュします。以下は例になります。

    $ docker push 172.30.48.125:5000/test/my-image
    The push refers to a repository [172.30.48.125:5000/test/my-image] (len: 1)
    c8a648134623: Pushed
    2bf4902415e3: Pushed
    latest: digest: sha256:be8bc4068b2f60cf274fc216e4caba6aa845fff5fa29139e6e7497bb57e48d67 size: 6273
  4. イメージストリームが作成されていることを確認します。

    $ oc get is
    NAME       DOCKER REPO                        TAGS      UPDATED
    my-image   172.30.48.125:5000/test/my-image   latest    3 seconds ago

13.8. イメージストリームの変更時の更新のトリガー

イメージストリームタグが新規イメージを参照するように更新される場合、OpenShift Container Platform は、古いイメージを使用していたリソースに新規イメージをロールアウトするためのアクションを自動的に実行します。イメージストリームタグを参照しているリソースのタイプに応じ、この設定はさまざまな方法で実行できます。

13.8.1. OpenShift リソース

OpenShift DeploymentConfigs および BuildConfigs は ImageStreamTags への変更によって自動的にトリガーされます。トリガーされたアクションは更新された ImageStreamTag で参照されるイメージの新規の値を使用して実行されます。この機能の使用方法についての詳細は、BuildConfig トリガーおよび DeploymentConfig トリガーについての説明を参照してください。

13.8.2. Kubernetes リソース

API 定義の一部としてトリガーを制御するためのフィールドセットを含む DeploymentConfigs および BuildConfigs とは異なり、Kubernetes リソースにはトリガー用のフィールドがありません。その代わりに、OpenShift Container Platform はアノテーションを使用してユーザーがトリガーを要求できるようにします。アノテーションは以下のように定義されます。

Key: image.openshift.io/triggers
Value: array of triggers, where each item has the schema:
[
 {
   "from" :{
     "kind": "ImageStreamTag", // required, the resource to trigger from, must be ImageStreamTag
     "name": "example:latest", // required, the name of an ImageStreamTag
     "namespace": "myapp",     // optional, defaults to the namespace of the object
   },
   // required, JSON path to change
   // Note that this field is limited today, and only accepts a very specific set
   // of inputs (a JSON path expression that precisely matches a container by ID or index).
   // For pods this would be "spec.containers[?(@.name='web')].image".
   "fieldPath": "spec.template.spec.containers[?(@.name='web')].image",
   // optional, set to true to temporarily disable this trigger.
   "paused": "false"
 },
 ...
]

OpenShift Container Platform が Pod テンプレート (CronJobs、Deployments、StatefulSets、DaemonSets、Jobs、ReplicaSets、ReplicationControllers、および Pods のみ) とこのアノテーションの両方が指定されたコアの Kubernetes リソースを検出すると、トリガーが参照する ImageStreamTag に関連付けられているイメージを使用してオブジェクトの更新を試行します。この更新は、指定の fieldPath に対して実行されます。

以下の例では、トリガーは example:latest イメージストリームタグの更新時に実行されます。実行時に、オブジェクトの Pod テンプレートにある web コンテナーへのイメージ参照が、新しいイメージの値に更新されます。Pod テンプレートがデプロイメント定義の一部である場合には、Pod テンプレートへの変更はデプロイメントを自動的にトリガーされて、新規イメージがロールアウトされます。

image.openshift.io/triggers=[{"from":{"kind":"ImageStreamTag","name":"example:latest"},"fieldPath":"spec.template.spec.containers[?(@.name='web')].image"}]

イメージトリガーをデプロイメントに追加する時に、oc set triggers コマンドも使用できます。たとえば、以下のコマンドは example という名前のデプロイメントにイメージ変更トリガーを追加し、example:latest イメージストリームタグが更新されるとデプロイメント内の web コンテナーがイメージの新規の値で更新されます。

$ oc set triggers deploy/example --from-image=example:latest -c web

デプロイメントが一時停止されない限り、この Pod テンプレートが更新されると自動的に、新しいイメージの値でデプロイメントが実行されます。

13.9. イメージストリーム定義の記述

イメージストリーム全体に対するイメージストリームの定義を記述して、複数のイメージストリームを定義できます。これにより、oc コマンドを実行せずに異なるクラスターに定義を配信することができます。

イメージストリームの定義は、インポートするイメージストリームや固有のタグに関する情報を指定します。

イメージストリームオブジェクトの定義

apiVersion: v1
kind: ImageStream
metadata:
  name: ruby
  annotations:
    openshift.io/display-name: Ruby 1
spec:
  tags:
    - name: '2.0' 2
      annotations:
        openshift.io/display-name: Ruby 2.0 3
        description: >- 4
          Build and run Ruby 2.0 applications on CentOS 7. For more information
          about using this builder image, including OpenShift considerations,
          see
          https://github.com/sclorg/s2i-ruby-container/tree/master/2.0/README.md.
        iconClass: icon-ruby 5
        sampleRepo: 'https://github.com/sclorg/ruby-ex.git' 6
        tags: 'builder,ruby' 7
        supports: 'ruby' 8
        version: '2.0' 9
      from:
        kind: DockerImage 10
        name: 'docker.io/openshift/ruby-20-centos7:latest' 11

1
イメージストリーム全体での簡単でユーザーフレンドリーな名前。
2
タグはバージョンとして参照されます。タグはドロップダウンメニューに表示されます。
3
イメージストリーム内のこのタグのユーザーフレンドリーな名前です。これは簡単で、バージョン情報が含まれている必要があります (該当する場合)。
4
タグの説明。これにはユーザーがイメージの提供内容を把握できる程度の詳細情報が含まれます。これには追加の説明へのリンクを含めることができます。説明をいくつかの文に制限します。
5
このタグ用に表示するアイコン。可能な場合は既存のロゴアイコンから選択します。FontAwesome および Patternfly のアイコンも使用できます。または、イメージストリームを使用する OpenShift Contaiter Platform クラスターに追加できる「CSS カスタマイズ」でアイコンを指定します。存在するアイコンクラスを指定する必要があります。これを指定しないと、汎用アイコンへのフォールバックができなくなります。
6
このイメージストリームタグをビルダーイメージタグとして使用してビルドでき、サンプルアプリケーションを実行するために使用されるソースリポジトリーの URL です。
7
イメージストリームタグを関連付けるカテゴリーです。このタグをカタログに表示するには builder タグが必要です。指定のカタログカテゴリーのいずれかとこのタグを関連付けるタグを追加します。コンソールの 定数ファイルにある CATALOG_CATEGORIESid および categoryAliases を参照してください。カテゴリーはクラスター全体に対して「カスタマイズ」することもできます。
8
このイメージがサポートする言語。この値は builder イメージを指定されるソースリポジトリーに一致させるように oc new-app の起動時に使用されます。
9
このタグのバージョン情報。
10
このイメージストリームタグが参照するオブジェクトのタイプ。有効な値は DockerImageImageStreamTag および ImageStreamImage です。
11
このイメージストリームタグがインポートするオブジェクト。

ImageStream に定義可能なフィールドに関する詳しい情報は、「Imagestream API」および「magestreamTag API」を参照してください。

第14章 クォータおよび制限範囲

14.1. 概要

クォータおよび制限範囲を使用して、クラスター管理者はプロジェクトで使用されるオブジェクトの数やコンピュートリソースの量を制限するための制約を設定することができます。これは、管理者がすべてのプロジェクトでリソースの効果的な管理および割り当てを実行し、いずれのプロジェクトでの使用量がクラスターサイズに対して適切な量を超えることのないようにするのに役立ちます。

開発者は Pod およびコンテナーのレベルで「コンピュートリソースの要求および制限」を設定することもできます。

以下のセクションは、クォータおよび制限範囲の設定を確認し、それらの制約対象や、独自の Pod およびコンテナーでコンピュートリソースを要求し、制限する方法について理解するのに役立ちます。

14.2. クォータ

ResourceQuota オブジェクトで定義されるリソースクォータは、プロジェクトごとにリソース消費量の総計を制限する制約を指定します。これは、タイプ別にプロジェクトで作成できるオブジェクトの数量を制限すると共に、そのプロジェクトのリソースが消費できるコンピュートリソースおよびストレージの合計量を制限することができます。

注記

クォータはクラスター管理者によって設定され、所定プロジェクトにスコープが設定されます。

14.2.1. クォータの表示

web コンソールでプロジェクトの Quota ページに移動し、プロジェクトのクォータで定義されるハード制限に関連する使用状況の統計を表示できます。

CLI を使用してクォータの詳細を表示することもできます。

  1. 最初に、プロジェクトで定義されたクォータの一覧を取得します。たとえば、demoproject というプロジェクトの場合、以下を実行します。

    $ oc get quota -n demoproject
    NAME                AGE
    besteffort          11m
    compute-resources   2m
    core-object-counts  29m
  2. 次に、関連するクォータについて記述します。たとえば、core-object-counts クォータの場合、以下を実行します。

    $ oc describe quota core-object-counts -n demoproject
    Name:			core-object-counts
    Namespace:		demoproject
    Resource		Used	Hard
    --------		----	----
    configmaps		3	10
    persistentvolumeclaims	0	4
    replicationcontrollers	3	20
    secrets			9	10
    services		2	10

詳細のクォータ定義は、オブジェクトで oc export を実行して表示できます。以下は、クォータ定義のサンプルを示しています。

core-object-counts.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: core-object-counts
spec:
  hard:
    configmaps: "10" 1
    persistentvolumeclaims: "4" 2
    replicationcontrollers: "20" 3
    secrets: "10" 4
    services: "10" 5

1
プロジェクトに存在できる ConfigMap オブジェクトの合計数です。
2
プロジェクトに存在できる Persistent Volume Claim (永続ボリューム要求、PVC) の合計数です。
3
プロジェクトに存在できるレプリケーションコントローラーの合計数です。
4
プロジェクトに存在できるシークレットの合計数です。
5
プロジェクトに存在できるサービスの合計数です。

openshift-object-counts.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: openshift-object-counts
spec:
  hard:
    openshift.io/imagestreams: "10" 1

1
プロジェクトに存在できるイメージストリームの合計数です。

compute-resources.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-resources
spec:
  hard:
    pods: "4" 1
    requests.cpu: "1" 2
    requests.memory: 1Gi 3
    requests.ephemeral-storage: 2Gi 4
    limits.cpu: "2" 5
    limits.memory: 2Gi 6
    limits.ephemeral-storage: 4Gi 7

1
プロジェクトに存在できる非終了状態の Pod の合計数です。
2
非終了状態のすべての Pod において、CPU 要求の合計は 1 コアを超えることができません。
3
非終了状態のすべての Pod において、メモリー要求の合計は 1 Gi を超えることができません。
4
非終了状態のすべての Pod において、一時ストレージ要求の合計は 2 Gi を超えることができません。
5
非終了状態のすべての Pod において、CPU 制限の合計は 2 コアを超えることができません。
6
非終了状態のすべての Pod において、メモリー制限の合計は 2 Gi を超えることができません。
7
非終了状態のすべての Pod において、一時ストレージ制限の合計は 4 Gi を超えることができません。

besteffort.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: besteffort
spec:
  hard:
    pods: "1" 1
  scopes:
  - BestEffort 2

1
プロジェクトに存在できる QoS (Quality of Service) が BestEffort の非終了状態の Pod の合計数です
2
クォータを、メモリーまたは CPU のいずれかの QoS (Quality of Service) が BestEffort の一致する Pod のみに制限します。

compute-resources-long-running.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-resources-long-running
spec:
  hard:
    pods: "4" 1
    limits.cpu: "4" 2
    limits.memory: "2Gi" 3
    limits.ephemeral-storage: "4Gi" 4
  scopes:
  - NotTerminating 5

1
非終了状態の Pod の合計数です。
2
非終了状態のすべての Pod において、CPU 制限の合計はこの値を超えることができません。
3
非終了状態のすべての Pod において、メモリー制限の合計はこの値を超えることができません。
4
非終了状態のすべての Pod において、一時ストレージ制限の合計はこの値を超えることができません。
5
クォータをspec.activeDeadlineSecondsnil に設定されている一致する Pod のみに制限します。ビルド Pod は、RestartNever ポリシーが適用されない場合に NotTerminating になります。

compute-resources-time-bound.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-resources-time-bound
spec:
  hard:
    pods: "2" 1
    limits.cpu: "1" 2
    limits.memory: "1Gi" 3
    limits.ephemeral-storage: "1Gi" 4
  scopes:
  - Terminating 5

1
非終了状態の Pod の合計数です。
2
非終了状態のすべての Pod において、CPU 制限の合計はこの値を超えることができません。
3
非終了状態のすべての Pod において、メモリー制限の合計はこの値を超えることができません。
4
非終了状態のすべての Pod において、一時ストレージ制限の合計はこの値を超えることができません。
5
クォータをspec.activeDeadlineSeconds >=0 に設定されている一致する Pod のみに制限します。たとえば、このクォータはビルド Pod またはデプロイヤー Pod に影響を与えますが、web サーバーまたはデータベースなどの長時間実行されない Pod には影響を与えません。

storage-consumption.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: storage-consumption
spec:
  hard:
    persistentvolumeclaims: "10" 1
    requests.storage: "50Gi" 2
    gold.storageclass.storage.k8s.io/requests.storage: "10Gi" 3
    silver.storageclass.storage.k8s.io/requests.storage: "20Gi" 4
    silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" 5
    bronze.storageclass.storage.k8s.io/requests.storage: "0" 6
    bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" 7

1
プロジェクト内の Persistent Volume Claim (永続ボリューム要求、PVC) の合計数です。
2
プロジェクトのすべての Persistent Volume Claim (永続ボリューム要求、PVC) において、要求されるストレージの合計はこの値を超えることができません。
3
プロジェクトのすべての Persistent Volume Claim (永続ボリューム要求、PVC) において、gold ストレージクラスで要求されるストレージの合計はこの値を超えることができません。
4
プロジェクトのすべての Persistent Volume Claim (永続ボリューム要求、PVC) において、silver ストレージクラスで要求されるストレージの合計はこの値を超えることができません。
5
プロジェクトのすべての Persistent Volume Claim (永続ボリューム要求、PVC) において、silver ストレージクラスの要求の合計数はこの値を超えることができません。
6
プロジェクトのすべての Persistent Volume Claim (永続ボリューム要求、PVC) において、bronze ストレージクラスで要求されるストレージの合計はこの値を超えることができません。これが 0 に設定される場合、bronze ストレージクラスはストレージを要求できないことを意味します。
7
プロジェクトのすべての Persistent Volume Claim (永続ボリューム要求、PVC) において、bronze ストレージクラスで要求されるストレージの合計はこの値を超えることができません。これが 0 に設定される場合は、bronze ストレージクラスでは要求を作成できないことを意味します。

14.2.2. クォータで管理されるリソース

以下では、クォータで管理できる一連のコンピュートリソースとオブジェクトタイプについて説明します。

注記

status.phase in (Failed, Succeeded) が true の場合、Pod は終了状態にあります。

表14.1 クォータで管理されるコンピュートリソース

リソース名説明

cpu

非終了状態のすべての Pod での CPU 要求の合計はこの値を超えることができません。cpu および requests.cpu は同じ値で、交換可能なものとして使用できます。

memory

非終了状態のすべての Pod でのメモリー要求の合計はこの値を超えることができません memory および requests.memory は同じ値で、交換可能なものとして使用できます。

ephemeral-storage

非終了状態のすべての Pod におけるローカルの一時ストレージ要求の合計はこの値を超えることができません。ephemeral-storage および requests.ephemeral-storage は同じ値で、交互で使用できます。このリソースは、OpenShift Container Platform 3.10 の一時ストレージのテクノロジープレビュー機能が有効化されている場合にのみ利用できます。この機能はデフォルトでは無効になっています。

requests.cpu

非終了状態のすべての Pod での CPU 要求の合計はこの値を超えることができません。cpu および requests.cpu は同じ値で、交換可能なものとして使用できます。

requests.memory

非終了状態のすべての Pod でのメモリー要求の合計はこの値を超えることができません memory および requests.memory は同じ値で、交換可能なものとして使用できます。

requests.ephemeral-storage

非終了状態のすべての Pod における一時ストレージ要求の合計はこの値を超えることができません。ephemeral-storage および requests.ephemeral-storage は同じ値で、交互で使用できます。このリソースは、OpenShift Container Platform 3.10 の一時ストレージのテクノロジープレビュー機能が有効化されている場合にのみ利用できます。この機能はデフォルトでは無効になっています。

limits.cpu

非終了状態のすべての Pod での CPU 制限の合計はこの値を超えることができません。

limits.memory

非終了状態のすべての Pod でのメモリー制限の合計はこの値を超えることができません。

limits.ephemeral-storage

非終了状態のすべての Pod における一時ストレージ要求の合計はこの値を超えることができません。このリソースは、OpenShift Container Platform 3.10 の一時ストレージのテクノロジープレビュー機能が有効化されている場合にのみ利用できます。この機能はデフォルトでは無効になっています。

表14.2 クォータで管理されるストレージリソース

リソース名説明

requests.storage

任意の状態のすべての Persistent Volume Claim (永続ボリューム要求、PVC) でのストレージ要求の合計はこの値を超えることができません。

persistentvolumeclaims

プロジェクトに存在できる Persistent Volume Claim (永続ボリューム要求、PVC) の合計数です。

<storage-class-name>.storageclass.storage.k8s.io/requests.storage

一致するストレージクラスを持つ、任意の状態のすべての Persistent Volume Claim (永続ボリューム要求、PVC) でのストレージ要求の合計はこの値を超えることができません。

<storage-class-name>.storageclass.storage.k8s.io/persistentvolumeclaims

プロジェクトに存在できる、一致するストレージクラスを持つ Persistent Volume Claim (永続ボリューム要求、PVC) の合計数です。

表14.3 クォータで管理されるオブジェクト数

リソース名説明

pods

プロジェクトに存在できる非終了状態の Pod の合計数です。

replicationcontrollers

プロジェクトに存在できるレプリケーションコントローラーの合計数です。

resourcequotas

プロジェクトに存在できるリソースクォータの合計数です。

services

プロジェクトに存在できるサービスの合計数です。

secrets

プロジェクトに存在できるシークレットの合計数です。

configmaps

プロジェクトに存在できる ConfigMap オブジェクトの合計数です。

persistentvolumeclaims

プロジェクトに存在できる Persistent Volume Claim (永続ボリューム要求、PVC) の合計数です。

openshift.io/imagestreams

プロジェクトに存在できるイメージストリームの合計数です。

14.2.3. クォータのスコープ

各クォータには スコープ のセットが関連付けられます。クォータは、列挙されたスコープの交差部分に一致する場合にのみリソースの使用状況を測定します。

スコープをクォータに追加すると、クォータが適用されるリソースのセットを制限できます。許可されるセット以外のリソースを設定すると、検証エラーが発生します。

スコープ説明

Terminating

spec.activeDeadlineSeconds >= 0 の Pod に一致します。

NotTerminating

spec.activeDeadlineSecondsnil の Pod に一致します。

BestEffort

cpu または memory のいずれかの QoS (Quality of Service) が BestEffort の Pod をマッチさせます。コンピュートリソースのコミットについての詳細は、「QoS (Quality of Service) クラス」を参照してください。

NotBestEffort

cpu および memory の QoS (Quality of Service) が Best Effort でない Pod に一致します。

BestEffort スコープは、以下のリソースを制限するようにクォータを制限します。

  • pods

TerminatingNotTerminating、および NotBestEffort スコープは、以下のリソースを追跡するようにクォータを制限します。

  • pods
  • memory
  • requests.memory
  • limits.memory
  • cpu
  • requests.cpu
  • limits.cpu
  • ephemeral-storage
  • requests.ephemeral-storage
  • limits.ephemeral-storage
注記

一時ストレージ要求と制限は、OpenShift Container Platform 3.10 でテクノロジープレビューとして提供されている一時ストレージを有効化した場合にのみ、適用されます。この機能はデフォルトでは無効になっています。

14.2.4. クォータの実施

プロジェクトのリソースクォータが最初に作成されると、プロジェクトは、更新された使用状況の統計が計算されるまでクォータ制約の違反を引き起こす可能性のある新規リソースの作成機能を制限します。

クォータが作成され、使用状況の統計が更新されると、プロジェクトは新規コンテンツの作成を許可します。リソースを作成または変更する場合、クォータの使用量はリソースの作成または変更要求があるとすぐに増分します。

リソースを削除する場合、クォータの使用量は、プロジェクトのクォータ統計の次回の完全な再計算時に減分されます。プロジェクトの変更がクォータ使用制限を超える場合、サーバーはこのアクションを拒否し、クォータ制約を違反していること、およびシステムで現在確認される使用量の統計値を示す適切なエラーメッセージが返されます。

14.2.5. 要求 vs 制限

「コンピュートリソース」の割り当て時に、各コンテナーは CPU、メモリー、一時ストレージそれぞれに要求値と制限値を指定できます。クォータはこれらの値をどれでも制限できます。

クォータに requests.cpu または requests.memory の値が指定されている場合、すべての着信コンテナーがそれらのリソースを明示的に要求することが求められます。クォータに limits.cpu または limits.memory の値が指定されている場合、すべての着信コンテナーがそれらのリソースの明示的な制限を指定することが求められます。

Pod およびコンテナーに要求および制限を設定する方法についての詳細は、「コンピュートリソース」を参照してください。

14.3. 制限範囲

LimitRange オブジェクトで定義される制限範囲は、Pod、コンテナー、イメージ、イメージストリーム、および Persistent Volume Claim (永続ボリューム要求、PVC) のレベルでプロジェクトコンピュートリソース制約を列挙し、Pod、コンテナー、イメージ、イメージストリームまたは Persistent Volume Claim (永続ボリューム要求、PVC) で消費できるリソースの量を指定します。

すべてのリソース作成および変更要求は、プロジェクトの各 LimitRange オブジェクトに対して評価されます。リソースが列挙される制約に違反する場合、そのリソースは拒否されます。リソースが明示的な値を指定しない場合で、制約がデフォルト値をサポートする場合は、デフォルト値がリソースに適用されます。

注記

OpenShift Container Platform 3.10 では、一時ストレージのテクノロジープレビューを使用して一時ストレージの制限と要求を指定できます。この機能は、デフォルトでは無効になっています。この機能を有効にするには、「一時ストレージの設定」を参照してください。

注記

制限範囲はクラスター管理者によって設定され、所定プロジェクトにスコープが設定されます。

14.3.1. 制限範囲の表示

web コンソールでプロジェクトの Quota ページに移動し、プロジェクトで定義される制限範囲を表示できます。

CLI を使用して制限範囲の詳細を表示することもできます。

  1. まず、プロジェクトで定義される制限範囲の一覧を取得します。たとえば、demoproject というプロジェクトの場合は以下のようになります。

    $ oc get limits -n demoproject
    NAME              AGE
    resource-limits   6d
  2. 次に、関連のある制限範囲の説明を表示します。たとえば、resource-limits 制限範囲の場合は以下のようになります。

    $ oc describe limits resource-limits -n demoproject
    Name:                           resource-limits
    Namespace:                      demoproject
    Type                            Resource                Min     Max     Default Request Default Limit   Max Limit/Request Ratio
    ----                            --------                ---     ---     --------------- -------------   -----------------------
    Pod                             cpu                     200m    2       -               -               -
    Pod                             memory                  6Mi     1Gi     -               -               -
    Container                       cpu                     100m    2       200m            300m            10
    Container                       memory                  4Mi     1Gi     100Mi           200Mi           -
    openshift.io/Image              storage                 -       1Gi     -               -               -
    openshift.io/ImageStream        openshift.io/image      -       12      -               -               -
    openshift.io/ImageStream        openshift.io/image-tags -       10      -               -               -

詳細の制限範囲の定義は、オブジェクトで oc export を実行して表示できます。以下は、制限範囲の定義例を示しています。

コア Limit Range オブジェクトの定義

apiVersion: "v1"
kind: "LimitRange"
metadata:
  name: "core-resource-limits" 1
spec:
  limits:
    - type: "Pod"
      max:
        cpu: "2" 2
        memory: "1Gi" 3
      min:
        cpu: "200m" 4
        memory: "6Mi" 5
    - type: "Container"
      max:
        cpu: "2" 6
        memory: "1Gi" 7
      min:
        cpu: "100m" 8
        memory: "4Mi" 9
      default:
        cpu: "300m" 10
        memory: "200Mi" 11
      defaultRequest:
        cpu: "200m" 12
        memory: "100Mi" 13
      maxLimitRequestRatio:
        cpu: "10" 14

1
制限範囲オブジェクトの名前です。
2
すべてのコンテナーにおいて Pod がノードで要求できる CPU の最大量です。
3
すべてのコンテナーにおいて Pod がノードで要求できるメモリーの最大量です。
4
すべてのコンテナーにおいて Pod がノードで要求できる CPU の最小量です。
5
すべてのコンテナーにおいて Pod がノードで要求できるメモリーの最小量です。
6
Pod の単一コンテナーが要求できる CPU の最大量です。
7
Pod の単一コンテナーが要求できるメモリーの最大量です。
8
Pod の単一コンテナーが要求できる CPU の最小量です。
9
Pod の単一コンテナーが要求できるメモリーの最小量です。
10
指定がない場合、コンテナーによる使用を制限する CPU のデフォルト量です。
11
コンテナーによる使用を制限するメモリーのデフォルト量です (指定がない場合)。
12
コンテナーが使用を要求する CPU のデフォルト量です (指定がない場合)。
13
コンテナーが使用を要求するメモリーのデフォルト量です (指定がない場合)。
14
制限の要求に対する比率でコンテナーで実行できる CPU バーストの最大量です。

CPU およびメモリーの測定方法についての詳細は、「コンピュートリソース」を参照してください。

14.3.2. コンテナーの制限

サポートされるリソース:

  • CPU
  • メモリー

サポートされる制約:

コンテナーごとに設定されます。指定される場合、以下を満たしている必要があります。

表14.4 コンテナー