付録C Fabric8 Maven プラグイン

C.1. 概要

fabric8-maven-plugin を利用すると、Java アプリケーションを OpenShift にデプロイできます。これは Maven との緊密なインテグレーションを提供し、すでに提供されているビルド設定の利点を活用できます。このプラグインは以下のタスクを中心に行います。

Docker 形式イメージのビルド
OpenShift リソース記述子の作成

大変柔軟に設定でき、以下を作成するために複数の設定モデルをサポートします。

Zero-Config の設定: opinionated default (推奨されるデフォルト) で迅速な立ち上げが可能になります。または、より高度な要件を可能にします。
XML 設定: pom.xml ファイルに追加できるその他の設定オプションを提供します。

C.1.1. イメージのビルド

fabric8:build ゴールは、アプリケーションが含まれる Docker 形式イメージの作成に使用されます。ビルドアーティファクトやイメージの依存関係を簡単に含めることができます。このプラグインは maven-assembly-plugin のアセンブリー記述子を使用し、イメージに追加されるコンテンツを指定します。

重要

Fuse on OpenShift では、OpenShift s2i ビルドストラテジーのみがサポートされます。docker ビルドストラテジーはサポートされません。

C.1.2. Kubernetes および OpenShift リソース

Kubernetes および OpenShift リソース記述子は、fabric8:resource で作成できます。これらのファイルは Maven アーティファクト内にパッケージされ、fabric8:apply を使用して稼働中のオーケストレーションプラットフォームにデプロイできます。

C.1.3. 設定

4 つのレベルの設定があります。

Zero-Config モードは、pom.xml ファイルにあるデータを基にして、使用するベースイメージや公開するポートなど、非常に的確な決定を行えるようにします。これは開始点として使用され、クイックスタートアプリケーションを小さくきれいに維持するために使用されます。
XML プラグイン設定モードは docker-maven-plugin が提供するモードと似ています。IDE サポートでタイプセーフな設定が可能ですが、可能なリソース記述子機能のサブセットのみが提供されます。
Kubernetes and OpenShift リソースフラグメントは、プラグインで強化できるユーザー提供の YAML ファイルです。これにより、上級ユーザーはすべての機能が含まれるプレーンな設定ファイルを使用できますが、プロジェクト固有のビルド情報を追加したり、定型コードの使用を回避することができます。OpenShift クラスターで docker compose デプロイメントを立ち上げるために Docker Compose が使用されます。これには、OpenShift のデプロイメントプロセスに関する知識はほとんど必要ありません。Cluster Operator 設定についての詳細は、https://maven.fabric8.io/#configuration を参照してください。

C.2. プラグインのインストール

Fabric8 Maven プラグインは Maven の中央リポジトリーで使用でき、以下のようにインテグレーション前後のフェーズに接続することができます。

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>fabric8-maven-plugin</artifactId>
  <version>${fuse.version}</version>

  <configuration>
     ....
     <images>
        <!-- A single's image configuration -->
        <image>
          ...
          <build>
           ....
          </build>
        </image>
        ....
     </images>
  </configuration>

  <!-- Connect fabric8:resource and fabric8:build to lifecycle phases -->
  <executions>
    <execution>
       <id>fabric8</id>
       <goals>
         <goal>resource</goal>
         <goal>build</goal>
       </goals>
    </execution>
  </executions>
</plugin>

C.3. ゴールの理解

Fabric8 Maven プラグインは、スムーズな Java 開発環境を提供するゴールのセットをサポートします。ゴールは以下のように分類できます。

ビルドゴールは、Docker 形式イメージや S2I ビルドなどの Kubernetes および OpenShift ビルドアーティファクトを作成および管理するために使用されます。
開発ゴールは、リソース記述子を開発クラスターにデプロイするために使用されます。また、開発クラスターのライフサイクルを管理するのにも便利です。

C.3.1. ビルドおよび開発ゴールの理解

Red Hat Fabric Integration Services 製品の Fabric8 Maven プラグインによってサポートされるゴールは次のとおりです。

表C.1 ビルドゴール
ゴール	説明
fabric8:build	ビルドイメージ。Fuse on OpenShift では、OpenShift `s2i` ビルドストラテジーのみがサポートされることに注意してください。`docker` ビルドストラテジーはサポートされません。
fabric8:resource	Kubernetes または OpenShift リソース記述子を作成します。
fabric8:apply	リソースを実行中のクラスターに適用します。
fabric8:resource-apply	`fabric8:resource` `fabric8:apply` を実行します。

