Spring Boot 開発者の Dekorate ガイド
Dekorate を使用して、OpenShift とスタンドアロンの RHEL へのデプロイメント用に Spring Boot アプリケーションを自動的に設定します。
概要
はじめに
Dekorate を使用して Spring Boot アプリケーションのコードを処理し、アプリケーションのマニフェストファイルを自動的に生成し、デプロイメントを OpenShift に設定します。
Red Hat ドキュメントへのフィードバック (英語のみ)
Red Hat ドキュメントに関するご意見やご感想をお寄せください。フィードバックをお寄せいただくには、ドキュメントのテキストを強調表示し、コメントを追加できます。
このセクションでは、フィードバックの送信方法を説明します。
前提条件
- Red Hat カスタマーポータルにログインしている。
- Red Hat カスタマーポータルで、マルチページ HTML 形式でドキュメントを表示している。
手順
フィードバックを提供するには、以下の手順を実施します。
ドキュメントの右上隅にある Feedback ボタンをクリックして、既存のフィードバックを確認します。
注記フィードバック機能は、Multi-page HTML 形式でのみ有効です。
- フィードバックを提供するドキュメントのセクションを強調表示します。
強調表示されたテキスト近くに表示される Add Feedback ポップアップをクリックします。
ページの右側のフィードバックセクションにテキストボックスが表示されます。
テキストボックスにフィードバックを入力し、Submit をクリックします。
ドキュメントに関する問題が作成されます。
- 問題を表示するには、フィードバックビューで問題トラッカーリンクをクリックします。
第1章 Spring Boot アプリケーションでの Dekorate の使用
Dekorate を使用して、アプリケーションマニフェストファイルを自動的に生成し、OpenShift にデプロイするためにアプリケーションを設定します。
1.1. Dekorate の概要
Dekorate は、コンパイル時のアノテーションプロセッサーおよび Red Hat build of Spring Boot で提供されるアプリケーションリソースジェネレーターのコレクションです。これは、アプリケーションをビルドして設定プロパティーを抽出する際に、コードでアノテーションを解析することで機能します。次に、Dekorate は、展開したプロパティーの値を使用して、アプリケーションを Kubernetes または OpenShift クラスターにデプロイするために使用できるアプリケーション設定リソースを生成します。
開発者は、コードにアノテーションを付けた後に Dekorate を使用してアプリケーションのビルド時にアプリケーションマニフェストを自動的に生成できます。これにより、アプリケーションをデプロイするためのリソースファイルを手動で作成する必要がなくなります。アプリケーションが、Spring Boot などのリッチアプリケーションのランタイムフレームワークに基づいていると、Spring Boot、Dokorate はフレームワークと直接統合でき、フレームワークによって提供される API から設定パラメーターを抽出できるため、コードにアノテーションを付ける必要がなくなります。Dekorate は、以下を使用してアプリケーションを自動的に設定できます。
- マニフェストファイルの設定に使用される値およびメタデータを取得するためにアプリケーションコードで Dekorate 固有のアノテーションを解析します。
-
application.properties、application.yamlなどの設定リソースから情報の抽出 -
リッチアプリケーションフレームワークから必要なメタデータを取得し、
application.propertiesファイルまたはapplication.ymlファイルから設定値を展開
アプリケーションのリソース定義を生成するほか、Deskrate はフックを提供し、OpenShift クラスターの Dekorate でアプリケーションをビルドおよびデプロイできます。また、アプリケーションを作成する言語とは独立して機能し、幅広いビルドシステムで使用できます。Dekorate は、Maven BOM として配布されるライブラリーのセットで設定されます。ライブラリーをアプリケーションプロジェクトの依存関係として追加し、アプリケーションと Dekorate を使用することができます。
Red Hat は Dekorate を使用して、Spring Boot をベースとする Java アプリケーションを OpenShift Container Platform にデプロイするのに使用できるリソースファイルとフックの生成をサポートします。
1.1.1. 関連情報
- OpenShift の Dekorate 設定プロパティー の参照
- Source-to-Image の Dekorate 設定プロパティー への参照
- コミュニティードキュメントの すべての Dekorate Configuration プロパティー への参照
1.2. Dekorate を使用するためのアプリケーションプロジェクトの設定
Dekorate BOM および OpenShift Annotations Starter をアプリケーションプロジェクトの pom.xml ファイルに追加します。基本的なアノテーションをソースファイルに追加し、Maven でアプリケーションをパッケージ化してアプリケーションマニフェストを生成します。
前提条件
- Spring Boot を使用するよう設定された Maven ベースの Java アプリケーションプロジェクト。
- Java JDK 8 または JDK 11 がインストールされている。
- Maven がインストールされている。
手順
Dekorate OpenShift Spring Starter をアプリケーションの
pom.xmlファイルに追加して、Dekorate がアプリケーションのソースコードとリソースファイルを処理できるようにします。<project> ... <dependencies> ... <dependency> <!-- The OpenShift Spring Starter automatically imports the "io.dekorate:openshift-annotations" dependency. --> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>${dekorate.version}</version> </dependency> ... </dependencies> ... <project>@SpringBootApplicationアノテーションをアプリケーションプロジェクトのメインクラスファイルに追加します。package org.acme; @SpringBootApplication public class Application { }アプリケーションをパッケージ化して、アプリケーションコードおよびリソースファイルを Dekorate で処理します。
mvn clean package
-
生成された OpenShift マニフェストが含まれる
target/classes/META-INF/dekorateディレクトリーに移動します。
1.3. Dekorate を使用したアプリケーション設定のカスタマイズ
Dekorate を使用して、OpenShift でのデプロイメント用にアプリケーションの設定をカスタマイズします。
- アプリケーションのソースのアノテーションで設定パラメーターを指定
-
application.propertiesファイルでのプロパティーの設定
以下の例は、OpenShift へのデプロイ時に 2 つのレプリカで始まるようにアプリケーションを設定する方法を示しています。
前提条件
- Spring Boot および Dekorate を使用するよう設定された Maven ベースの Java アプリケーションプロジェクト。
- Java JDK 8 または JDK 11 がインストールされている。
- Maven がインストールされている。
手順
Dekorate OpenShift Annotations モジュールを、アプリケーションの
pom.xmlファイルの依存関係として追加します。<project> ... <dependencies> ... <dependency> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>${dekorate.version}</version> </dependency> ... </dependencies> ... <project>OpenShift へのデプロイ時に、アプリケーションが開始するデフォルトのレプリカ数を設定します。
@OpenshiftApplicationアノテーションをアプリケーションのメインソースファイルに追加し、レプリカ数を 2 に設定します。アプリケーションのビルドとデプロイ時に、実行中のメインのアプリケーションコンテナーの 2 つのレプリカで自動的に起動します。package org.acme; import io.dekorate.openshift.annotation.OpenshiftApplication; // include the parameter for the number of replicas to @OpenshiftApplication(replicas=2) @SpringBootApplication public class Application { }または、アプリケーションの
application.propertiesファイルにdekorate.openshift.replicas=2プロパティーを設定します。/src/main/resources/application.properties
dekorate.openshift.replicas=2
アプリケーションをパッケージ化します。
mvn clean package
target/classes/META-INF/dekorateに移動し、Dekorate が生成したマニフェストを表示します。デプロイメント設定 YAML テンプレートのレプリカ数は 2 に設定されます。... spec: replicas: 2 selector: matchLabels: app: acme ...
関連情報
1.4. Spring Boot アプリケーションでのアノテーションレス設定の使用
Dekorate を使用して、application.properties ファイルおよび application.yml ファイルから dekorate 設定プロパティーを抽出して、Spring Boot アプリケーションプロジェクトの OpenShift リソース設定ファイルを生成します。Dekorate は、Spring Boot から必要なメタデータとプロパティーファイルから設定パラメーターを取得できるため、このメソッドにはアプリケーションソースにアノテーションを付ける必要はありません。アノテーションのない設定は、Spring Boot と Dekorate の間のリッチフレームワーク統合機能です。
前提条件
- Spring Boot および Dekorate を使用するよう設定された Maven ベースのアプリケーションプロジェクト。
-
@SpringBootApplicationアノテーションが付けられたアプリケーションプロジェクトの 1 つ以上のクラス。 - Java JDK 8 または JDK 11 がインストールされている。
- Maven がインストールされている。
手順
アプリケーションの
pom.xmlファイルに以下の依存関係を追加します。<project> ... <dependencies> ... <!-- The OpenShift Spring Starter automatically adds "io.dekorate:openshift-annotations" as a transitive dependency --> <dependency> <groupId>io.dekorate</groupId> <artifactId>openshfit-spring-starter</artifactId> <version>${dekorate.version}</version> </dependency> ... </dependencies> ... <project>-
Dekorate 設定プロパティーをプロジェクトの
application.propertiesファイルまたはapplication.ymlファイルに追加します。Dekorate プロパティーアノテーションをソースファイルに追加する必要はありません。ソースファイルのアノテーションを使用できますが、これを行う場合は、アノテーションで提供されるパラメーターをapplication.propertiesファイルまたはapplication.ymlファイルにあるパラメーターで上書きします。 アプリケーションをパッケージ化します。
mvn clean package
アプリケーションの Dekorate をビルドすると、アプリケーションプロジェクト内の以下のリソースの設定が解析されます。設定リソースは優先順に解析されます。つまり、異なるタイプの 2 つの異なるリソースが同じ設定パラメーターに異なる値を持っている場合、Dekorate は優先度のリストにあるリソースから取得した値を使用します。たとえば、ソースのアノテーションがパラメーター値を指定するものの、
application.ymlの同じパラメーターに異なる値が指定されている場合、Dekorate はapplication.ymlから取得する値を使用します。Dekorate は、以下の優先順位でプロジェクトリソースを解析します。- アノテーション
-
application.properties -
application.yaml -
application.yml
-
生成された
openshift.jsonおよびopenshift.ymlマニフェストファイルが含まれるtarget/classes/META-INF/dekorateディレクトリーに移動します。
1.5. Dekorate を使用した OpenShift Source-to-Image ビルドの自動実行
Maven でアプリケーションをコンパイルした後に、Dekorate を使用して OpenShift コンテナーイメージビルドを自動的に実行できます。
Dekorate を使用して Source-to-Image ビルドを自動的にトリガーする機能は テクノロジープレビュー として利用できます。Red Hat は、実稼働環境でのこの機能の使用に対するサポートを提供していません。
前提条件
- Spring Boot および Dekorate を使用するよう設定された Maven ベースのアプリケーションプロジェクト。
-
@SpringBootApplicationアノテーションがプロジェクトのソースファイルに追加されている。 - Java JDK 8 または JDK 11 がインストールされている。
- Maven がインストールされている。
-
ocコマンドラインツールがインストールされている。 -
ocコマンドラインツールを使用して OpenShift クラスターにログインしている。
手順
Dekorate OpenShift Spring Starter を依存関係としてアプリケーションの
pom.xmlファイルに追加します。このモジュールは、すべての Dekorate OpenShift Starters に推移的な依存関係として含まれていることに注意してください。<project> ... <dependencies> ... <dependency> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>${dekorate.version}</version> </dependency> ... </dependencies> ... <project>アプリケーションをビルドしてデプロイします。Maven がアプリケーションをコンパイルした後にコンテナーイメージビルドを実行するための
-Ddekorate.build=trueプロパティーを含めます。Source-to-Image ビルドを自動的に実行する機能は テクノロジープレビュー として提供されることに注意してください。$ mvn clean install -Ddekorate.build=true
Maven でアプリケーションをコンパイルした後に、コマンドラインから Source-to-image ビルドを手動で実行することもできます。
# Process your application YAML template that is generated by Dekorate: $ oc apply -f target/classes/META-INF/dekorate/openshift.yml # Execute the Source-to-image build and deploy your application to the OpenShift cluster: $ oc start-build example --from-dir=./target --follow
1.6. OpenShift での Spring Boot での Dekorate の使用
以下の例は、方法を示しています。
-
アプリケーションで
openshift-spring-staterを使用できます。 - Dekorate は、アプリケーションのタイプを自動的に識別し、OpenShift サービスルートおよびプローブを随時設定できます。
- Maven がアプリケーションをコンパイルした後に、source-to-image ビルドをトリガーするようにアプリケーションを設定できます。
前提条件
- Spring Boot および Dekorate を使用するよう設定された Maven ベースのアプリケーションプロジェクト。
-
@SpringBootApplicationアノテーションがプロジェクトのソースファイルに追加されている。 - Java JDK 8 または JDK 11 がインストールされている。
- Maven がインストールされている。
-
ocコマンドラインツールがインストールされている｡ -
ocコマンドラインツールを使用して OpenShift クラスターにログインしている。
手順
Dekorate Spring Starter は、アプリケーションプロジェクトの
pom.xmlファイルの依存関係として追加します。pom.xml
<project> ... <dependencies> ... <dependency> <groupId>io.dekorate</groupId> <artifactId>openshift-spring-starter</artifactId> <version>${dekorate.version}</version> </dependency> ... </dependencies> ... <project>@SpringBootApplicationアノテーションをMain.javaクラスに追加します。これにより、アプリケーションをコンパイルする際に source-to-image ビルドを開始できます。/src/main/java/io/dekorate/example/sbonopenshift/Main.java
package io.dekorate.example.sbonopenshift; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class Main { public static void main(String[] args) { SpringApplication.run(Main.class, args); } }Rest コントローラーをアプリケーションに追加します。
/src/main/java/io/dekorate/example/sbonopenshift/Controller.java
package io.dekorate.example.sbonopenshift; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class Controller { @RequestMapping("/") public String hello() { return "Hello world"; } }Dekorate Spring スターターによって提供される Spring アプリケーションプロセッサーは Rest コントローラーを自動的に検出し、アプリケーションタイプを Web アプリケーションとして識別します。Web アプリケーションの場合、Dekorate は OpenShift アプリケーションテンプレートを自動的に生成し、以下を設定します。
- アプリケーションの OpenShift Service ルート
- アプリケーションのルートにおけるサービスの公開
- Liveness および Readiness プローブの設定
-
アプリケーションをビルドしてデプロイします。Maven がアプリケーションをコンパイルした後に source-to-image ビルドを自動的に実行するには、
-Ddekorate.deploy=trueプロパティーを含めます。
mvn clean install -Ddekorate.deploy=true
1.7. OpenShift の Dekorate 設定プロパティー
以下の表に記載されているプロパティーは、Depkorate が OpenShift へのデプロイメントに使用する値を設定します。Dekorate は、これらのプロパティーで指定した値を使用して、アプリケーションプロジェクトに生成された Deployment Configuration およびアプリケーションリソースファイルを設定します。各プロパティーは、特定のプロパティーのテーブルに記載されているデータ型の値を受け入れます。一部のプロパティーには、これらの属性に値を指定しない場合に Dekorate が使用するデフォルト値があります。これらのプロパティーは、アプリケーションプロジェクトの application.properties ファイルで設定できます。
表1.1 OpenShift の Dekorate アプリケーションプロパティー
| プロパティー | データ型 | 説明 | デフォルト値 (該当する場合) |
|---|---|---|---|
|
| String | アプリケーションが属するコンポーネントのコレクション名。このプロパティーの値は、デプロイメント設定やサービスなど、アプリケーションに含まれる他の Kubernetes リソースの名前で使用されます。 |
このプロパティーの値を指定しない場合、Dokorate はアプリケーションの Maven プロジェクトで使用する |
|
| String | アプリケーションの名前。このプロパティーの値は、デプロイメント設定やサービスなど、アプリケーションに含まれる他の Kubernetes リソースの名前で使用されます。 |
このプロパティーの値を指定しない場合、Dokorate は、アプリケーションの Maven プロジェクトに使用する |
|
| String | アプリケーションのバージョン。このプロパティーの値は、デプロイメント設定やサービスなど、アプリケーションに含まれるすべての Kubernetes リソースの名前で使用されます。 |
このプロパティーの値を指定しない場合、Dokorate はアプリケーションの Maven プロジェクトで指定する |
|
| Container[] | アプリケーションで使用する init コンテナーを指定します。 | |
|
| Label[] | アプリケーションのすべてのリソースに追加するカスタムラベルを指定します。 | |
|
| Annotation[] | アプリケーションのすべてのリソースに追加するカスタムアノテーションを指定します。 | |
|
| Env[] | アプリケーション用に作成したすべてのコンテナーに定義する環境変数を指定します。 | |
|
| String | アプリケーションコンテナーの作業ディレクトリーを指定します。 | |
|
| String[] | コンテナーで使用するコマンドを指定します。 | |
|
| String[] | コンテナーで使用するカスタムコマンドライン引数を指定します。 | |
|
| int | アプリケーションのデプロイ時に作成するアプリケーションコンテナーのレプリカ数を指定します。 |
|
|
| String | アプリケーションが使用するサービスアカウントの名前を指定します。 | |
|
| String | アプリケーションが実行しているホストノードの名前 | |
|
| Port[] | 提供するサービスが公開されるネットワークポート | |
|
| ServiceType | アプリケーション用に生成されるサービスのタイプ |
|
|
| PersistentVolumeClaimVolume[] | アプリケーションのすべてのコンテナーに割り当てる永続ボリューム要求 (PVC) | |
|
| SecretVolume[] | アプリケーションのすべてのコンテナーに割り当てるシークレットボリューム | |
|
| ConfigMapVolume[] | アプリケーションのすべてのコンテナーに割り当てる ConfigMap ボリューム | |
|
| GitRepoVolume[] | アプリケーションのすべてのコンテナーに割り当てる Git リポジトリーボリューム | |
|
| AwsElasticBlockStoreVolume[] | アプリケーションのすべてのコンテナーに割り当てる AWS Elastic Block Store ボリューム | |
|
| AzureDiskVolume[] | アプリケーションのすべてのコンテナーに割り当てる Microsoft Azure ディスクボリューム | |
|
| AzureFileVolume[] | アプリケーションのすべてのコンテナーに割り当てる Azure ファイルボリューム | |
|
| Mount[] | アプリケーションのすべてのコンテナーに割り当てるマウント | |
|
| ImagePullPolicy | アプリケーションのデプロイ時に使用するイメージプルポリシーを指定します。 |
|
|
| String[] | アプリケーションのデプロイ時に使用するイメージプルシークレットポリシーを指定します。 | |
|
| プローブ | アプリケーションコンテナーの Liveness プローブの設定 | |
|
| プローブ | アプリケーションコンテナーの Readiness プローブの設定 | |
|
| ResourceRequirements | アプリケーションコンテナーが要求するリソースの量の指定 | |
|
| ResourceRequirements | アプリケーションコンテナーのリソース制限を設定します。 | |
|
| Container[] | サイドカーコンテナーとしてデプロイするコンテナーの指定 | |
|
| boolean | デプロイ後にアプリケーションの Route を公開するかどうかを設定します。 |
|
|
| boolean | 生成するサービスがヘッドレスを実行するかどうかを設定します。 |
|
|
| boolean |
デプロイフックを生成する際にアプリケーションが自動的にデプロイされるかどうかを設定します。このプロパティーをアプリケーションで設定するには、 |
|
|
| String |
使用するデプロイメントリソースの種類。サポートされている値は |
|
1.8. Source-to-Image の Dekorate 設定プロパティー
以下の表に記載されているプロパティーは、Depkorate が Source-to-Image (s2i) を設定してアプリケーション用にビルドするために使用する値を設定します。これらのプロパティーは、アプリケーションプロジェクトの application.properties ファイルで設定できます。
表1.2 S2i の Dekorate 設定プロパティー
| プロパティー | データ型 | 説明 | デフォルト値 (該当する場合) |
|---|---|---|---|
|
| boolean | アプリケーション用の s2i ビルドフックの生成を有効にします。 |
|
|
| String | ビルドするイメージのレジストリー名を指定します。 | |
|
| String | アプリケーションのグループ ID を指定します。この値は、構築する docker イメージのユーザー名として使用されます。 | |
|
| String | アプリケーションの名前を指定します。この値は、ビルドするイメージの名前として使用されます。 | |
|
| String | アプリケーションのバージョン。この値は、ビルドするイメージのタグとして使用されます。 | |
|
| String |
ビルドするイメージの完全な参照を指定します。このプロパティーを設定すると、 | |
|
| String | アプリケーションプロジェクトのルートディレクトリーからの Dockerfile への相対パスを指定します。 |
|
|
| String | 使用する S2i ビルダーイメージの名前を指定します。 |
|
|
| Env[] | s2i ビルドの環境変数を設定します。 | |
|
| boolean |
|
|
|
| boolean |
|
|
|
| boolean |
|
|
付録A Source-to-Image (S2I) ビルドプロセス
Source-to-Image (S2I) は、アプリケーションソースのあるオンライン SCM リポジトリーから再現可能な Docker 形式のコンテナーイメージを生成するビルドツールです。S2I ビルドを使用すると、ビルド時間を短縮し、リソースおよびネットワークの使用量を減らし、セキュリティーを改善し、その他の多くの利点を使用して、アプリケーションの最新バージョンを実稼働に簡単に配信できます。OpenShift は、複数の ビルドストラテジーおよび入力ソース をサポートします。
詳細は、OpenShift Container Platform ドキュメントの Source-to-Image (S2I) ビルド の章を参照してください。
最終的なコンテナーイメージをアセンブルするには、S2I プロセスに 3 つの要素を指定する必要があります。
- GitHub などのオンライン SCM リポジトリーでホストされるアプリケーションソース。
- S2I Builder イメージ。アセンブルされたイメージの基盤となり、アプリケーションを実行しているエコシステムを提供します。
- 必要に応じて、S2I スクリプト によって使用される環境変数およびパラメーターを指定することもできます。
このプロセスは、S2I スクリプトで指定された指示に従ってアプリケーションソースおよび依存関係を Builder イメージに挿入し、アセンブルされたアプリケーションを実行する Docker 形式のコンテナーイメージを生成します。詳細は、OpenShift Container Platform ドキュメントの S2I ビルド要件、ビルドオプション および ビルドの仕組み を参照してください。
付録B 追加の Spring Boot リソース
付録C アプリケーション開発リソース
OpenShift でのアプリケーション開発に関する詳細は、以下を参照してください。
ネットワーク負荷を軽減し、アプリケーションのビルド時間を短縮するには、OpenShift Container Platform で Maven の Nexus ミラーをセットアップします。
付録D 習熟度レベル
利用可能な各例は、特定の最小知識を必要とする概念について言及しています。この要件は例によって異なります。最小要件と概念は、いくつかの上達度レベルで設定されています。ここで説明するレベルの他に、各例に固有の追加情報が必要になる場合があります。
Foundational
Foundational と評価された例は、通常、サブジェクトに関する事前の知識を必要としません。それらは、重要な要素、概念、および用語の一般的な認識およびデモンストレーションを提供します。この例の説明に直接記載されているものを除き、特別な要件はありません。
Advanced
Advanced サンプルを使用する場合は、Kubernetes および OpenShift に加えて、例のサブジェクトエリアの一般的な概念および用語に精通していることを前提としています。サービスやアプリケーションの設定、ネットワークの管理など、独自の基本的なタスクを実行できるようにする必要があります。この例ではサービスが必要で、設定がサンプルの範囲に含まれていない場合は、適切に設定する知識があり、サービスの結果として生じる状態のみがドキュメントに記載されていることを前提とします。
Expert
Expert サンプルは、サブジェクトに関する最高レベルの知識が必要です。機能ベースのドキュメントとマニュアルに基づいて多くのタスクを実行することが期待されており、ドキュメントは最も複雑なシナリオを対象としています。
