開発者ガイド
OpenShift Container Platform 3.10 開発者リファレンス
概要
- Web コンソールを使用したプロジェクトのモニターおよび参照
- CLI の設定および利用
- テンプレートを使用した設定の生成
- ビルドおよび Webhook の管理
- デプロイメントの定義およびトリガー
- 外部サービス (データベース、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 の使用
OpenShift Container Platform を直接使用してアプリケーションの開発をゼロから行うことができます。この種類の開発プロセスを計画する場合には、以下の手順を考慮してください。
初期計画
- アプリケーションの機能は?
- どのプログラミング言語を使用して開発するか?
OpenShift Container Platform へのアクセス
- この時点で、ご自身または組織内の管理者が OpenShift Container Platform をインストールする必要があります。
開発
- 各自が選択するエディターまたは IDE を使用して、アプリケーションの基本的なスケルトンを作成します。このスケルトンは、OpenShift Container Platform が「アプリケーションの種類」について認識できるように適切に作成されている必要があります。
- コードを Git リポジトリーにプッシュします。
生成
-
oc new-app
コマンドを使用して「基本的なアプリケーションを作成」します。OpenShift Container Platform はビルドおよびデプロイメント設定を生成します。
管理
- アプリケーションコードの開発を開始します。
- アプリケーションが正常にビルドされることを確認します。
- 引き続きコードをローカルで開発し、コードを改良します。
- コードを Git リポジトリーにプッシュします。
- 追加の設定が必要かどうかを確認します。追加のオプションについて『開発者ガイド』で確認してください。
検証
-
アプリケーションは数多くの方法で検証できます。変更をアプリケーションの Git リポジトリーにプッシュし、OpenShift Container Platform を使用してアプリケーションの再ビルドおよび再デプロイを行うことができます。または、
rsync
でホットデプロイを実行して、コードの変更を実行中の Pod で同期できます。
2.1.3. アプリケーションの OpenShift Container Platform へのデプロイ
アプリケーション開発ストラテジーの別の可能性として、ローカルで開発してから OpenShift Container Platform を使用して完全に開発されたアプリケーションをデプロイする方法があります。アプリケーションコードを先に準備してからビルドし、完了後に OpenShift Container Platform インストールにデプロイする場合は、以下の手順を使用します。
初期計画
- アプリケーションの機能は?
- どのプログラミング言語を使用して開発するか?
開発
- 任意のエディターまたは IDE を使用してアプリケーションコードを開発します。
- アプリケーションコードをローカルでビルドしてテストします。
- コードを Git リポジトリーにプッシュします。
OpenShift Container Platform へのアクセス
- この時点で、ご自身または組織内の管理者が OpenShift Container Platform をインストールする必要があります。
生成
-
oc new-app
コマンドを使用して「基本的なアプリケーションを作成」します。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 は Docker
、Pipeline
または Source
「ビルドストラテジー」のいずれを使用すべきかを自動的に「検出」します。また、Source
ビルドの場合は、「適切な言語のビルダーイメージを検出します」。
ビルドストラテジーの検出
新規アプリケーションの作成時に Jenkinsfile がソースリポジトリーの root または指定のコンテキストディレクトリーに存在する場合に、OpenShift Container Platform は「Pipeline
ビルドストラテジー」を生成します。または、Dockerfile がある場合に、OpenShift Container Platform は 「Docker
ビルドストラテジー」を生成します。Dockerfile がない場合には、「Source
ビルドストラテジー」を生成します。
ビルドストラテジーを上書きするには、--strategy
フラグを docker
、pipeline
または source
のいずれかに設定してください。
$ oc new-app /home/user/code/myapp --strategy=docker
oc
コマンドを使用するには、ビルドのソースを含むファイルがリモートの git リポジトリーで利用できる必要があります。ソースの全ビルドには、git remote -v
を使用する必要があります。
言語検出
Source
ビルドストラテジーを使用する場合に、new-app
はリポジトリーの root または指定したコンテキストディレクトリーに特定のファイルが存在するかどうかで、使用する言語ビルダーを判別しようとします。
言語 | ファイル |
---|---|
|
project.json、*.csproj |
|
pom.xml |
|
app.json、package.json |
|
cpanfile、index.pl |
|
composer.json、index.php |
|
requirements.txt、setup.py |
|
Gemfile, Rakefile、config.ru |
|
build.sbt |
|
Godeps、main.go |
言語の検出後、new-app
は、検出言語に一致する supports
アノテーションが指定された 「イメージストリーム」タグか、または検出言語の名前に一致するイメージストリームがないかどうか、OpenShift Container Platform サーバーを検索します。一致するものが見つからない場合には、new-app
は Docker 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.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 コンソールを使用したアプリケーションの作成
必要なプロジェクトで Add to Project をクリックします。
プロジェクト内にあるイメージの一覧またはサービスカタログからビルダーイメージを選択します。
注記以下に示すように、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 コンソールに表示されます。
新規アプリケーション画面で設定を変更し、オブジェクトをアプリケーションをサポートするように設定します。
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 方向マージを実行します。
- コマンドへの入力
- オブジェクトの現行バージョン
- 現行オブジェクトにアノテーションとして保存された最新のユーザー指定オブジェクト定義
その後に既存のオブジェクトは結果と共に更新されます。
オブジェクトがソース環境とターゲット環境間で同一であることが予期されていない場合など、API オブジェクトの追加のカスタマイズが必要な場合に、oc set
などの oc
コマンドは、アップストリーム環境から最新のオブジェクト定義を適用した後に、オブジェクトを変更するために使用できます。
使用方法についての詳細は、「シナリオおよび実例」を参照してください。
2.3.4.2. イメージおよびイメージストリームの管理
OpenShift Container Platform のイメージも一連の API オブジェクトで管理されます。ただし、イメージの管理はアプリケーションのプロモートにおける非常に中心的な部分であるため、イメージに最も直接的に関係するツールおよび API オブジェクトについては別途扱います。イメージのプロモートの管理には、手動および自動の方法を使用できます (パイプラインによるイメージの伝搬) 。
2.3.4.2.1. イメージの移動
イメージの管理に関する注意事項すべての詳細については、「イメージの管理」のトピックを参照してください。
2.3.4.2.1.2. ステージング環境が異なるレジストリーを使用する場合
ステージング環境が異なる OpenShift Container Platform レジストリーを活用している場合、より高度な使用方法が見られます。内部レジストリーへのアクセス で、手順を詳細に説明していますが、まとめると以下のようになります。
-
OpenShift Container Platform のアクセストークンの取得と関連して
docker
コマンドを使用し、docker login
コマンドに指定します。 -
OpenShift Container Platform レジストリーにログインした後、
docker pull
、docker tag
およびdocker push
を使用してイメージを移行します。 -
イメージがパイプラインの次の環境のレジストリーで利用可能になってから、必要に応じて
oc tag
を使用してイメージストリームを設定します。
2.3.4.2.2. デプロイ
変更対象が基礎となるアプリケーションイメージであるか、アプリケーションを設定する API オブジェクトであるかを問わず、プロモートされた変更を認識するにはデプロイメントが通常必要になります。アプリケーションのイメージが変更される場合 (アップストリームからのイメージのプロモートの一環としての oc tag
操作または docker push
の実行による場合など)、DeploymentConfig
の ImageChangeTriggers
が新規デプロイメントをトリガーできます。同様に 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. プロモーションのセットアップ
アプリケーションの初期リビジョンの開発が完了すると、次の手順として、プロモーションパイプラインのステージング環境に移行できるようにアプリケーションのコンテンツをパッケージ化します。
最初に、表示されるすべての API オブジェクトを移行可能なものとしてグループ化し、共通の
label
を適用します。labels: promotion-group: <application_name>
前述のように
oc label
コマンドは、さまざまな API オブジェクトのラベルの管理を容易にします。ヒントOpenShift Container Platform テンプレートに API オブジェクトを最初に定義する場合、プロモート用にエクスポートする際にクエリーに使用する共通のラベルがすべての関連するオブジェクトにあることを簡単に確認できます。
このラベルは後続のクエリーで使用できます。たとえば、アプリケーションの 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
タイプを含めるかどうかは、パイプライン内の異なる環境全体でイメージ、イメージストリーム、およびレジストリーの管理方法をどのように選択するかによって変わってきます。この点に関する注意事項を以下で説明しています。イメージの管理 のトピックも参照してください。プロモーションパイプラインの各種のステージング環境で使用されるそれぞれのレジストリーに対して機能するトークンを取得する必要があります。各環境について以下を実行します。
環境にログインします。
$ oc login <each_environment_with_a_unique_registry>
以下を実行してアクセストークンを取得します。
$ oc whoami -t
- 次回に使用できるようにトークン値をコピーアンドペーストします。
2.3.5.2. 繰り返し可能なプロモーションプロセス
パイプラインの異なるステージング環境での初回のセットアップ後に、プロモーションパイプラインを使用したアプリケーションの反復を検証する繰り返し可能な手順のセットを開始できます。これらの基本的な手順は、ソース環境のイメージまたは API オブジェクトが変更されるたびに実行されます。
更新後のイメージの移動→更新後の API オブジェクトの移動→環境固有のカスタマイズの適用
通常、最初の手順ではアプリケーションに関連するイメージの更新をパイプラインの次のステージにプロモートします。前述のように、ステージング環境間で OpenShift Container Platform レジストリーが共有されるかどうかが、イメージをプロモートする上での主要な差別化要因となります。
レジストリーが共有されている場合、単に
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>
レジストリーが共有されていない場合、ソースおよび宛先の両方のレジストリーにログインする際、各プロモーションパイプラインレジストリーに対してアクセストークンを使用でき、アプリケーションイメージのプル、タグ付け、およびプッシュを随時実行できます。
ソース環境レジストリーにログインします。
$ docker login -u <username> -e <any_email_address> -p <token_value> <src_env_registry_ip>:<port>
アプリケーションのイメージをプルします。
$ docker pull <src_env_registry_ip>:<port>/<namespace>/<image name>:<tag>
アプリケーションのイメージを宛先レジストリーの場所にタグ付けし、宛先ステージング環境と一致するように namespace、名前、タグを随時更新します。
$ docker tag <src_env_registry_ip>:<port>/<namespace>/<image name>:<tag> <dest_env_registry_ip>:<port>/<namespace>/<image name>:<tag>
宛先ステージング環境レジストリーにログインします。
$ docker login -u <username> -e <any_email_address> -p <token_value> <dest_env_registry_ip>:<port>
イメージを宛先にプッシュします。
$ docker push <dest_env_registry_ip>:<port>/<namespace>/<image name>:<tag>
ヒント外部レジストリーからイメージの新バージョンを自動的にインポートするために、
oc tag
コマンドで--scheduled
オプションを使用できます。これを使用する場合、ImageStreamTag
が参照するイメージは、イメージをホストするレジストリーから定期的にプルされます。
次に、アプリケーションの変化によってアプリケーションを構成する API オブジェクトの根本的な変更や API オブジェクトセットへの追加と削除が必要となるケースがあります。アプリケーションの API オブジェクトにこのような変化が生じると、OpenShift Container Platform CLI はあるステージング環境から次の環境へと変更を移行するための広範囲のオプションを提供します。
プロモーションパイプラインの初回セットアップ時と同じ方法で開始します。
$ 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>
単に新しい環境でリソースを作成するのではなく、それらを更新します。これを実行するための方法がいくつかあります。
より保守的なアプローチとして、
oc apply
を使用し、ターゲット環境内の各 API オブジェクトに新しい変更をマージできます。これを実行することにより、--dry-run=true
オプションを実行し、オブジェクトを実際に変更する前に結果として得られるオブジェクトを確認することができます。$ oc apply -f export.yaml --dry-run=true
問題がなければ、
apply
コマンドを実際に実行します。$ oc apply -f export.yaml
apply
コマンドはより複雑なシナリオで役立つ追加の引数をオプションで取ります。詳細についてはoc apply --help
を参照してください。または、よりシンプルで積極的なアプローチとして、
oc replace
を使用できます。この更新および置換についてはドライランは利用できません。最も基本的な形式として、以下を実行できます。$ oc replace -f export.yaml
apply
と同様に、replace
はより高度な動作については他の引数をオプションで取ります。詳細は、oc replace --help
を参照してください。
-
直前の手順では、導入された新しい API オブジェクトは自動的に処理されますが、API オブジェクトがソースの環境から削除された場合には、
oc delete
を使用してこれらをターゲットの環境から手動で削除する必要があります。 ステージング環境ごとに必要な値が異なる可能性があるため、API オブジェクトで引用された環境変数を調整する必要がある場合があります。この場合は
oc set env
を使用します。$ oc set env <api_object_type>/<api_object_ID> <env_var_name>=<env_var_value>
-
最後に、
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 ソースリポジトリー で定義されます。このアプリケーションは
ImageStreams
、ImageChangeTriggers
、ImageStreamTags
、BuildConfigs
およびプロモーションパイプラインの各種ステージに対応した別個のDeploymentConfigs
とServices
を利用します。
以下では、OpenShift のサンプルジョブを詳細に検証していきます。
-
最初のステップ は、
oc scale dc frontend --replicas=0
の呼び出しと同じです。この手順は、実行されている可能性のあるアプリケーションイメージの以前のバージョンを終了させるために実行されます。 -
2 番目のステップ は
oc start-build frontend
の呼び出しと同じです。 -
3 番目のステップ は
oc rollout latest dc/frontend
の呼び出しと同じです。 - 4 番目のステップ は、このサンプルの「テスト」を行います。このステップでは、アプリケーションに関連するサービスがネットワークからアクセス可能であることを確認します。背後で、OpenShift Container Platform サービスに関連する IP アドレスやポートにソケット接続を試みます。当然のこととして別のテストを追加することも可能です (OpenShift Pipepline plug-in ステップを使用しない場合は、Jenkins Shell ステップを使用して、OS レベルのコマンドとスクリプトを使用してアプリケーションをテストします)。
-
5 番目のステップ は、アプリケーションがテストに合格したことを前提としているため、イメージは「Ready (使用準備完了)」としてマークされます。このステップでは、新規の prod タグが 最新の イメージをベースにしたアプリケーションイメージ用に作成されます。フロントエンドの
DeploymentConfig
で そのタグに対して、ImageChangeTrigger
が定義されている場合には、対応する「実稼働」デプロイメントが起動されます。 - 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]
以下の表では、一般的なオプションを紹介しています。
オプション | 構文 | 説明 |
---|---|---|
|
$ oc login -s=<server> |
OpenShift Container Platform サーバーのホスト名を指定します。サーバーがこのフラグで指定されている場合には、このコマンドではホスト名は対話的に確認されません。また、このフラグは、CLI 設定ファイルがある場合や、ログインして別のサーバーに切り替える場合に使用できます。 |
|
$ oc login -u=<username> -p=<password> |
OpenShift Container Platform サーバーにログインするための認証情報を指定できます。これらのフラグを指定してユーザー名またはパスワードを入力した場合は、このコマンドでは、ユーザー名やパスワードが対話的に確認されません。設定ファイルでセッショントークンを確立し、ログインしてから別のユーザー名に切り替える場合に、これらのフラグを使用することができます。 |
|
$ oc login -u=<username> -p=<password> -n=<project> |
|
|
$ oc login --certificate-authority=<path/to/file.crt> |
HTTPS を使用する OpenShift Container Platform サーバーで正常かつセキュアに認証します。認証局ファイルへのパスは指定する必要があります。 |
|
$ oc login --insecure-skip-tls-verify |
HTTPS サーバーとの対話を可能にして、サーバーの証明書チェックを省略します。ただし、これはセキュリティーが確保されない点に注意してください。有効な証明書を提示しない HTTPS サーバーに |
CLI 設定ファイルを使用すると、簡単に「複数の CLI プロファイル」を管理することができます。
管理者認証情報があるのに、「デフォルトシステムユーザー」の system:admin としてログインされていない場合、認証情報が 「CLI 設定ファイル」にある限り、いつでもこのユーザーとしてログインし直すことができます。以下のコマンドはログインを実行し、「デフォルト」プロジェクトに切り替えます。
$ oc login -u system:admin -n default
第4章 承認
4.1. 概要
以下のトピックでは、アプリケーション開発者向けの「認証タスク」と、クラスター管理者が指定する認証機能について紹介します。
4.2. ユーザーの Pod 作成権限の有無の確認
scc-review
と scc-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 ボタンはデフォルトで表示されていますが、オプションで非表示にしたり、カスタマイズしたりすることができます。
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 リンクを使用します。
「CLI」を使用して 「新規プロジェクト」を作成する場合は、ブラウザーでページを更新して、新規プロジェクトを表示できます。
プロジェクトを選択すると、そのプロジェクトの「プロジェクトの概要」が表示されます。
特定プロジェクトの kebab (ケバブ) メニューをクリックすると、以下のオプションが表示されます。
5.4. プロジェクトステータスの確認
oc status
コマンドは、コンポーネントと関係を含む現在のコンポーネントの概要を示します。このコマンドには引数は指定できません。
$ oc status
5.5. ラベル別の絞り込み
リソースの「ラベル」を使用して、「Web コンソール」のプロジェクトページのコンテンツを絞り込むことができます。提案されたラベル名や値から選択することも、独自の内容を入力することも可能です。また、複数のフィルターを指定することもできます。複数のフィルターが適用される場合には、リソースはすべてのフィルターと一致しないと表示されなくなります。
ラベル別で絞り込むには以下を実行します。
ラベルタイプを選択します。
以下のいずれかを選択します。
exists
ラベル名が存在することを確認するだけで、値は無視します。
does not exist
ラベル名が存在しないことを確認してこの値を無視します。
in
ラベル名が存在し、選択した値の 1 つと同じであることを確認します。
not in
ラベル名が存在しない、または選択した値に該当しないことを確認します。
in または not in を選択した場合には、値セットを選択してから、Filter を選択します。
フィルターの追加後に、Clear all 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 イメージに含める必要があるため、それらを記録する必要もあります。
一般的な移行手順は以下のとおりです。
v2 アプリケーションをバックアップします。
- Web カートリッジ: ソースコードは、GitHub のリポジトリーにプッシュするなど、Git リポジトリーにバックアップすることができます。
-
データベースカートリッジ: データベースは、dump コマンドを使用してバックアップすることができます (
mongodump
、mysqldump
、pg_dump
)。 Web およびデータベースカートリッジ:
rhc
クライアントツールには、複数のカートリッジをバックアップするスナップショットの機能があります。$ rhc snapshot save <app_name>
スナップショットは展開可能な tar ファイルであり、このファイルには、アプリケーションのソースコードとデータベースのダンプが含まれます。
- アプリケーションにデータベースカートリッジが含まれる場合には、v3 データベースアプリケーションを作成し、データベースダンプを新しい v3 データベースアプリケーションの Pod に同期してから、データベースの復元コマンドを使用して v3 データベースアプリケーションに v2 データベースを復元します。
- Web フレームワークアプリケーションの場合には、v3 と互換性を持たせるようにアプリケーションのソースコードを編集してから、Git リポジトリーの適切なファイルに、必要な依存関係やパッケージを追加します。v2 環境変数を適切な v3 環境変数に変換します。
- ソース (Git リポジトリー) または Git URL のクイックスタートから v3 アプリケーションを作成します。また、データベースのサービスパラメーターを新規アプリケーションに追加して、データベースアプリケーションと Web アプリケーションをリンクします。
- 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. サポートされているデータベース
v2 | v3 |
---|---|
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
すべてのデータベースをダンプファイルにエクスポートして、これをローカルマシン (現在のディレクトリー) にコピーします
$ 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
dbdump をローカルマシンにダウンロードします。
$ mkdir mysqldumpdir $ rhc scp -a <v2_application_name> download mysqldumpdir app-root/data/all.sql
テンプレートから 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>
Pod の使用準備ができているかどうかを確認します。
$ oc get pods
Pod の実行中に、データベースのアーカイブファイルを v3 MySQL Pod にコピーします。
$ oc rsync /local/mysqldumpdir <mysql_pod_name>:/var/lib/mysql/data
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
に割り当ててから、権限をフラッシュします。Pod からダンプディレクトリーを削除します。
$ cd ../; rm -rf /var/lib/mysql/data/mysqldumpdir
サポート対象の MySQL 環境変数
v2 | v3 |
---|---|
|
|
|
|
|
|
|
|
| |
| |
| |
| |
| |
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
| |
| |
| |
| |
|
6.2.4. PostgreSQL
ギアから 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
ローカルマシンに、バックアップファイルを展開します。
$ rhc scp -a <v2_application_name> download <local_dest> app-root/data/tmp/<db-name>.gz $ gzip -d <database-name>.gz
注記手順 4 とは別のフォルダーにバックアップファイルを保存します。
新規サービスを作成するための v2 アプリケーションのデータベース名、ユーザー名、パスワードを使用して PostgreSQL サービスを作成します。
$ oc new-app postgresql-persistent -p POSTGRESQL_DATABASE=dbname -p POSTGRESQL_PASSWORD=password -p POSTGRESQL_USER=username
Pod の使用準備ができているかどうかを確認します。
$ oc get pods
Pod を実行中に、バックアップディレクトリーを Pod に同期します。
$ oc rsync /local/path/to/dir <postgresql_pod_name>:/var/lib/pgsql/data
Pod にリモートからアクセスします。
$ oc rsh <pod_name>
データベースを復元します。
psql dbname < /var/lib/pgsql/data/<database_backup_file>
必要のなくなったバックアップファイルをすべて削除します。
$ rm /var/lib/pgsql/data/<database-backup-file>
サポート対象の PostgreSQL 環境変数
v2 | v3 |
---|---|
|
|
|
|
|
|
|
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
6.2.5. MongoDB
- OpenShift v3 の場合: MongoDB シェルバージョン 3.2.6
- OpenShift v2 の場合: MongoDB シェルバージョン 2.4.9
ssh
コマンドを使用して、v2 アプリケーションにリモートからアクセスします。$ rhc ssh <v2_application_name>
-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
dbdump を mongodump ディレクトリーのローカルマシンにダウンロードします。
$ mkdir mongodump $ rhc scp -a <v2 appname> download mongodump \ app-root/repo/mydbdump/<dbname>/dbname.tar.gz
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:latest
はmongodb: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
mongodb Pod の実行中に、データベースのアーカイブファイルを v3 MongoDB Pod にコピーします。
$ oc rsync local/path/to/mongodump <mongodb_pod_name>:/var/lib/mongodb/data $ oc rsh <mongodb_pod>
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
データベースが復元されたかどうかを確認します。
$ mongo admin -u $MONGODB_USER -p $MONGODB_ADMIN_PASSWORD $ use dbname $ show collections $ exit
Pod から mongodump ディレクトリーを削除します。
$ rm -rf /var/lib/mongodb/data/mongodump
サポート対象の MongoDB 環境変数
v2 | v3 |
---|---|
|
|
|
|
|
|
|
|
| |
| |
| |
| |
| |
| |
| |
| |
|
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
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>.git
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
setup.py、wsgi.py、requirements.txt および etc などの重要なファイルがすべて新規リポジトリーにプッシュされていることを確認します。
- アプリケーションに必要なパッケージがすべて requirements.txt に含まれていることを確認します。
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 バージョン
v2 | v3 |
---|---|
Python: 2.6、2.7、3.3 | |
Django |
Django-psql-example (quickstart) |
6.3.3. Ruby
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>.git
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
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 以降を使用してください。
oc
コマンドを使用して、ビルダーイメージとソースコードから新規の Ruby アプリケーションを起動します。$ oc new-app --strategy=source ruby:2.0~https://github.com/<github-id>/<repo-name>.git
サポート対象の Ruby バージョン
v2 | v3 |
---|---|
Ruby: 1.8、1.9、2.0 | |
Ruby on Rails: 3、4 |
Rails-postgresql-example (quickstart) |
Sinatra |
6.3.4. PHP
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
oc
コマンドを使用して、ビルダーイメージとソースコードから新規の PHP アプリケーションを起動します。$ oc new-app https://github.com/<github-id>/<repo-name>.git --name=<app-name> -e <ENV_VAR_NAME>=<env_var_value>
サポート対象の PHP バージョン
v2 | v3 |
---|---|
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
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル v2 Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
ローカルの Git リポジトリーを編集して、変更をアップストリームにプッシュして、v3 との互換性を確保します。
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
.openshift ディレクトリーを削除します。
注記v3 では、action_hooks および cron タスクは同じようにサポートされません。詳細情報は、「アクションフック」を参照してください。
-
oc
コマンドを使用して、ビルダーイメージとソースコードから新規の Perl アプリケーションを起動します。
$ oc new-app https://github.com/<github-id>/<repo-name>.git
サポート対象の Perl バージョン
v2 | v3 |
---|---|
Perl: 5.10 | |
Dancer-mysql-example (quickstart) |
6.3.6. Node.js
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
ローカルの Git リポジトリーを編集して、変更をアップストリームにプッシュして、v3 との互換性を確保します。
.openshift ディレクトリーを削除します。
注記v3 では、action_hooks および cron タスクは同じようにサポートされません。詳細情報は、「アクションフック」を参照してください。
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 から取得されます。
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 バージョン
v2 | v3 |
---|---|
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
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
- リポジトリーに事前にビルドされた .war ファイルが含まれている場合には、それらをリポジトリーの root ディレクトリー内の deployments ディレクトリーに置く必要があります。
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)
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
- リポジトリーに事前にビルドされた .war ファイルが含まれている場合には、それらをリポジトリーの root ディレクトリー内の deployments ディレクトリーに置く必要があります。
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)
新しい GitHub リポジトリーを設定して、そのリポジトリーをリモートのブランチとして現在のローカル Git リポジトリーに追加します。
$ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
ローカルの v2 ソースコードを新規リポジトリーにプッシュします。
$ git push -u <remote-name> master
ローカルの Git リポジトリーを編集して、変更をアップストリームにプッシュして v3 との互換性を確保します。
.openshift ディレクトリーを削除します。
注記v3 では、action_hooks および cron タスクは同じようにサポートされません。詳細情報は、「アクションフック」を参照してください。
- deployments ディレクトリーをソースリポジトリーの root に追加します。.war ファイルをこの「deployments」ディレクトリーに移動します。
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
はアプリケーション名を指定するためのオプションの引数です。また、-e
はOPENSHIFT_PYTHON_DIR
などのビルドやデプロイメントプロセスに必要な環境変数を追加するためのオプションの引数です。
6.3.12. サポート対象の JBoss バージョン
v2 | v3 |
---|---|
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
で利用可能なテンプレートをすべて表示することができます。
CakePHP MySQL https://github.com/sclorg/cakephp-ex
- テンプレート: cakephp-mysql-example
Node.js MongoDB https://github.com/sclorg/nodejs-ex
- テンプレート: nodejs-mongodb-example
Django PosgreSQL https://github.com/sclorg/django-ex
- テンプレート: django-psql-example
Dancer MySQL https://github.com/sclorg/dancer-ex
- テンプレート: dancer-mysql-example
Rails PostgreSQL https://github.com/sclorg/rails-ex
- テンプレート: rails-postgresql-example
6.4.2. ワークフロー
上記のテンプレート URL のいずれかに対して git clone
をローカルで実行します。アプリケーションのソースコードを追加し、コミットし、GitHub リポジトリーにプッシュしてから、上記のテンプレートのいずれかで v3 クイックスタート アプリケーションを起動します。
- アプリケーション用の GitHub リポジトリーを作成します。
クイックスタートテンプレートのクローンを作成して、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
ソースコードを GitHub にコミットし、プッシュします。
$ cd <your local repository> $ git commit -am “added code for my app” $ git push origin master
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_PASSWORD
はMONGODB_ADMIN_PASSWORD
になります (MongoDB のみに該当します)。SOURCE_REPOSITORY_URL
が指定されていない場合、テンプレートはソースリポジトリーとして上記のテンプレート URL (https://github.com/openshift/<quickstart>-ex) を使用して、hello-welcome アプリケーションが起動します。
-
データベースを移行する場合は、データベースをダンプファイルにエクスポートして、新しい 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
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>.
- GitHub の Web コンソールから、この URL を GitHub にカットアンドペーストします。
- GitHub リポジトリーで、Settings → Webhooks & Services から Add Webhook を選択します。
- Payload URL フィールドに、(上記と同様の) URL の出力を貼り付けます。
-
Content Type を
application/json
に設定します。 - 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. コンテナーイメージの作成
- アプリケーションに必要なビルダーイメージを特定します。Red Hat は、「Python、Ruby、Perl、PHP および Node.js」など各種の言語のビルダーイメージを複数提供しています。他のイメージは コミュニティースペース から取得できます。
S2I は、Git リポジトリーまたはローカルのファイルシステムのソースコードからイメージをビルドできます。ビルダーイメージおよびソースコードから新しいコンテナーイメージをビルドするには、以下を実行します。
$ s2i build <source-location> <builder-image-name> <output-image-name>
注記<source-location>
には Git リポジトリーの URL、 またはローカルファイルシステムのソースコードのディレクトリーのいずれかを指定できます。Docker デーモンでビルドしたイメージをテストします。
$ docker run -d --name <new-name> -p <port-number>:<port-number> <output-image-name> $ curl localhost:<port-number>
- 新しいイメージを「OpenShift レジストリー」にプッシュします。
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. サポート対象のフレームワーク
v2 | v3 |
---|---|
Jenkins サーバー |
jenkins-persistent |
Drupal 7 | |
Ghost 0.7.5 | |
WordPress 4 | |
Ceylon | |
Go | |
MEAN |
6.8.5. サポート対象のマーカー
v2 | v3 |
---|---|
pip_install |
リポジトリーに requirements.txt が含まれる場合には、デフォルトで pip が呼び出されます。含まれていない場合に pip は使用されません。 |
v2 | v3 |
---|---|
disable_asset_compilation |
これは、buildconfig ストラテジー定義で |
v2 | v3 |
---|---|
enable_cpan_tests |
これは、「ビルド設定」で |
v2 | v3 |
---|---|
use_composer |
ソースリポジトリーの root ディレクトリーに composer.json が含まれる場合に、コンポーザーが常に使用されます。 |
v2 | v3 |
---|---|
NODEJS_VERSION |
該当なし |
use_npm |
アプリケーションの起動には、 |
v2 | v3 |
---|---|
enable_debugging |
このオプションは、デプロイメント設定で設定される |
skip_maven_build |
pom.xml がある場合には、maven が実行されます。 |
java7 |
該当なし |
java8 |
JavaEE は JDK8 を使用します。 |
v2 | v3 |
---|---|
enable_debugging |
該当なし |
v2 | v3 |
---|---|
force_clean_build |
v3 には同様の概念が使われています。buildconfig の noCache フィールドにより、コンテナービルドによる各層の再実行が強制的に実行されます。S2I ビルドでは、clean build を示す incremental フラグはデフォルトで false になっています。 |
hot_deploy | |
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 フレームワーククイックスタートのテンプレート
以下のクイックスタートでは、指定のフレームワークおよび言語の基本アプリケーションを提供します。
CakePHP: PHP web フレームワーク (MySQL データベースを含む)
Dancer: Perl web フレームワーク (MySQL データベースを含む)
Django: Python web フレームワーク (PostgreSQL データベースを含む)
NodeJS: NodeJS web アプリケーション (MongoDB データベースを含む)
Rails: Ruby web フレームワーク (PostgreSQL データベースを含む)
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.yml
が postgresql
アダプターを使用していることを確認する必要があります。
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.yml
の default
セクションを編集する必要があります。環境変数は、後でデータベースサービスを作成する時に定義します。
編集した config/database.yml
の default
セクションに事前定義済みの変数を入力すると、以下のようになります。
<% 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 つの手順を実行します。
- OpenShift Container Platform の「PostgreSQL イメージ」からデータベース「サービス」を作成します。
- OpenShift Container Platform の「Ruby 2.0 ビルダーイメージ」と Ruby on Rails のソースコードでフロントエンドの「サービス」を作成して、データベースサービスと接続します。
- アプリケーションのルートを作成します。
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
の環境変数を指定する必要はありません。
- テンプレートに事前デプロイメントの ライフサイクルフック を追加する。たとえば、Rails サンプル アプリケーションの フックのサンプル を確認します。
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 の設定
正式な Nexus コンテナーイメージをダウンロードし、デプロイします。
oc new-app sonatype/nexus
新規作成した Nexus サービスを公開して、ルートを作成します。
oc expose svc/nexus
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
- ブラウザーで 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
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 Sync の Namespace フィールドを更新します。
- または、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
): ソースが含まれるアーカイブがすでに存在する場合に使用します。アーカイブはtar
、tar.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 クラスターが利用可能であり、アーティファクトを作成できるプロジェクトが用意されていることを前提としています。このチュートリアルでは、git
と oc
がローカルで使用できる必要があります。
7.6.2.1. チュートリアル: ローカルコードの変更のビルド
既存のソースリポジトリーをベースにして新規アプリケーションを作成し、そのルートを作成します。
$ oc new-app https://github.com/openshift/ruby-hello-world.git $ oc expose svc/ruby-hello-world
初期ビルドが完了するまで待機し、ルートのホストに移動してアプリケーションのページを表示すると、Welcome ページが表示されるはずです。
$ oc get route ruby-hello-world
リポジトリーをローカルにクローンします。
$ git clone https://github.com/openshift/ruby-hello-world.git $ cd ruby-hello-world
-
アプリケーションのビューに変更を加えます。任意のエディターで
views/main.rb
を編集します。<body>
タグを<body style="background-color:blue">
に変更します。 ローカルで変更したソースで新規ビルドを起動します。リポジトリーのローカルディレクトリーから、以下を実行します。
---- $ 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. チュートリアル: プライベートコードのビルド
コードを保存するローカルディレクトリーを作成します。
$ mkdir myapp $ cd myapp
このディレクトリーで、以下の内容を含む
Dockerfile
という名前のファイルを作成します。FROM centos:centos7 EXPOSE 8080 COPY index.html /var/run/web/index.html CMD cd /var/run/web && python -m SimpleHTTPServer 8080
以下の内容を含む
index.html
という名前のファイルを作成します。<html> <head> <title>My local app</title> </head> <body> <h1>Hello World</h1> <p>This is my local application</p> </body> </html>
アプリケーションの新規ビルドを作成します。
$ oc new-build --strategy docker --binary --docker-image centos:centos7 --name myapp
ローカルディレクトリーの内容を使用して、バイナリービルドを起動します。
$ oc start-build myapp --from-dir . --follow
new-app
を使用してアプリケーションをデプロイしてから、そのルートを作成します。$ oc new-app myapp $ oc expose svc/myapp
ルートのホスト名を取得して、そこに移動します。
$ 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 パイプラインを作成します。
アプリケーションの新規ディレクトリーを作成します。
$ mkdir mavenapp $ cd mavenapp
WAR を wildfly イメージ内の適切な場所にコピーする
Dockerfile
を作成します。以下をDockerfile
という名前のローカルファイルにコピーします。FROM wildfly:latest COPY ROOT.war /wildfly/standalone/deployments/ROOT.war CMD $STI_SCRIPTS_PATH/run
Dockerfile の新規 BuildConfig を作成します。
注記これにより、ビルドが自動的に起動しますが、
ROOT.war
アーティファクトがまだ利用できないので初回は失敗します。以下のパイプラインでは、バイナリービルドを使用してその WAR をビルドに渡します。$ cat Dockerfile | oc new-build -D - --name mavenapp
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: []
Pipeline ビルドを作成します。Jenkins がプロジェクトにデプロイされていない場合は、パイプラインが含まれる BuildConfig を作成すると、Jenkins がデプロイされます。Jenkins がパイプラインをビルドする準備ができるまで、2 分ほどかかる場合があります。Jenkins のロールアウトの状況を確認するには、
oc rollout status dc/jenkins
を起動します。$ oc create -f ./mavenapp-pipeline.yml
Jenkins の準備ができたら、以前に定義したパイプラインを起動します。
$ oc start-build mavenapp-pipeline
パイプラインがビルドを完了した時点で、new-app で新規アプリケーションをデプロイし、ルートを公開します。
$ oc new-app mavenapp $ oc expose svc/mavenapp
ブラウザーで、アプリケーションのルートに移動します。
$ 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
セクションでは、ビルドの実行に使用するビルドストラテジーを記述します。ここではSource
、Docker
または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
コマンドに以下のオプションのいずれかを指定して実行できます。
オプション | 説明 |
---|---|
|
アーカイブし、ビルドのバイナリー入力として使用するディレクトリーを指定します。 |
|
単一ファイルを指定します。これはビルドソースで唯一のファイルでなければなりません。このファイルは、元のファイルと同じファイル名で空のディレクトリーのルートに置いてください。 |
|
ビルドのバイナリー入力として使用するローカルリポジトリーへのパスを指定します。 |
以下のオプションをビルドに直接指定した場合には、コンテンツはビルドにストリームされ、現在のビルドソースの設定が上書きされます。
バイナリー入力からトリガーされたビルドは、サーバー上にソースを保存しないため、ベースイメージの変更でビルドが再度トリガーされた場合には、ビルド設定で指定されたソースが使用されます。
たとえば、以下のコマンドは、タグ 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 インスタンス全体のデフォルトのビルドの詳細レベルを設定できます。このデフォルトは、指定の BuildConfig
で BUILD_LOGLEVEL
を指定することで上書きできます。コマンドラインで --build-loglevel
を oc start-build
に渡すことで、バイナリー以外のビルドについて優先順位の高い上書きを指定することができます。
ソースビルドで利用できるログレベルは以下のとおりです。
レベル 0 |
assemble スクリプトを実行してコンテナーからの出力とすべてのエラーを生成します。これはデフォルトの設定です。 |
レベル 1 |
実行したプロセスに関する基本情報を生成します。 |
レベル 2 |
実行したプロセスに関する詳細情報を生成します。 |
レベル 3 |
実行したプロセスに関する詳細情報と、アーカイブコンテンツの一覧を生成します。 |
レベル 4 |
現時点ではレベル 3 と同じ情報を生成します。 |
レベル 5 |
これまでのレベルで記載したすべての内容と docker のプッシュメッセージを提供します。 |
8.3. ビルド入力
8.3.1. ビルド入力の仕組み
ビルド入力 は、ビルドが動作するために必要なソースコンテンツを提供します。OpenShift Cotainer Platform では複数の方法でソースを提供します。以下に優先順に記載します。
異なる入力を単一のビルドにまとめることができます。インラインの Dockerfile が優先されるため、別の入力で指定される Dockerfile という名前の他のファイルは上書きされます。バイナリー (ローカル) 入力および Git リポジトリーは併用できません。
入力シークレットは、ビルド時に使用される特定のリソースや認証情報をビルドで生成される最終アプリケーションイメージで使用不可にする必要がある場合や、Secret
リソースで定義される値を使用する必要がある場合に役立ちます。外部アーティファクトは、他のビルド入力タイプのいずれとして利用できない別のファイルをプルする場合に使用できます。
ビルドが実行されるたびに、以下が行われます。
- 作業ディレクトリーが作成され、すべての入力内容がその作業ディレクトリーに配置されます。たとえば、入力 Git リポジトリーのクローンはこの作業ディレクトリーに作成され、入力イメージから指定されたファイルはターゲットのパスを使用してこの作業ディレクトリーにコピーされます。
-
ビルドプロセスによりディレクトリーが
contextDir
に変更されます (定義されている場合)。 - インライン Dockerfile がある場合は、現在のディレクトリーに書き込まれます。
-
現在の作業ディレクトリーにある内容が 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
8.3.2. Dockerfile のソース
dockerfile
の値が指定されると、このフィールドの内容は、Dockerfile という名前のファイルとしてディスクに書き込まれます。これは、他の入力ソースが処理された後に実行されるので、入力ソースリポジトリーの root ディレクトリーに Dockerfile が含まれる場合は、これはこの内容で上書きされます。
このフィールドの一般的な用途は、Dockerfile
を「Docker ストラテジー」ビルドに渡すことです。
ソースの定義は BuildConfig
の spec
セクションに含まれます。
source:
dockerfile: "FROM centos:7\nRUN yum install -y httpd" 1
- 1
dockerfile
フィールドには、ビルドされるインライン Dockerfile が含まれます。
8.3.3. イメージソース
追加のファイルは、イメージを使用してビルドプロセスに渡すことができます。入力イメージは From
および To
イメージターゲットが定義されるのと同じ方法で参照されます。つまり、コンテナーイメージと「イメージストリームタグ」の両方を参照できます。イメージと合わせて、1 つまたは複数のパスのペアを指定して、ファイルまたはディレクトリーのパスを示し、イメージと宛先をコピーしてビルドコンテキストに配置する必要があります。
ソースパスは、指定したイメージ内の絶対パスで指定してください。宛先は、相対ディレクトリーパスでなければなりません。ビルド時に、イメージは読み込まれ、指定のファイルおよびディレクトリーはビルドプロセスのコンテキストディレクトリーにコピーされます。これは、ソースリポジトリーのコンテンツ (ある場合) のクローンが作成されるディレクトリーと同じです。ソースパスの末尾は /. であり、ディレクトリーのコンテンツがコピーされますが、ディレクトリー自体は宛先で作成されません。
イメージのインプットは、BuildConfig
の source
の定義で指定します。
source: git: uri: https://github.com/openshift/ruby-hello-world.git images: 1 - from: 2 kind: ImageStreamTag name: myinputimage:latest namespace: mynamespace paths: 3 - destinationDir: injected/dir 4 sourcePath: /usr/lib/somefile.jar 5 - from: kind: ImageStreamTag name: myotherinputimage:latest namespace: myothernamespace pullSecret: mysecret 6 paths: - destinationDir: injected/dir sourcePath: /usr/lib/somefile.jar
この機能は、カスタムストラテジー を使用したビルドではサポートされません。
8.3.4. git ソース
指定されている場合には、ソースコードが指定先の場所からフェッチされます。
インラインの Dockerfile がサポートされる場合には、git リポジトリー contextDir
内にあるDockerfile (ある場合) が上書きされます。
ソースの定義は BuildConfig
の spec
セクションに含まれます。
source: git: 1 uri: "https://github.com/openshift/ruby-hello-world" ref: "master" contextDir: "app/dir" 2 dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" 3
- 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 リポジトリーにアクセスできる場合には、BuildConfig
の source
セクションで使用するプロキシーを定義できます。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 リポジトリーの認証情報を含む Secret
が BuildConfig
が後に作成される 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 ファイルに証明書ファイルへの参照を追加する必要があります。
- client.crt、cacert.crt および client.key ファイルを「アプリケーションのソースコード」の /var/run/secrets/openshift.io/source/ フォルダーに追加します。
サーバーの .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
シークレットを作成します。
$ 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
パスワードを再度入力しないでいいように、ビルド内に 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.pub
、id_ecdsa.pub
、id_ed25519.pub
または id_rsa.pub
という名前が付けられています。以下のコマンドで、SSH キーの認証情報を生成します。
$ ssh-keygen -t rsa -C "your_email@example.com"
SSH キーのパスフレーズを作成すると、OpenShift Container Platform でビルドができなくなります。パスフレーズを求めるプロンプトが出されても、ブランクのままにします。
パブリックキーと、それに対応するプライベートキーのファイルが 2 つ作成されます (id_dsa
、id_ecdsa
、id_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 証明書ファイルでシークレットを作成する (推奨)
CA が中間証明局を使用する場合には、ca.crt ファイルにすべての CA の証明書を統合します。以下のコマンドを実行してください。
$ cat intermediateCA.crt intermediateCA.crt rootCA.crt > ca.crt
シークレットを作成します。
$ 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. 組み合わせ
ここでは、特定のニーズに対応するために上記の方法を組み合わせてソースクローンのシークレットを作成する方法についての例を紹介します。
.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
.gitconfig ファイルと CA 証明書を組み合わせてシークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> \ --from-file=ca.crt=<path/to/certificate> \ --from-file=<path/to/.gitconfig>
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
.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
.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
と同様に動作しますが、このオプションの引数がディレクトリーの場合には常に、まずアーカイブがホストに作成されます。
上記のそれぞれの例では、以下のようになります。
-
BuildConfig
にBinary
のソースタイプが定義されている場合には、これは事実上無視され、クライアントが送信する内容に置き換えられます。 -
BuildConfig
にGit
のソースタイプが定義されている場合には、Binary
とGit
は併用できないので、動的に無効にされます。この場合、ビルダーに渡されるバイナリーストリームのデータが優先されます。
ファイル名ではなく、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
に入力シークレットを追加するには、以下を行います。
シークレットがない場合は作成します。
$ oc create secret generic secret-npmrc \ --from-file=.npmrc=<path/to/.npmrc>
これにより、secret-npmrc という名前の新しいシークレットが作成されます。これには、~/.npmrc ファイルの base64 でエンコードされたコンテンツが含まれます。
既存の
BuildConfig
のsource
セクションにシークレットを追加します。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 ビルダーイメージでは、これはイメージの作業ディレクトリーで、Dockerfile の WORKDIR
の指示を使用して設定されます。別のディレクトリーを指定するには、シークレットの定義に 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
ストラテジーを使用すると、Dockerfile で ADD
および 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
で定義した環境変数で、ダウンロードする固有ファイルをカスタマイズすることができます。
環境変数の定義には複数の方法があり、いずれかの方法を選択できます。
- .s2i/environment ファイルの使用 (ソースビルドストラテジーのみ)
-
BuildConfig
での設定 -
「
oc start-build --env
を使用した明示的な指定」 (手動でトリガーされるビルドのみ)
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
このファイルに複数の Docker レジストリーを定義できます。または docker login
コマンドを実行して、このファイルに認証エントリーを追加することも可能です。ファイルが存在しない場合には作成されます。
Kubernetes では Secret
オブジェクトが提供され、これを使用して設定とパスワードを保存することができます。
ローカルの .docker/config.json ファイルからシークレットを作成します。
$ oc create secret generic dockerhub \ --from-file=.dockerconfigjson=<path/to/.docker/config.json> \ --type=kubernetes.io/dockerconfigjson
このコマンドにより、
dockerhub
という名前のシークレットの JSON 仕様が生成され、オブジェクトが作成されます。シークレットが作成されたら、これをビルダーサービスアカウントに追加します。ビルドは
builder
ロールで実行されるので、以下のコマンドでシークレットへのアクセスを設定する必要があります。$ oc secrets link builder dockerhub
pushSecret
フィールドをBuildConfig
のoutput
セクションに追加し、作成した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
ビルドストラテジー定義に含まれる
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
ストラテジービルドは、以下の環境変数をアウトプットイメージに設定します。
変数 | 説明 |
---|---|
|
ビルドの名前 |
|
ビルドの namespace |
|
ビルドのソース URL |
|
ビルドで使用する git 参照 |
|
ビルドで使用するソースコミット |
さらに、Source
または Docker
ストラテジーオプションで設定されるユーザー定義の環境変数は、アウトプットイメージの環境変数一覧にも含まれます。
8.4.3. アウトプットイメージのラベル
Docker
および Source
ビルドは、以下のラベルをアウトプットイメージに設定します。
ラベル | 説明 |
---|---|
|
ビルドで使用するソースコミットの作者 |
|
ビルドで使用するソースコミットの日付 |
|
ビルドで使用するソースコミットのハッシュ |
|
ビルドで使用するソースコミットのメッセージ |
|
ソースに指定するブランチまたは参照 |
|
ビルドのソース 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
8.5.1.2. 増分ビルド
S2I は増分ビルドを実行できるので、以前にビルドされたイメージからのアーティファクトが再利用されます。増分ビルドを作成するには、ストラテジー定義に以下の変更を加えて、BuildConfig
を作成します。
strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "incremental-image:latest" 1 incremental: true 2
増分ビルドをサポートするビルダーイメージを作成する方法に関する説明は、「S2I 要件」を参照してください。
8.5.1.3. ビルダーイメージのスクリプトの上書き
ビルダーイメージが提供する assemble、run および save-artifacts の「S2I スクリプト」は、以下 2 種類のいずれかの方法で上書きできます。
- アプリケーションのソースリポジトリーの .s2i/bin ディレクトリーに assemble, run および/または save-artifacts スクリプトを指定します。
- 以下のように、ストラテジー定義の一部として、スクリプトを含むディレクトリーの 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 環境
環境変数を BuildConfig
の sourceStrategy
定義に追加できます。ここに定義されている環境変数は、assemble スクリプトの実行時に表示され、アウトプットイメージで定義されるので、run スクリプトやアプリケーションコードでも利用できるようになります。
Rails アプリケーションのアセットコンパイルを無効にする例:
sourceStrategy: ... env: - name: "DISABLE_ASSET_COMPILATION" value: "true"
ビルド環境 のセクションには、詳細な説明があります。
oc set env
コマンドで、BuildConfig
に定義した環境変数を管理することも可能です。
8.5.1.5. Web コンソールを使用したシークレットの追加
プライベートリポジトリーにアクセスできるようにビルド設定にシークレットを追加するには、以下を実行します。
- 新規の OpenShift Container Platform プロジェクトを作成します。
- プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
- 「Source-to-Image (S2I) ビルド設定」を作成します。
-
ビルド設定のエディターページや、「web コンソール」の fromimage ページの
create app from builder image
ページで ソースシークレット を設定します。 - 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 イメージ
Dockerfile の FROM
命令は、BuildConfig
の from
に置き換えられます。
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
- このフラグがあると、ローカルのビルダーイメージが無視され、イメージストリームが参照するレジストリーから新しいバージョンがプルされます。
forcePull
を false に設定すると、デフォルトの動作として、ローカルに保存されたイメージが使用されます。
8.5.2.5. 環境変数
「Docker ビルド」 ロセスと作成されたイメージで環境変数を利用できるようにするには、BuildConfig
の dockerStrategy
の定義に環境変数を追加します。
ここに定義した環境変数は、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 コンソールを使用したシークレットの追加
プライベートリポジトリーにアクセスできるように、ビルド設定にシークレットを追加するには、以下を実行します。
- 新規の OpenShift Container Platform プロジェクトを作成します。
- プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
- 「docker のビルド設定」を作成します。
- ビルド設定のエディターページまたは、「web コンソール」の fromimage ページで、ソースシークレット を設定します。
- Save ボタンをクリックします。
8.5.2.7. Docker ビルド引数
Docker ビルドの引数 を設定するには、以下のように BuildArgs
配列にエントリーを追加します。これは、BuildConfig
の dockerStrategy
定義の中にあります。
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. シークレット
source と images の secrets に加え、カスタムストラテジーを使用すると、任意のシークレット一覧をビルダー pod に追加できます。
各シークレットは、特定の場所にマウントできます。
strategy: customStrategy: secrets: - secretSource: 1 name: "secret1" mountPath: "/tmp/secret1" 2 - secretSource: name: "secret2" mountPath: "/tmp/secret2"
8.5.3.3.1. Web コンソールを使用したシークレットの追加
プライベートリポジトリーにアクセスできるようにビルド設定にシークレットを追加するには、以下を実行します。
- 新規の OpenShift Container Platform プロジェクトを作成します。
- プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
- 「docker のビルド設定」を作成します。
- ビルド設定のエディターページまたは、「web コンソール」の fromimage ページで、ソースシークレット を設定します。
- Save ボタンをクリックします。
8.5.3.3.2. プルおよびプッシュの有効化
プライベートレジストリーにプルできるようにするには、ビルド設定に Pull Secret
を設定し、プッシュを有効にするには Push Secret
を設定します。
8.5.3.4. 強制プル
ビルド Pod を設定する場合に、ビルドコントローラーはデフォルトで、ビルド設定で指定したイメージがローカルで使用できるかどうかを確認します。ローカルで利用できる場合にはそのイメージが使用されます。ただし、ローカルイメージを上書きして、イメージストリームが参照するレジストリーからイメージを更新する場合には、forcePull
フラグを true に設定して BuildConfig
を作成します。
strategy:
customStrategy:
forcePull: true 1
- 1
- このフラグがあると、ローカルのビルダーイメージが無視され、イメージストリームが参照するレジストリーから新しいバージョンがプルされます。
forcePull
を false に設定すると、デフォルトの動作として、ローカルに保存されたイメージが使用されます。
8.5.3.5. 環境変数
「カスタムビルド」のプロセスで環境変数を利用できるようにするには、環境変数を BuildConfig
の customStrategy
定義に追加します。
ここに定義された環境変数は、カスタムビルドを実行する 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 つの方法のどちらかで提供できます。
- ビルド設定に Jenkinsfile を埋め込む
- 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 ビルド」のプロセスで環境変数を利用できるようにするには、環境変数を BuildConfig
の jenkinsPipelineStrategy
定義に追加します。
定義した後に、環境変数は 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 コンソールから環境変数に対応するパラメーターに対して変更を加えても無視され、BuildConfig
と oc 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 エンドポイントに送信して新規ビルドをトリガーできます。GitHub、GitLab、Bitbucket または 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 を設定するには以下を実行します。
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>.
- GitHub の Web コンソールから、この URL を GitHub にカットアンドペーストします。
- GitHub リポジトリーで、Settings → Webhooks & Services から Add Webhook を選択します。
- Payload URL フィールドに、(上記と同様の) URL の出力を貼り付けます。
-
Content Type を GitHub のデフォルト
application/x-www-form-urlencoded
からapplication/json
に変更します。 - 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 を設定するには以下を実行します。
ビルド設定を記述して、webhook URL を取得します。
$ oc describe bc <name>
-
webhook URL をコピーします。
<secret>
はシークレットの値に置き換えます。 - 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 を設定するには以下を実行します。
ビルド設定を記述して、webhook URL を取得します。
$ oc describe bc <name>
-
webhook URL をコピーします。
<secret>
はシークレットの値に置き換えます。 - 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 ベースイメージ上で実行されるようになります。
イメージ変更のトリガーを設定するには、以下のアクションを実行する必要があります。
トリガーするアップストリームイメージを参照するように、
ImageStream
を定義します。kind: "ImageStream" apiVersion: "v1" metadata: name: "ruby-20-centos7"
この定義では、イメージストリームが <system-registry>/<namespace>/ruby-20-centos7 に配置されているコンテナーイメージリポジトリーに紐付けられます。<system-registry> は、OpenShift Container Platform で実行する
docker-registry
の名前で、サービスとして定義されます。イメージストリームがビルドのベースイメージの場合には、ビルドストラテジーの From フィールドを設定して、イメージストリームを参照します。
strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "ruby-20-centos7:latest"
上記の例では、
sourceStrategy
の定義は、この namespace 内に配置されているruby-20-centos7
という名前のイメージストリームのlatest
タグを使用します。イメージストリームを参照する 1 つまたは複数のトリガーでビルドを定義します。
type: "imageChange" 1 imageChange: {} type: "imagechange" 2 imageChange: from: kind: "ImageStreamTag" name: "custom-image:latest"
ストラテジーイメージストリームにイメージ変更トリガーを使用する場合は、生成されたビルドに不変な 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/orargs
を使用します。注記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
に引数を追加するのと同じです。
script
と command
を同時に指定すると、無効なビルドフックが作成されてしまいます。
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. ビルド実行ポリシーの概要
ビルド実行ポリシーでは、ビルド設定から作成されるビルドを実行する順番を記述します。これには、Build
の spec
セクションにある runPolicy
フィールドの値を変更してください。
既存のビルド設定の runPolicy
値を変更することも可能です。
-
Parallel
からSerial
やSerialLatestOnly
に変更して、この設定から新規ビルドをトリガーすると、新しいビルドは並列ビルドすべてが完了するまで待機します。これは、順次ビルドは、一度に 1 つしか実行できないためです。 -
Serial
をSerialLatestOnly
に変更して、新規ビルドをトリガーすると、現在実行中のビルドと直近で作成されたビルド以外には、キューにある既存のビルドがすべてキャンセルされます。最新のビルドが次に実行されます。
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 により完了されます。プロジェクトのデフォルトのコンテナー制限に、リソースの制限を指定すると、これらのリソースを制限できます。
ビルド設定の一部にリソース制限を指定して、リソースの使用を制限することも可能です。以下の例では、resources
、cpu
および memory
の各パラメーターはオプションです。
apiVersion: "v1" kind: "BuildConfig" metadata: name: "sample-build" spec: resources: limits: cpu: "100m" 1 memory: "256Mi" 2
ただし、「クォータ」がプロジェクトに定義されている場合には、以下の 2 つの項目のいずれかが必要です。
適用されない場合は、クォータ基準を満たさないために失敗したというメッセージが出され、ビルド 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=value2
とkey2=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 つ目のビルドは、イメージからの入力コンテンツを使用可能なストラテジーを使用できます。
最初のビルドは、アプリケーションソースを取得して、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
この設定の結果、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
ビルドプルーニングは、以下のアクションによりトリガーされます。
- ビルド設定が更新された場合
- ビルドのライフサイクルが完了した場合
ビルドは、作成時のタイムスタンプで分類され、一番古いビルドが先にプルーニングされます。
管理者は、「'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 (カスタム) のデプロイメントストラテジーで使用できます。
以下の例では、resources
、cpu
、memory
および ephemeral-storage
はそれぞれオプションです。
type: "Recreate" resources: limits: cpu: "100m" 1 memory: "256Mi" 2 ephemeral-storage: "1Gi" 3
ただし、クォータがプロジェクトに定義されている場合には、以下の 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-node
と region=east
のラベルがクラスター管理者により追加され、上記の disktype: ssd
ラベルを Pod に追加した場合に、Pod は 3 つのラベルすべてが含まれるノードにのみスケジュールされます。
ラベルには値を 1 つしか設定できないので、region=east
が管理者によりデフォルト設定されている Pod 設定に region=west
のノードセレクターを設定すると、Pod が全くスケジュールされなくなります。
9.2.10. 異なるサービスアカウントでの Pod の実行
デフォルト以外のサービスアカウントで Pod を実行できます。
デプロイメント設定を編集します。
$ oc edit dc/<deployment_config>
serviceAccount
とserviceAccountName
パラメーターをspec
フィールドに追加し、使用するサービスアカウントを指定します。spec: securityContext: {} serviceAccount: <service_account> serviceAccountName: <service_account>
9.2.11. Web コンソールを使用してデプロイメント設定にシークレットを追加する手順
プライベートリポジトリーにアクセスできるように、デプロイメント設定にシークレットを追加します。
- 新規の OpenShift Container Platform プロジェクトを作成します。
- プライベートのイメージリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
- デプロイメント設定を作成します。
- デプロイメント設定のエディターページまたは、「web コンソール」の fromimage ページで、プルシークレット を設定します。
- Save ボタンをクリックします。
9.3. デプロイメントストラテジー
9.3.1. デプロイメントストラテジーの概要
アプリケーションを変更またはアップグレードする手段として、デプロイメントストラテジーを使用します。デプロイメントストラテジーの目的は、ユーザーには改善が加えられていることが分からないように、ダウンタイムなしに変更を加えることです。
最も一般的なストラテジーとして blue-green デプロイメント を使用します。新規バージョン (blue バージョン) を、テストと評価用に起動しつつ、安定版 (green バージョン) をユーザーが継続して使用します。準備が整ったら、Blue バージョンに切り替えられます。問題が発生した場合には、Green バージョンに戻すことができます。
一般的な別のストラテジーとして、A/B バージョンがいずれも、同時にアクティブな状態で、A バージョンを使用するユーザーも、B ユーザーを使用するユーザーもいるという方法です。これは、ユーザーインターフェースや他の機能の変更をテストして、ユーザーのフィードバックを取得するために使用できます。また、ユーザーに対する問題の影響が限られている場合に、実稼働のコンテキストで操作が正しく行われていることを検証するのに使用することもできます。
カナリアリリースデプロイメントでは、新規バージョンをテストしますが、問題が検出されると、すぐに以前のバージョンにフォールバックされます。これは、上記のストラテジーどちらでも実行できます。
ルートベースのデプロイメントストラテジーでは、サービス内の Pod 数はスケーリングされません。希望とするパフォーマンスの特徴を維持するには、デプロイメント設定をスケーリングする必要があります。
デプロイメントストラテジーを選択する場合に、考慮するべき事項があります。
- 長期間実行される接続は正しく処理される必要があります。
- データベースの変換は複雑になる可能性があり、アプリケーションと共に変換し、ロールバックする必要があります。
- アプリケーションがマイクロサービスと従来のコンポーネントを使用するハイブリッドの場合には、移行の完了時にダウンタイムが必要になる場合があります。
- これを実行するためのインフラストラクチャーが必要です。
- テスト環境が分離されていない場合は、新規バージョンと以前のバージョン両方が破損してしまう可能性があります。
通常、エンドユーザーはルーターが取り扱うルート経由でアプリケーションにアクセスするので、デプロイメントストラテジーは、デプロイメント設定機能またはルーティング機能にフォーカスできます。
デプロイメント設定にフォーカスするストラテジーは、アプリケーションを使用するすべてのルートに影響を与えます。ルーター機能を使用するストラテジーは個別のルートをターゲットに設定します。
デプロイメントストラテジーの多くは、デプロイメント設定でサポートされ、追加のストラテジーはルーター機能でサポートされます。このセクションでは、デプロイメント設定をベースにするストラテジーについて説明します。
- ローリングストラテジー およびカナリアリリースデプロイメント
- 再作成ストラテジー
- カスタムストラテジー
- ルートを使用した Blue-Green デプロイメント
- ルートを使用した A/B デプロイメント およびカナリアリリースデプロイメント
- 1 サービス、複数デプロイメント設定
ローリングストラテジー は、ストラテジーがデプロイメント設定に指定されていない場合にデフォルトで使用するストラテジーです。
デプロイメントストラテジーは、Readiness チェック を使用して、新しい Pod の使用準備ができているかを判断します。Readiness チェックに失敗すると、デプロイメント設定は、タイムアウトするまで pod の実行を再試行します。デフォルトのタイムアウトは、10m
で、値は dc.spec.strategy.*params
の TimeoutSeconds
で設定します。
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
ライフサイクルフックを実行します。
スケールダウン時には、ローリングストラテジーは 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 では、ローリングデプロイメントはデフォルト設定です。ローリングアップデートを行うには、以下の手順に従います。
DockerHub にあるデプロイメントイメージの例を基にアプリケーションを作成します。
$ oc new-app openshift/deployment-example
ルーターをインストールしている場合は、ルートを使用してアプリケーションを利用できるようにしてください (または、サービス IP を直接使用してください)。
$ oc expose svc/deployment-example
deployment-example.<project>.<router_domain>
でアプリケーションを参照し、v1 イメージが表示されることを確認します。レプリカが最大 3 つになるまで、デプロイメント設定をスケーリングします。
$ oc scale dc/deployment-example --replicas=3
新しいバージョンの例を
latest
とタグ付けして、新規デプロイメントを自動的にトリガーします。$ oc tag deployment-example:v2 deployment-example:latest
- ブラウザーで、v2 イメージが表示されるまでページを更新します。
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: {}
再作成ストラテジーは以下を行います。
-
pre
ライフサイクルフックを実行します。 - 以前のデプロイメントをゼロにスケールダウンします。
-
mid
ライフサイクルフックを実行します。 - 新規デプロイメントをスケールアップします。
-
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 は以下の環境変数もデプロイメントプロセスに提供します。
環境変数 | 説明 |
---|---|
|
新規デプロイメント名 (レプリケーションコントローラー) |
|
新規デプロイメントの 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
- 1
execNewPod
は Pod ベースのライフサイクルフック です。
フックにはすべて、フックに問題が発生した場合にストラテジーが取るべきアクションを定義する failurePolicy
が含まれます。
|
フックに失敗すると、デプロイメントプロセスも失敗とみなされます。 |
|
フックの実行は、成功するまで再試行されます。 |
|
フックの失敗は無視され、デプロイメントは続行されます。 |
フックには、フックの実行方法を記述するタイプ固有のフィールドがあります。現在、フックタイプとしてサポートされているのは 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
この例では 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 アプリケーションに最適です。
アプリケーションサンプルを 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 イメージを実行するコンポーネントです。以前のサービスを参照するルートを作成します。
$ oc expose svc/example-green --name=bluegreen-example
bluegreen-example.<project>.<router_domain>
で、アプリケーションを参照して v1 イメージが表示されることを確認します。注記OpenShift Container Platform v3.0.1 以前のバージョンでは、このコマンドは、上記の場所ではなく
example-green.<project>.<router_domain>
にルートを生成します。ルートを編集して、サービス名を
example-blue
に変更します。$ oc patch route/bluegreen-example -p '{"spec":{"to":{"name":"example-blue"}}}'
- ルートが変更されたことを確認するには、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_weight
を sum_of_weights
で除算します。エンドポイントの weights
の合計がサービスの weight
になるように、サービスごとの weight
がサービスのエンドポイントに分散されます。
ルートにはサービスを 4 つ含めることができます。サービスの weight
は、0
から 256
で指定してください。weight
が 0
の場合は、新しい要求はサービスに移動せずに、既存の接続がアクティブのままになります。サービスの weight
が 0
でない場合は、エンドポイントの最小 weight
は 1
となります。これにより、エンドポイントが多数含まれるサービスは、最終的に希望の weight
よりも多くなってしまう可能性があります。このような場合は、希望とする負荷分散の weight
になるように、Pod の数を減らして