表C.2 開発ゴール
ゴール	説明
fabric8:run	フォアグラウンドで完全な開発ワークフローサイクル `fabric8:resource` `fabric8:build` `fabric8:apply` を実行します。
fabric8:deploy	リソース記述子の作成後にクラスターへデプロイし、アプリケーションをビルドします。バックグラウンドで実行すること以外は `fabric8:run` と同じです。
fabric8:undeploy	クラスターからリソース記述子をアンデプロイおよび削除します。
fabric8:start	以前デプロイされたアプリケーションを開始します。
fabric8:stop	以前デプロイされたアプリケーションを停止します。
fabric8:log	実行中のアプリケーションのログを表示します。
fabric8:debug	リモートのデバッグを有効にします。
fabric8:watch	プロジェクトワークスペースで変更を監視し、アプリケーションの再デプロイメントを自動的にトリガーします。

C.3.2. 環境変数の設定

以下のように XML 設定に env パラメーターを追加して、1 つ以上の環境変数を設定できます。例を以下に示します。

<configuration>
  <resources>
    <env>
        <JAVA_OPTIONS>-Dmy.custom=option</JAVA_OPTIONS>
        <MY_VAR>value</MY_VAR>
    </env>
  </resources>
</configuration>

C.3.3. リソース検証設定

fabric8:resource ゴールは、Kubernetes および OpenShift の API 仕様を使用して、生成されたリソース記述子を検証します。

表C.3 リソース検証設定
設定	説明	デフォルト
`fabric8.skipResourceValidation`	値が true に設定されている場合、リソース検証はスキップされます。これは、何らかの理由でリソース検証に失敗してもデプロイメントを継続したい場合に便利です。	false
`fabric8.failOnValidationError`	値が true に設定されている場合、検証エラーによってプラグインの実行がブロックされます。true に設定されていない場合は警告が表示されます。	false
`fabric8.build.switchToDeployment`	値が true に設定され、OpenShift で ImageStreams を使用していない場合、fabric8-maven-plugin は DeploymentConfig ではなく Deployments に切り替わります。	false
`fabric8.openshift.trimImageInContainerSpec`	値が true に設定されている場合、コンテナーイメージ参照が "" に設定されます。これは、後続のロールアウトによって `ImagePullErr` が発生する OpenShift 3.7 での不適切な動作を処理するためのものです。	false

Fabric8 Maven プラグインゴールの詳細は「https://maven.fabric8.io/#goals」を参照してください。

C.4. ジェネレーター

Fabric8 Maven プラグインは、特定の種類のアプリケーションに対して自動的にイメージをビルドする機能がある、generator コンポーネントを提供します。Fuse on OpenShift の場合、以下のジェネレータータイプがサポートされます。

ジェネレーターフレームワークは、アプリケーションプロジェクトの特性に応じて、必要なビルドタイプを自動検出し、適切なジェネレーターコンポーネントを呼び出します。

注記

Fabric8 Maven プラグインのオープンソースコミュニティーバージョンは、追加のジェネレータータイプを提供しますが、これらのタイプは Fuse on OpenShift 製品ではサポートされません。

C.4.1. Zero-Configuration

ジェネレーターには設定が必要ありません。ジェネレーターはデフォルトで有効になり、Fabric8 Maven プラグインが呼び出されると自動的にデフォルト設定で実行されます。しかし、必要な場合はジェネレーターの設定を簡単にカスタマイズできます。

C.4.2. ベースイメージを指定するモード

Fuse on OpenShift では、アプリケーションビルドのベースイメージは Java イメージ (Spring Boot アプリケーションの場合) または Karaf イメージ (Karaf アプリケーションの場合) のいずれかになります。Fabric8 Maven プラグインは、ベースイメージの指定に以下のモードをサポートします。

istag

(デフォルト): image stream は、OpenShift イメージストリームからタグ付けされたイメージを選択して動作します。この場合、ベースイメージは以下の形式で指定されます。

<namespace>/<image-stream-name>:<tag>

<namespace> は、イメージストリームが定義される OpenShift プロジェクトの名前に置き換えます (通常は openshift)。<image-stream-name> はイメージストリームの名前に置き換えます。<tag> はストリームの特定のイメージを識別します (またはストリームの最新イメージを追跡します)。

docker

docker モードは、イメージレジストリーから特定の Docker 形式イメージを選択して動作します。ベースイメージは直接リモートレジストリーから取得されるため、イメージストリームは必要ありません。この場合、ベースイメージは以下の形式で指定されます。

[<registry-location-url>/]<image-namespace>/<image-name>:<tag>

イメージ指定子は 任意で リモートイメージレジストリーの URL である <registry-location-url> で始まり、イメージ namespace <image-namespace>、イメージ名 <image-name>、およびタグ <tag> が続きます。

注記

オープンソースコミュニティーバージョンの fabric8-maven-plugin のデフォルト操作は Red Hat の製品化バージョンとは異なります。たとえば、コミュニティーバージョンのデフォルトモードは docker です。

