OAMを使用したアプリケーションの開発およびデプロイ

前提条件

  • Verrazzanoがインストールされている既存のKubernetesクラスタへのアクセス。
  • GitHubコンテナ・レジストリ内のアプリケーションのイメージへのアクセス。
    次のコマンドを使用して、サンプルのDockerイメージをプルしてアクセスを確認します: 
    $ docker pull ghcr.io/verrazzano/example-helidon-greet-app-v1:0.1.12-1-20210218160249-d8db8f3

アプリケーション開発

この項では、JavaおよびHelidonで記述されたサンプル・アプリケーションを使用します。実装の詳細は、Helidon MPチュートリアルを参照してください。Verrazzanoのサンプル・リポジトリのアプリケーションのソース・コードを参照してください。

サンプル・アプリケーションはJAX-RSサービスで、次のRESTエンドポイントを実装します:

  • /greet - メモリーに格納されているデフォルトのグリーティング・メッセージを返します。このエンドポイントは、GET HTTPリクエスト・メソッドを受け入れます。
  • /greet/{name} - パス・パラメータで指定されている名前を含むグリーティング・メッセージを返します。このエンドポイントは、GET HTTPリクエスト・メソッドを受け入れます。
  • /greet/greeting - 他のエンドポイントへの今後のコールで使用されるグリーティング・メッセージを変更します。このエンドポイントは、PUT HTTPリクエスト・メソッドとJSONペイロードを受け入れます。

次のコードは、アプリケーションの実装の一部を示しています。Verrazzanoのサンプル・リポジトリには、完全な実装が含まれています。ここで重要な詳細は、/greetパスで公開される単一のリソースがアプリケーションに含まれていることです。

package io.helidon.examples.quickstart.mp;
...
@Path("/greet")
@RequestScoped
public class GreetResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public JsonObject getDefaultMessage() {
        ...
    }

    @Path("/{name}")
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public JsonObject getMessage(@PathParam("name") String name) {
        ...
    }

    @Path("/greeting")
    @PUT
    @Consumes(MediaType.APPLICATION_JSON)
    ...
    public Response updateGreeting(JsonObject jsonObject) {
        ...
    }

}

Dockerfileは、完了したアプリケーションJARファイルをDockerイメージにパッケージ化するために使用されます。次のコードは、Dockerfileの一部を示しています。Verrazzanoのサンプル・リポジトリには、完全なDockerfileが含まれています。Dockerコンテナは単一のポート8080を公開することに注意してください。

