Dekorate: JavaプロジェクトのためのKubernetesとOpenShiftのマニフェストの生成

原文(投稿日：2020/06/05)へのリンク

Dekorate, (旧 ap4k プロジェクト) は、Java ベースのプロジェクトで Kubernetes や OpenShift のマニフェストを簡単に生成できるように設計されている。アノテーションを使用せずにKubernetesのマニフェストを飾ることをサポートするようになったため、プロジェクトはリブランドされた。ですが、ap4kという名前はもはやプロジェクトを正確に説明していない。

Dekorateは、KubernetesとOpenShiftマニフェスト用のデコレータとJavaコンパイル時ジェネレータのコレクションだ。開発者は、これらのマニフェストをカスタマイズするために XML、JSON、YAML を編集する必要はない。

Dekorateを使用すると、開発者はアノテーション処理、設定プロパティ（application.properties）、またはその両方を使用してマニフェストを生成したり、カスタマイズできる。DekorateはKubernetes、OpenShift、Knative、Tekton、Prometheus、Jaeger、Service Catalog、Halkyon CRDをサポートしている。さらに、Dekorateは、Spring Boot、Quarkus、Thorntailのようなフレームワークと統合されており、一般的なJavaプロジェクトのためのビルドツールも提供しているので、どんなmaven、gradle、sbt、bazelプロジェクトでもマニフェストを生成できる。

例として、DekorateがどのようにQuarkusアプリケーションと統合されているかを見てみよう。

QuarkusにはすでにKubernetes拡張機能があり、内部的にはDekorateを使用してKubernetes、OpenShift、Knative用のマニフェストの生成とカスタマイズを行っている。この拡張機能により、Quarkusは生成されたマニフェストを適用してアプリケーションをKubernetesクラスタにデプロイしたり、コンテナイメージを作成してアプリケーションをデプロイする前にレジストリにプッシュできる（詳細はコンテナイメージガイドを参照）。

その拡張機能を追加するには、ターミナルで実行するだけだ。

mvn quarkus:add-extension -Dextensions="io.quarkus:quarkus-kubernetes"

コンパイルが終了すると、生成されたマニフェストは次の場所で利用可能になる: target/kubernetes/.

kubernetes.jsonファイルはこのような感じだ。

{
  "apiVersion" : "v1",
  "kind" : "ServiceAccount",
  "metadata" : {
    "annotations" : {
      "app.quarkus.io/vcs-url" : "<>",
      "app.quarkus.io/build-timestamp" : "2020-06-04 - 05:13:57 +0000",
      "app.quarkus.io/commit-id" : "<>"
    },
    "labels" : {
      "app.kubernetes.io/name" : "decorate",
      "app.kubernetes.io/version" : "1.0.0-SNAPSHOT"
    },
    "name" : "decorate"
  }
}

そして、この拡張機能はポートやヘルスチェックのようなものを、ユーザ側からの設定せずに処理する。設計上、この拡張機能は生成されたマニフェストをカスタマイズするために dekorate アノテーションを使用しないことに注意することが重要だ。

Spring Bootアプリケーションの場合、Kubernetes用のio.dekorate:kubernetes-spring-starter:1.0.0とOpenShift用のio.dekorate:openshift-spring-starter:1.0.0の2つのスターターが用意されている。

Spring Bootでは、既存のフレームワーク固有のメタデータを利用することで、アノテーションを回避できる。生成されたマニフェストをカスタマイズするには、dekorateプロパティをapplication.yml/application.propertiesに追加したり、application.yml/application.propertiesと一緒にアノテーションを使用できる。デフォルトでは、dekorateプロパティは既存のアノテーション設定をすべて上書く。

Dekorateは、以下のようにサポートされている設定を優先度の高い順に探す。

1. アノテーション
2. application.properties
3. application.yaml
4. application.yml
5. application-kubernetes.properties
6. application-kubernetes.yaml
7. application-kubernetes.yml

Thorntailアプリケーションには、Kubernetes用のio.dekorate:kubernetes-thorntail-starter:jar:1.0.0、OpenShift用のio.dekorate:openshift-thorntail-starter:jar:1.0.0の2つのスターターが用意されている。

これらのスターターから、@KubernetesApplication、@OpenShiftApplicationなどのDekorateアノテーションを使い始められる。

汎用Javaアプリケーション用のKubernetesマニフェストを生成するには、Kubernetesの場合はio.dekorate:kubernetes-annotations:jar:1.0.0、OpenShiftの場合はio.dekorate:openshit-annotations:jar:1.0.0という依存関係を追加する必要がある。

そして、@Dekorateアノテーションを追加する必要がある。もしくは、@KubernetesApplication。それはJavaソースファイルの1つに@Dekorateのより特殊な形だ。

import io.dekorate.kubernetes.annotation.KubernetesApplication;
 
@KubernetesApplication
public class Main {
    public static void main(String[] args) {
    }
}

mvn clean packageを実行した後、target/classes/META-INF/decorateの下に生成されたマニフェストがあるだろう。

Kubernetes.ymlは以下のようになる。

apiVersion: "apps/v1"
kind: "Deployment"
metadata:
  name: "kubernetes-example"
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: "my-gradle-app"
      app.kubernetes.io/version: "1.0-SNAPSHOT"
  template:
    metadata:
      labels:
        app.kubernetes.io/name: "my-gradle-app"
        app.kubernetes.io/version: "1.0-SNAPSHOT"
    spec:
      containers:
      - env:
        - name: "KUBERNETES_NAMESPACE"
          valueFrom:
            fieldRef:
              fieldPath: "metadata.namespace"
        image: "default/my-gradle-app:1.0-SNAPSHOT"
        imagePullPolicy: "IfNotPresent"
        name: "my-gradle-app"

一般的なJavaアプリケーション用のOpenShiftマニフェストを生成するには、@Dekorateアノテーション、または@OpenshiftApplicationを使用することができるが、これは@KubernetesApplicationと全く同じように動作するが、代わりにopenshift.yml/openshift.jsonを生成する。

Dekorateは、コアとなるマニフェスト生成機能とは別に、いくつかの追加機能をもたらす。これらの機能には、ビルド、デプロイ、テストなどが含まれる。

Dekorateはコンパイル終了後にコンテナイメージのビルドをトリガーするために外部ツール(例えばdockerやoc)をフックできる。DekorateはDockerファイルを生成しないが、dockerやs2iビルドを実行するための内部サポートも提供していない。

今のところ、実験的な機能として、以下のようなフックが用意されている。

• docker ビルドフック (docker バイナリが必要。 -Ddekorate.build=true でトリガーされる)
• docker プッシュフック (docker バイナリが必要。 -Ddekorate.push=true でトリガーされる)
• OpenShift s2i ビルドフック (oc バイナリを必要。-Ddekorate.deploy=true でトリガーされる)

Dekorateはまた、KubernetesとOpenshift用のJUnit 5拡張機能を提供する。これは開発者がエンドツーエンドのテストを実行できる。現時点でサポートされている機能は、環境条件、コンテナビルド、生成されたマニフェストを適用して環境をテストすること、クライアント/アプリケーションポッドでテストを注入することだ。

すべての設定オプションやコード例 (Spring Boot, Thorntail, Vertx, Istio) などの詳細は、GitHub リポジトリ を参照。