C.4.2.1. istag モードのデフォルト値

デフォルトである istag モードが選択されている場合、Fabric8 Maven プラグインは以下のデフォルトイメージ指定子を使用して Fuse イメージを選択します (形式は <namespace>/<image-stream-name>:<tag> です)。

fuse7/fuse-eap-openshift:1.3
fuse7/fuse-java-openshift:1.3
fuse7/fuse-karaf-openshift:1.3

注記

Fuse イメージストリームでは、個別のイメージに 1.0-1 や 1.0-2 などのビルド番号がタグ付けされます。常に最新のイメージを追跡するよう、1.0 タグが設定されます。

C.4.2.2. docker モードのデフォルト値

docker モードが選択され、registry.redhat.io にアクセスするよう OpenShift 環境が設定されていることを仮定する場合、Fabric8 Maven プラグインは以下のデフォルトイメージ指定子を使用して Fuse イメージを選択します (形式は <image-namespace>/<image-name>:<tag> です)。

fuse7/fuse-eap-openshift:1.3
fuse7/fuse-java-openshift:1.3
fuse7/fuse-karaf-openshift:1.3

C.4.2.3. Spring Boot アプリケーションのモード設定

Spring Boot アプリケーションのビルドに使用されるモード設定とベースイメージの場所をカスタマイズするには、以下の形式で configuration 要素をアプリケーションの pom.xml ファイルにある fabric8-maven-plugin 設定に追加します。

<configuration>
  <generator>
    <config>
      <spring-boot>
        <fromMode>{istag|docker}</fromMode>
        <from>{image locations}</from>
      </spring-boot>
    </config>
  </generator>
</configuration>

C.4.2.4. Karaf アプリケーションのモード設定

Karaf アプリケーションのビルドに使用されるモード設定とベースイメージの場所をカスタマイズするには、以下の形式で configuration 要素をアプリケーションの pom.xml ファイルにある fabric8-maven-plugin 設定に追加します。

<configuration>
  <generator>
    <config>
      <karaf>
        <fromMode>{istag|docker}</fromMode>
        <from>{image locations}</from>
      </karaf>
    </config>
  </generator>
</configuration>

C.4.2.5. コマンドラインにおけるモードの指定

pom.xml ファイルで直接モードの設定をカスタマイズする代わりに、以下のプロパティー設定をコマンドライン呼び出しに追加し、モードの設定を直接 mvn コマンドに渡すことができます。

//build from Docker-formatted image directly, registry location, image name or tag are subject to change if desirable
-Dfabric8.generator.fromMode=docker
-Dfabric8.generator.from=<custom-registry-location-url>/<image-namespace>/<image-name>:<tag>

//to use ImageStream from different namespace
-Dfabric8.generator.fromMode=istag //istag is default
-Dfabric8.generator.from=<namespace>/<image-stream-name>:<tag>

C.4.3. Spring Boot

Spring Boot ジェネレーターは、pom.xml ファイルで spring-boot-maven-plugin を見つけるとアクティベートされます。生成されたコンテナーポートは server.port プロパティーの application.properties から読み取られ、見つからない場合はデフォルトで 8080 になります。

このジェネレーターは一般的なジェネレーターオプションの他に、以下のオプションで設定することができます。

表C.4 Spring Boot 設定オプション
要素	説明	デフォルト
assemblyRef	アセンブリーへの参照が指定されている場合は、含めるアーティファクトの検出を行わずに使用されます。
targetDir	検出されたアーティファクトが配置される生成されたイメージ内のディレクトリー。ベースイメージも変更された場合のみ変更します。	`/deployments`
jolokiaPort	ベースイメージによって公開される Jolokia エージェントのポート。Jolokia ポートを公開したくない場合はこれを０に設定します。	8778
mainClass	呼び出すメインクラス。指定のない場合は次のようにジェネレーターがメインクラスを検索します。最初に、fat-jar を検出するためにチェックが実行されます。次に、`main` メソッドを持つ単一のクラスを探すために `target/classes` ディレクトリーがスキャンされます。何も見つからなかった場合や複数のクラスが見つかった場合は、ジェネレーターは何もしません。
webPort	サービスとして公開するポート。Web アプリケーションのポートであるはずです。ポートを公開しない場合はこれを０に設定します。	8080
color	設定されている場合、Spring Boot のコンソール出力で色を強制的に使用します。

ジェネレーターは、application.properties から読み取られた管理またはサーバーポートのいずれかを示す Kubernetes の liveness および readiness probe を追加します。server.ssl.key-store プロパティーが application.properties に設定されている場合、probe は https を使用するよう自動的に設定されます。

C.4.4. Karaf

Karaf ジェネレーターは、pom.xml ファイルで karaf-maven-plugin を見つけるとアクティベートされます。