FROM ghcr.io/oracle/oraclelinux:7-slim
...
CMD java -cp /app/helidon-quickstart-mp.jar:/app/* io.helidon.examples.quickstart.mp.Main
EXPOSE 8080

アプリケーション・デプロイメント

Verrazzanoを使用してアプリケーションをデプロイすると、プラットフォームによって、サービス・メッシュに接続、ネットワーク・ポリシーおよびイングレスが設定され、モニタリング・スタックが準備されてメトリック、ログおよびトレースが取得されます。Verrazzanoでは、OAMコンポーネントを採用してシステムの機能ユニットを定義します。その後、関連するアプリケーション構成を定義することによって、システムの機能ユニットがアセンブルおよび構成されます。

Verrazzanoコンポーネント

Verrazzano OAMコンポーネントは、アプリケーションの一般的な構成および環境要件を示すKubernetesカスタム・リソースです。次のコードは、このガイドで使用されるサンプル・アプリケーションのコンポーネントを示しています。このリソースは、単一のエンドポイントを公開するHelidonアプリケーションを含む単一のDockerイメージによって実装されるコンポーネントを表しています。

apiVersion: core.oam.dev/v1alpha2
kind: Component
metadata:
  name: hello-helidon-component
  namespace: hello-helidon
spec:
  workload:
    apiVersion: oam.verrazzano.io/v1alpha1
    kind: VerrazzanoHelidonWorkload
    metadata:
      name: hello-helidon-workload
      labels:
        app: hello-helidon
    spec:
      deploymentTemplate:
        metadata:
          name: hello-helidon-deployment
        podSpec:
          containers:
            - name: hello-helidon-container
              image: "ghcr.io/verrazzano/example-helidon-greet-app-v1:0.1.10-3-20201016220428-56fb4d4"
              ports:
                - containerPort: 8080
                  name: http

コンポーネントの各フィールドの簡単な説明:

  • apiVersion - コンポーネント・カスタム・リソース定義のバージョン
  • kind - コンポーネント・カスタム・リソース定義の標準名
  • metadata.name - コンポーネントのカスタム・リソースの作成に使用される名前
  • metadata.namespace - このコンポーネントのカスタム・リソースの作成に使用されるネームスペース
  • spec.workload.kind - VerrazzanoHelidonWorkloadは、Kubernetesのステートレス・ワークロードを定義します
  • spec.workload.spec.deploymentTemplate.podSpec.metadata.name - Kubernetesのステートレス・ワークロードの作成に使用される名前
  • spec.workload.spec.deploymentTemplate.podSpec.containers - 実装コンテナ
  • spec.workload.spec.deploymentTemplate.podSpec.containers.ports - コンテナによって公開されるポート

Verrazzanoアプリケーション構成

Verrazzanoアプリケーション構成は、環境固有のカスタマイズを提供するKubernetesカスタム・リソースです。次のコードは、このガイドで使用されているサンプルのアプリケーション構成を示しています。このリソースは、hello-helidonネームスペースへのアプリケーションのデプロイを指定します。追加のランタイム機能は、トレイトを使用するか、ワークロードを補強するランタイム・オーバーレイを使用して指定します。たとえば、イングレス・トレイトはイングレス・ホストおよびパスを指定し、メトリック・トレイトは、オプションで、アプリケーション関連メトリックの取得に使用されるPrometheusスクレイパを提供します。メトリック・トレイトが指定されていない場合は、Verrazzano提供のPrometheusコンポーネントがデフォルトで使用されます。 

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: hello-helidon-appconf
  namespace: hello-helidon
  annotations:
    version: v1.0.0
    description: "Hello Helidon application"
spec:
  components:
    - componentName: hello-helidon-component
      traits:
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: MetricsTrait
            spec:
              scraper: <optionally specify custom scraper>
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: IngressTrait
            metadata:
              name: hello-helidon-ingress
            spec:
              rules:
                - paths:
                    - path: "/greet"
                      pathType: Prefix

アプリケーション構成の各フィールドの簡単な説明:

  • apiVersion - ApplicationConfigurationカスタム・リソース定義のバージョン
  • kind - アプリケーション構成カスタム・リソース定義の標準名
  • metadata.name - このアプリケーション構成リソースの作成に使用される名前
  • metadata.namespace - このアプリケーション構成カスタム・リソースに使用されるネームスペース
  • spec.components - ランタイム構成を指定するために利用されるアプリケーションのコンポーネントへの参照
  • spec.components[].traits - アプリケーションのコンポーネントに指定されたトレイト

トレイトについて知るために、イングレス・トレイトのフィールドを確認します:

  • apiVersion - OAMトレイト・カスタム・リソース定義のバージョン
  • kind - IngressTraitは、OAMアプリケーションのイングレス・トレイト・カスタム・リソース定義の名前です
  • spec.rules.paths - アプリケーションにアクセスするためのコンテキスト・パス

アプリケーションのデプロイ

サンプル・アプリケーションをデプロイするには、次のステップが必要です。applyステップと同様のステップを使用して、アプリケーションをVerrazzanoにデプロイします。

  1. サンプル・アプリケーションのネームスペースを作成し、ネームスペースがVerrazzanoによって管理され、Istioが有効化されることを示すラベルを追加します。 

    $ kubectl create namespace hello-helidon
$ kubectl label namespace hello-helidon verrazzano-managed=true istio-injection=enabled

  2. アプリケーションのコンポーネントを適用します。 

    $ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.7.2/examples/hello-helidon/hello-helidon-comp.yaml -n hello-helidon

    このステップにより、Componentリソースの検証および作成が行われます。その結果、他のリソースやオブジェクトは作成されません。将来適用されるアプリケーション構成は、このComponentリソースを参照できます。

  3. アプリケーション構成を適用します。 

    $ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.7.2/examples/hello-helidon/hello-helidon-app.yaml -n hello-helidon

    このステップにより、アプリケーション構成リソースの検証および作成が行われます。この操作によって、複数のVerrazzanoオペレータのアクティブ化がトリガーされます。これらのオペレータは、共同してアプリケーションを提供およびサポートする他のKubernetesオブジェクト(Deployment、ReplicaSet、Pod、Service、Ingressなど)を作成します。

  4. アプリケーションのDNS解決を構成します。

    アプリケーションのデプロイ後、アプリケーションのイングレスDNS名をアプリケーションのロード・バランサIPアドレスに解決するようにDNSを構成します。生成されたホスト名は、Kubernetesにゲートウェイを問い合せることで取得されます: 

    $ kubectl get gateways.networking.istio.io hello-helidon-hello-helidon-gw \
    -n hello-helidon \
    -o jsonpath='{.spec.servers[0].hosts[0]}'

    ロード・バランサIPは、KubernetesにIstioイングレス・ゲートウェイのステータスを問い合せることで取得されます: 

    $ kubectl get service \
    -n istio-system istio-ingressgateway \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

    DNS構成ステップは、このガイドの対象外です。構成および使用できるDNSインフラストラクチャについては、Oracle Cloud Infrastructure DNSのドキュメントを参照してください。一部の本番以外のシナリオでは、/etc/hostsまたは同等のものを使用したDNS構成で十分な場合があります。

デプロイメントの検証

アプリケーション構成を適用すると、複数のKubernetesオブジェクトの作成が開始されます。これらのオブジェクトの実際の作成および初期化は非同期に行われます。次のステップでは、これらのオブジェクトの使用準備が完了しているかどうかを判断するためのコマンドを示します。

ノート: サンプル・アプリケーションに関連しない他の多くのKubernetesオブジェクトが存在する場合もあります。それらはリストから省略されています。

  1. Helidonアプリケーション・ポッドが実行中であることを確認します。 

    $ kubectl get pods -n hello-helidon -l app=hello-helidon

# Sample output
NAME                                        READY   STATUS    RESTARTS   AGE
hello-helidon-deployment-8664954995-wcb9d   2/2     Running   0          5m5s

  2. Verrazzanoアプリケーション・オペレータ・ポッドが実行中であることを確認します。 

    $ kubectl get pod -n verrazzano-system -l app=verrazzano-application-operator

# Sample output
NAME                                               READY   STATUS    RESTARTS   AGE
verrazzano-application-operator-79849b89ff-lr9w6   1/1     Running   0          13m

    ネームスペースverrazzano-systemは、Verrazzanoによって管理される非アプリケーション・オブジェクトに対してVerrazzanoで使用されます。単一のverrazzano-application-operatorは、クラスタ内のすべてのOAMベースのアプリケーションのライフサイクルを管理します。

  3. Verrazzanoロギングおよびモニタリング・インフラストラクチャが実行中であることを確認します。 

    $ kubectl get pods -n verrazzano-system | grep '^NAME\|vmi-system'

# Sample output
NAME                                               READY   STATUS    RESTARTS   AGE
vmi-system-grafana-799d79648d-wsdp4                2/2     Running   0          47m
vmi-system-kiali-574c6dd94d-f49jv                  2/2     Running   0          51m

    $ kubectl get pods -n verrazzano-logging

# Sample output
NAME                                                      READY   STATUS      RESTARTS      AGE
opensearch-dashboards-56d845466c-9xsrv                    1/1     Running     0             2h
opensearch-es-master-0                                    1/1     Running     0             1h
opensearch-operator-controller-manager-5c498865fc-27jr5   1/1     Running     0             2h
opensearch-securityconfig-update-jj2xv                    0/1     Completed   0             2h

    $ kubectl get pods -n verrazzano-monitoring

# Sample output
NAME                                                   READY   STATUS    RESTARTS   AGE
prometheus-node-exporter-fstc7                         1/1     Running   0          14h
prometheus-operator-kube-p-operator-857fb66b74-szv4h   1/1     Running   0          14h
prometheus-prometheus-operator-kube-p-prometheus-0     3/3     Running   0          14h

    verrazzano-system、verrazzano-loggingおよびverrazzano-monitoringネームスペース内のこれらのポッドは、デプロイされたアプリケーション向けにVerrazzano社が作成したロギングおよびモニタリング・スタックを構成します。

    ロギングおよびモニタリング・インフラストラクチャは、次の複数のコンポーネントで構成されます:

    • opensearch-es - ログ収集用のOpenSearch
    • vmi-system-grafana - メトリック・ビジュアライゼーションのためのGrafana
    • vms-system-kiali - istioサービス・メッシュの管理コンソールのためのKiali
    • opensearch-dashboards - ログ・ビジュアライゼーション用のOpenSearchダッシュボード
    • prometheus-prometheus-operator-kube-p-prometheus - メトリック収集のためのPrometheus

  4. 障害を診断します。

    5分など、適切な長さの時間内にRunning状態になっていないポッドのイベント・ログを表示します。 

    $ kubectl describe pod -n hello-helidon -l app=hello-helidon

    調査するポッドの特定のネームスペースおよび名前を使用します。

アプリケーションの探索

アプリケーションの機能を確認するには、次のステップに従います。DNSが構成されていない場合は、代替コマンドを使用します。

  1. 後で使用できるようにアプリケーションのRESTサービス・エンドポイントを公開するロード・バランサのホスト名およびIPアドレスを保存します。 

     $ HOST=$(kubectl get gateways.networking.istio.io hello-helidon-hello-helidon-gw \
       -n hello-helidon \
       -o jsonpath='{.spec.servers[0].hosts[0]}')
 $ ADDRESS=$(kubectl get service \
       -n istio-system istio-ingressgateway \
       -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

    ノート:

    • ADDRESSの値は、DNSが構成されていない場合のみ使用されます。
    • 次の代替コマンドは、HTTP Hostヘッダーを検証するファイアウォールと連携できない場合があります。

  2. デフォルトのメッセージを取得します。 

      $ curl -sk \
      -X GET \
      "https://${HOST}/greet"

  # Expected response
  {"message":"Hello World!"}

    DNSが構成されていない場合は、次のコマンドを使用します。

  $ curl -sk \
      -X GET \
      "https://${HOST}/greet" \
      --resolve ${HOST}:443:${ADDRESS}

  1. Robertに対するメッセージを取得します。 

      $ curl -sk \
      -X GET \
      "https://${HOST}/greet/Robert"

  # Expected response
  {"message":"Hello Robert!"}
  ```
  If DNS has not been configured, then use this command.
  ```
  $ curl -sk \
      -X GET
      "https://${HOST}/greet/Robert" \
      --resolve ${HOST}:443:${ADDRESS}

  2. デフォルトのグリーティングを更新します。 

      $ curl -sk \
      -X PUT \
      "https://${HOST}/greet/greeting" \
      -H 'Content-Type: application/json' \
      -d '{"greeting" : "Greetings"}'

    DNSが構成されていない場合は、次のコマンドを使用します。 

      $ curl -sk \
      -X PUT \
      "https://${HOST}/greet/greeting" \
      -H 'Content-Type: application/json' \
      -d '{"greeting" : "Greetings"}' \
      --resolve ${HOST}:443:${ADDRESS}

  3. Robertに対する新しいメッセージを取得します。 

      $ curl -sk \
      -X GET \
      "https://${HOST}/greet/Robert"

  # Expected response
  {"message":"Greetings Robert!"}

    DNSが構成されていない場合は、次のコマンドを使用します。 

      $ curl -sk \
      -X GET \
      "https://${HOST}/greet/Robert" \
      --resolve ${HOST}:443:${ADDRESS}

アプリケーションのログへのアクセス

デプロイされたアプリケーションではログ収集が有効になっています。これらのログはOpenSearchを使用して収集され、OpenSearchダッシュボードを使用してアクセスできます。OpenSearchとOpenSearchダッシュボードは、アプリケーション構成の適用の結果としてアプリケーションをサポートするためにVerrazzanoが作成するインフラストラクチャの例です。索引パターンの作成およびOpenSearchで収集されたログ・データのビジュアル化の詳細は、「OpenSearchダッシュボード」を参照してください。

OpenSearchダッシュボードにアクセスするためのURLを決定します: 

$ OSD_HOST=$(kubectl get ingress \
     -n verrazzano-system opensearch-dashboards \
     -o jsonpath='{.spec.rules[0].host}')
$ OSD_URL="https://${OSD_HOST}"
$ echo "${OSD_URL}"
$ open "${OSD_URL}"

OpenSearchダッシュボードにアクセスするユーザー名は、Verrazzanoのインストール時にデフォルトでverrazzanoに設定されます。

OpenSearchダッシュボードにアクセスするためのパスワードを決定します: 

$ echo $(kubectl get secret \
      -n verrazzano-system verrazzano \
      -o jsonpath={.data.password} | base64 \
      --decode)

アプリケーションのメトリックへのアクセス

デプロイされたアプリケーションではメトリック収集が有効になっています。Grafanaを使用して、Prometheusによって収集されたこれらのメトリックにアクセスできます。PrometheusとGrafanaは、アプリケーション構成を適用した結果、Verrazzanoが作成する追加のコンポーネントです。Prometheusメトリック・データのビジュアル化の詳細は、Grafanaを参照してください。

GrafanaにアクセスするためのURLを決定します: 

$ GRAFANA_HOST=$(kubectl get ingress \
      -n verrazzano-system vmi-system-grafana \
      -o jsonpath='{.spec.rules[0].host}')
$ GRAFANA_URL="https://${GRAFANA_HOST}"
$ echo "${GRAFANA_URL}"
$ open "${GRAFANA_URL}"

Grafanaにアクセスするためのユーザー名は、Verrazzanoのインストール時にデフォルト値verrazzanoに設定されます。

Grafanaにアクセスするためのパスワードを確認します: 

$ echo $(kubectl get secret \
      -n verrazzano-system verrazzano \
      -o jsonpath={.data.password} | base64 \
      --decode)

または、Prometheusを使用してメトリックに直接アクセスできます。このアクセスのためのURLを決定します: 

$ PROMETHEUS_HOST=$(kubectl get ingress \
      -n verrazzano-system vmi-system-prometheus \
      -o jsonpath='{.spec.rules[0].host}')
$ PROMETHEUS_URL="https://${PROMETHEUS_HOST}"
$ echo "${PROMETHEUS_URL}"
$ open "${PROMETHEUS_URL}"

PrometheusとGrafanaの両方のユーザー名とパスワードは同じです。

Kialiコンソールの警告の抑制

一部のアプリケーションでは、Kialiコンソールに、複数のIngressTraitにわたってホスト名/ポート構成をレプリケートするVirtualServiceおよびGatewayオブジェクトに対する警告が表示される場合があります。これらの警告は機能に影響せず、次のコンポーネント・オーバーライドを使用して抑制できます: 

kiali:
  overrides:
    - values:
        kiali_feature_flags:
          validations:
            ignore: ["KIA1106", "KIA0301"]

アプリケーションの削除

次のコマンドを実行して、アプリケーション構成を削除し、オプションでコンポーネントとネームスペースを削除します。

  1. アプリケーション構成を削除します。 

    $ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.7.2/examples/hello-helidon/hello-helidon-app.yaml

    アプリケーション構成を削除すると、アプリケーション固有のすべてのKubernetesオブジェクトが破棄されます。

  2. (オプション)アプリケーションのコンポーネントを削除します。 

    $ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.7.2/examples/hello-helidon/hello-helidon-comp.yaml

    ノート: このコンポーネントの他のアプリケーション構成が将来適用される場合、このステップは不要です。

  3. (オプション)ネームスペースを削除します。 

    $ kubectl delete namespace hello-helidon