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にデプロイします。
-
サンプル・アプリケーションのネームスペースを作成し、ネームスペースがVerrazzanoによって管理され、Istioが有効化されることを示すラベルを追加します。
$ kubectl create namespace hello-helidon $ kubectl label namespace hello-helidon verrazzano-managed=true istio-injection=enabled
-
アプリケーションのコンポーネントを適用します。
$ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.6.11/examples/hello-helidon/hello-helidon-comp.yaml -n hello-helidon
このステップにより、Componentリソースの検証および作成が行われます。その結果、他のリソースやオブジェクトは作成されません。将来適用されるアプリケーション構成は、このComponentリソースを参照できます。
-
アプリケーション構成を適用します。
$ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.6.11/examples/hello-helidon/hello-helidon-app.yaml -n hello-helidon
このステップにより、アプリケーション構成リソースの検証および作成が行われます。この操作によって、複数のVerrazzanoオペレータのアクティブ化がトリガーされます。これらのオペレータは、共同してアプリケーションを提供およびサポートする他のKubernetesオブジェクト(Deployment、ReplicaSet、Pod、Service、Ingressなど)を作成します。
-
アプリケーションの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オブジェクトが存在する場合もあります。それらはリストから省略されています。
-
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
-
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ベースのアプリケーションのライフサイクルを管理します。 -
Verrazzanoモニタリング・インフラストラクチャが実行中であることを確認します。
$ kubectl get pods -n verrazzano-system | grep '^NAME\|vmi-system' # Sample output NAME READY STATUS RESTARTS AGE vmi-system-es-master-0 2/2 Running 0 47m vmi-system-grafana-799d79648d-wsdp4 2/2 Running 0 47m vmi-system-kiali-574c6dd94d-f49jv 2/2 Running 0 51m vmi-system-osd-77f8d998f4-zzvqr 2/2 Running 0 47m
$ 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-monitoring
ネームスペース内のこれらのポッドは、Verrazzanoによって作成され、デプロイ済アプリケーション用のモニタリング・スタックを構成します。モニタリング・インフラストラクチャは、次の複数のコンポーネントで構成されます:
vmi-system-es
- ログ収集のためのOpenSearchvmi-system-grafana
- メトリック・ビジュアライゼーションのためのGrafanavms-system-kiali
-istio
サービス・メッシュの管理コンソールのためのKialivmi-system-osd
- ログ・ビジュアライゼーションのためのOpenSearchダッシュボードprometheus-prometheus-operator-kube-p-prometheus
- メトリック収集のためのPrometheus
-
障害を診断します。
5分など、適切な長さの時間内に
Running
状態になっていないポッドのイベント・ログを表示します。$ kubectl describe pod -n hello-helidon -l app=hello-helidon
調査するポッドの特定のネームスペースおよび名前を使用します。
アプリケーションの探索
アプリケーションの機能を確認するには、次のステップに従います。DNSが構成されていない場合は、代替コマンドを使用します。
-
後で使用できるようにアプリケーションの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
ヘッダーを検証するファイアウォールと連携できない場合があります。
-
デフォルトのメッセージを取得します。
$ curl -sk \ -X GET \ "https://${HOST}/greet" # Expected response {"message":"Hello World!"}
DNSが構成されていない場合は、次のコマンドを使用します。
$ curl -sk \
-X GET \
"https://${HOST}/greet" \
--resolve ${HOST}:443:${ADDRESS}
-
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}
-
デフォルトのグリーティングを更新します。
$ 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}
-
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 vmi-system-osd \
-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"]
アプリケーションの削除
次のコマンドを実行して、アプリケーション構成を削除し、オプションでコンポーネントとネームスペースを削除します。
-
アプリケーション構成を削除します。
$ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.6.11/examples/hello-helidon/hello-helidon-app.yaml
アプリケーション構成を削除すると、アプリケーション固有のすべてのKubernetesオブジェクトが破棄されます。
-
(オプション)アプリケーションのコンポーネントを削除します。
$ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.6.11/examples/hello-helidon/hello-helidon-comp.yaml
ノート: このコンポーネントの他のアプリケーション構成が将来適用される場合、このステップは不要です。
-
(オプション)ネームスペースを削除します。
$ kubectl delete namespace hello-helidon