新しい IBM Developer JP サイトへようこそ!サイトのデザインが一新され、旧 developerWorks のコンテンツも統合されました。 詳細はこちら

Appsody、OpenShift、Open Liberty を使用して、観測可能なマイクロサービスを構成する

編集者注: このチュートリアルは、Kabanero 0.6.0 および Red Hat OpenShift Container Platform 4.3 に対応するために 2020年4月9日に更新されました。

OpenShift と連動する Appsody Operator を使用すると、さまざまなランタイム・テンプレートを短時間で簡単にデプロイできます。これらのテンプレートによって作成されるシンプルな基本プロジェクト・ワークスペースは、開発の出発点として使用できるものです。

テンプレートのうちの 1 つとして、Open Liberty を利用した Java Open Liberty Appsody アプリケーション・スタックがあります。このテンプレートでは Eclipse MicroProfile 3.2 テクノロジーを使用してマイクロサービスを開発するため、可観測性を備えたマイクロサービスを開発するには理想的な基盤となります。

MicroProfile を採用する理由は何でしょう?それは、Eclipse MicroProfile 仕様には MicroProfile Metrics や MicroProfile Health などの重要な可観測性機能がすでに規定されているからです。MicroProfile Health 機能を使用すれば、サービスが自身の readiness ステータスと liveness ステータスを、それぞれのステータスに対応する 2 つのエンドポイントを介して報告できます。さらに MicroProfile Metrics 機能を使用すれば、ランタイムでエンドポイントを介してモニタリング対象のメトリックを追跡し、公開することが可能になります。

このチュートリアルでは、アプリケーション・デプロイメントをカスタマイズして、各種のモニタリング・ツールでヘルス・データとメトリック・データを取り込み視覚化する方法を紹介します。さらに、Open Liberty ランタイムの JSON ロギング機能を利用して、Kibana によってロギング・データを視覚化する方法についても説明します。

前提条件

このチュートリアルの手順に従うには、以下の前提条件を満たす必要があります。

  • Appsody をインストールする
  • Docker レジストリーにログインする
  • OpenShift クラスターにログインする
  • 以下のスタックを OpenShift クラスター上にデプロイする
    • Prometheus および Grafana スタック。このスタックを OpenShift クラスター上にデプロイする手順については、このドキュメントを参照してください。
    • Elasticsearch、Fluentd、Kibana (EFK) スタック。EFK スタックを OpenShift クラスター上にデプロイする手順については、このドキュメントを参照してください。

Prometheus を使用して Open Liberty から安全にメトリック・データを収集するには、開発チームと運用チームが協力して認証資格情報を構成する必要があります。このトピックについは、このチュートリアルのセクション「Open Liberty のセキュリティーを構成する」で詳しく説明します。

Java Open Liberty スタックをカスタマイズしてデプロイする

ローカル・システム上で、プロジェクトのディレクトリーとして使用する空のディレクトリーを作成します。Appsody はこのディレクトリーの名前をアプリケーション名として使用します。

空のプロジェクト・ディレクトリーから以下のコマンドを呼び出して、Java Open Liberty スタックを初期化します。

appsody init java-openliberty

これで、Java Open Liberty テンプレートがカレント・ディレクトリーにデプロイされたので、コードをカスタマイズする作業を開始できます。

java-openliberty スタックについて詳しくは、Appsody スタックの Github ページを参照してください。

OpenShift クラスター上に、Appsody アプリケーション・スタックのデプロイ先とするプロジェクト名前空間を作成する必要があります。以下のコードに、この名前空間を作成する方法が示されています。この例でプロジェクト名前空間として使用しているのは、appsody-application です。

oc new-project appsody-application

Open Liberty のセキュリティーを構成する

Java Open Liberty Appsody スタックにはローカル開発用の基本認証が構成されています。そのために使用されているのが、<appsody_project_directory>/src/main/liberty/config/configDropins/defaults に格納されている quick-start-security.xml 構成ファイル内の <quickStartSecurity> 要素です。デフォルトのユーザー名は admin で、パスワードは起動時に生成されます。

quick-start-security.xml 構成ファイルはローカル開発でのプロトタイピング専用なので、OpenShift にデプロイする場合は <appsody_project_directory>/src/main/liberty/config に格納されている server.xml 構成ファイル内に <quickStartSecurity> 要素を追加する必要があります。

運用チームがすでにユーザー名とパスワードを指定している場合は、server.xml 構成ファイル内の <quickStartSecurity> 属性を変更してユーザー名とパスワードを置き換えてください。独自のユーザー名とパスワードの値を構成することもできます。

以下のコードは、認証が指定された server.xml を示しています。

<server description="Liberty server">
    <featureManager>
        <feature>microProfile-3.2</feature>
    </featureManager>

    <quickStartSecurity userName="admin" userPassword="adminpwd"/>

    <httpEndpoint host="*" httpPort="${default.http.port}" httpsPort="${default.https.port}" id="defaultHttpEndpoint"/>

    <webApplication location="starter-app.war" contextRoot="/"/>
</server>

Open Liberty の JSON ロギングを有効にする

Open Liberty ランタイムは、ロギング・イベントを JSON 形式で標準出力/コンソールに送信することができます。ロギング・イベントが JSON 形式になっていれば、Elasticsearch、Fluentd、Kibana (EFK) などの強力なモニタリング・スタックで、データの取り込み、保管、視覚化をさらに効率化できます。

Open Liberty の JSON ロギング機能を有効にするには、目的とする構成値を含んだ bootstrap.properties ファイルを生成するように pom.xml を変更します。

例えば、次のようなコードになっているとします。

... 
    <bootstrapProperties>
       <default.http.port>${http.port}</default.http.port>
       <default.https.port>${https.port}</default.https.port>
       <app.context.root>${app.name}</app.context.root>
    </bootstrapProperties>
...

上記のコードを次のように変更します。

... 
    <bootstrapProperties>
       <default.http.port>${http.port}</default.http.port>
       <default.https.port>${https.port}</default.https.port>
       <app.context.root>${app.name}</app.context.root>
       <com.ibm.ws.logging.console.format>json</com.ibm.ws.logging.console.format>
       <com.ibm.ws.logging.console.source>message,trace,accessLog,ffdc,audit</com.ibm.ws.logging.console.source>
       <com.ibm.ws.logging.console.log.level>info</com.ibm.ws.logging.console.log.level>
       <com.ibm.ws.logging.message.format>json</com.ibm.ws.logging.message.format>
       <com.ibm.ws.logging.message.source></com.ibm.ws.logging.message.source>
       <com.ibm.ws.logging.trace.file.name>stdout</com.ibm.ws.logging.trace.file.name>
    </bootstrapProperties>
...

サーバーの起動時に、Open Liberty ランタイムによって上記の構成値が解釈され、コンソール に出力される以降のすべてのログは、これらの環境変数で定義されたソース を構成要素とすることになります。また、上記のスニペットで定義されている設定により、messages.logtrace.log への出力が無効化されます。

さらに、このガイドで使用する Kibana ダッシュボードの 1 つを使用して、HTTP エンドポイントが処理するインバウンドのクライアント・リクエストを視覚化するには、Open Liberty サーバー構成で accessLogging 機能を有効にする必要があります。それには、<appsody_project_directory>/src/main/liberty/config に格納されている server.xml 構成ファイル内に以下のコードを追加します。

... 
    <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="${default.http.port}" httpsPort="${default.https.port}">
        <accessLogging logFormat='%{R}W %h %u %t "%r" %s %b %D %{User-agent}i'/>
    </httpEndpoint>
...

以降のステップについては、「Open Liberty のログを分析する」を参照してください。

Open Liberty のロギング機能の構成について詳しくは、Open Liberty のロギングに関するドキュメントを参照してください。

Open Liberty のメトリックを有効にする

monitor-1.0 機能と mpMetrics-x.x 機能の両方が構成されている場合、Open Liberty ランタイムは追加のメトリックを追跡します。microProfile-3.2 機能によって、mpMetrics-2.2 機能が起動されます。

monitor-1.0 機能を構成するには、<appsody_project_directory>/src/main/liberty/config/server.xml 内に以下のコードを追加します。

server.xml のスニペット:

<featureManager>
   <feature>microProfile-3.2</feature>
   <feature>monitor-1.0</feature>
</featureManager>

まず、以下のコマンドを呼び出してローカルで Appsody アプリケーションをテストできます。

appsody run

/metrics エンドポイントに関するメトリックを確認するには、http://localhost:9080/metrics にアクセスします。 認証資格情報の入力を求められたら、前に構成したユーザー名とパスワードを入力します。

アプリケーションを OpenShift にデプロイする

Appsody アプリケーションが完成したので、Docker リポジトリーにログインしていることを確認してから、以下のコマンドを使用してアプリケーションを OpenShift クラスターにデプロイします。

appsody deploy -t demo-repo/java-openliberty-demo:latest --push --namespace appsody-application

このコードでは何が行われているのでしょうか?簡単に内容を見ていきましょう。

  • -t で、イメージにタグを付けます。
  • --push で、イメージを外部 Docker レジストリーにプッシュします。
  • --namespace で、OpenShift クラスターに対し、この Appsody アプリケーションのデプロイ先とする名前空間を指示します。
  • demo-repo は、サンプル・リポジトリーの名前です。実際のリポジトリーの名前で置き換えてください。
  • appsody-application は、プロジェクトの名前空間です。実際のプロジェクトの名前空間で置き換えてください。

デプロイ・プロセスの一環として、Appsody CLI により、Appsody Operator が指定の名前空間にデプロイ済みであるかどうかがチェックされ、必要に応じてデプロイされます。その後、Operator に合わせて Appsody アプリケーションのデプロイ・マニフェストが生成されて適用されます。これで、アプリケーションが OpenShift クラスターにデプロイされました。

ローカルのプロジェクト・ディレクトリー内には app-deploy.yaml という名前のファイルも生成されます。これが、OpenShift クラスター上にデプロイされる yaml ファイルです。このファイルの内容を更新して構成を追加した後、以下のコマンドを実行することでファイルを再適用できます。

oc apply -f app-deploy.yaml

Appsody Operator を使用して独自の Service Monitor をデプロイします。その方法については、この後のセクション「Service Monitor をデプロイする」を参照してください。

運用チームは、必要に応じて、特定のラベルが付いたデプロイメントをモニタリングするための Service Monitor を作成することもできます。その場合、運用チームと連絡をとって、対象のラベルのキーと値のペアを特定してください。Appsody Operator を使用して自分自身で Service Monitor をデプロイするとしたら、ラベルの突き合わせは自動的に処理されます。その場合は、使用するラベルを app-deploy.yaml に適用して再デプロイすることが必要になります。

例えば、Service Monitor で値 demo が設定されたラベル app を監視する場合は、以下のコードを使用します。

metadata:
  labels: 
    app: demo

Service Monitor をデプロイする

Service Monitor を OpenShift クラスターにデプロイするには、app-deploy.yaml を更新してから、このファイルを再適用します。これにより、開発者はアプリケーション・デプロイメントと Prometheus の接続をより直接的に制御できます。

以下の構成を追加します。

monitoring:
    endpoints:
    - basicAuth:
        password:
          key: password
          name: metrics-liberty
        username:
          key: username
          name: metrics-liberty
      interval: 10s
      tlsConfig:
        insecureSkipVerify: true
    labels:
      k8s-app: ''

Prometheus デプロイメントでは特定のラベルが付いた Service Monitors をモニタリングできます。上記の例で、Prometheus デプロイメントのモニタリング対象として設定しているのは、k8s-app というラベル付きの Service Monitor です。Prometheus デプロイメントでは、特定のラベルが付いた名前空間のみをモニタリングすることもできます。

Service Monitor や名前空間がモニタリングの対象となるよう、運用チームと連絡をとって必要なラベルを確認する必要があります。

basicAuth セクションで定義されているのは、/metrics エンドポイントにアクセスする際の認証に使用するユーザー名とパスワードです。

上記の例で使用されている metrics-liberty は、metrics-liberty という名前のシークレットへの参照です。このシークレットに、暗号化されたユーザー名とパスワードの値が含まれています。このシークレットは、開発者または運用チームのどちらでも作成できます。シークレットを作成する場所は、アプリケーション・デプロイメントおよび Service Monitor と同じプロジェクト名前空間でなければなりません。「Open Liberty のセキュリティーを構成する」を参照して、基礎となる Open Liberty ランタイムの認証セキュリティーをセットアップする方法を再確認してください。

以下のコードに、app-deploy.yaml 内の monitoring セクションが示されています。

apiVersion: appsody.dev/v1beta1
kind: AppsodyApplication
metadata:
  name: myAppsodyApplication
spec:
  # Add fields here
  version: 1.0.0
  applicationImage: demo-repo/java-openliberty-demo:latest
  stack: java-openliberty
  service:
    type: NodePort
    port: 9080
    annotations:
      prometheus.io/scrape: 'true'
  readinessProbe:
    failureThreshold: 12
    httpGet:
      path: /health/ready
      port: 9080
    initialDelaySeconds: 5
    periodSeconds: 2
  livenessProbe:
    failureThreshold: 12
    httpGet:
      path: /health/live
      port: 9080
    initialDelaySeconds: 5
    periodSeconds: 2
  monitoring:
    endpoints:
    - basicAuth:
        password:
          key: password
          name: metrics-liberty
        username:
          key: username
          name: metrics-liberty
      interval: 10s
      tlsConfig:
        insecureSkipVerify: true
    labels:
      k8s-app: ''
  expose: true
  createKnativeService: false

Open Liberty のログを分析する

Kibana ダッシュボードを使用してログを確認する

Open Liberty ランタイムが JSON 形式のログを出力するようになったので、EFK スタックを利用して、これらのロギング・イベントをモニタリングできます。Fluentd が JSON データを収集して Elasticsearch に送信します。データは Elasticsearch 内に保管されてインデックス付けされます。インデックス付けされたデータは、Kibana によって視覚化されます。

Open Liberty ランタイムからのイベントを視覚化するための Kibana ダッシュボードが用意されています。Liberty のロギング・イベントを分析するために作成された Kibana ダッシュボードは、ここから入手できます。

注: これらの Kibana ダッシュボードを使用するには、ロギング・イベントが JSON 形式で標準出力に送信されるようでなければなりません。まだ、そのように Open Liberty ランタイムを構成していない場合は、「Open Liberty の JSON ロギングを有効にする」を参照してください。

Kibana ダッシュボードをインポートする

Kibana ダッシュボードをインポートするには、以下の手順に従います。

  1. OpenShift Container Platform Web コンソールで、「Monitoring (モニタリング)」> 「Logging (ロギング)」にナビゲートして Kibana にアクセスします。

    公開されている Kibana ルートにアクセスする画面のスクリーンショット

  2. Kibana で、「Management (管理)」 > 「Saved Objects (保存済みオブジェクト)」にナビゲートして「Import (インポート) 」をクリックし、ファイル・システムを参照して目的のダッシュボードを見つけます。

    ダッシュボードをインポートする画面のスクリーンショット

  3. サイドバーで「Dashboards (ダッシュボード)」タブを選択すると、インポートされたダッシュボードを確認できます。

    ダッシュボードをインポートする画面のスクリーンショット

  4. インポートしたダッシュボードをクリックして、視覚化されたログ・データを表示します。

    視覚化されたログ・データを表示する画面のスクリーンショット

コマンド・ラインを使用してログを確認する

コマンド・ラインからログを表示するには、以下のように oc logs コマンドを使用します。

oc logs -f pod_name -n namespace

ここで、pod_name は Open Liberty ポッドの名前、namespace はそのポッドが稼働している名前空間です。

JSON Query ツール (jq) などのコマンド・ライン JSON 構文解析プログラムを使用すれば、人間が読んで理解できる JSON 形式のログのビューを作成できます。以下の例では、jq で行を解析する前にメッセージ・フィールドが確実に存在するように、grep を実行してログをパイプ接続しています。

oc logs -f pod_name -n namespace | \
  grep --line-buffered message | \
  jq .message -r

Java Open Liberty Appsody スタックの正常性をモニタリングする

MicroProfile Health 機能を使用すると、サービスにサービス自身の readiness ステータスと liveness ステータスを報告させることができます。この機能は、全体的なヘルス・ステータスを定義済みのエンドポイントを介して公開します。サービスから「UP」と報告された場合、サービスは利用可能な状態です。サービスから「DOWN」と報告された場合、サービスを利用することはできません。MicroProfile Health はエンドポイントでの個々のサービス・ステータスを報告し、すべてのサービスが稼動中の場合は全体的なステータスを「UP」として示します。サービス・オーケストレーターは、MicroProfile Health から報告されたヘルス・ステータスに基づいてオーケストレーションを決定できます。

liveness チェックと readiness チェックでのヘルス・データは、それぞれ /health/live エンドポイント、/health/ready エンドポイントで利用可能になります。

コンテナーのヘルス・チェックには、Kubernetes に用意されている liveness プローブと readiness プローブが使用されます。これらのプローブでは、コンテナー内の特定のファイルをチェックするか、単一の TCP ソケットをチェックする、または HTTP リクエストを行うことができます。MicroProfile Health はマイクロサービスの上述の readiness エンドポイントと liveness エンドポイントを公開し、Kubernetes はブローブで指定されたこれらのエンドポイントをポーリングして、マイクロサービスのステータスに変更があれば、それに応じて必要な処理を行います。

Kubernetes の liveness プローブと readiness プローブは、Appsody Operator と Open Liberty Appsody スタックの構成ファイルに含まれる、それぞれの MicroProfile Health エンドポイントに応じて、このように事前構成されています。

Kubernetes の liveness プローブと readiness プローブの構成について詳しくは、このドキュメントを参照してください。

Open Liberty Appsody スタックのメトリックをモニタリングする

MicroProfile Metrics が有効にされた Open Liberty ランタイムでは、JVM と Open Liberty サーバーからのメトリックを追跡して観測できるだけでなく、デプロイ済みアプリケーション内でインスツルメンテーション化されたメトリックも追跡できます。メトリック・データは /metrics エンドポイント上で利用可能になります。追跡対象のメトリック・データは、Prometheus で収集して Grafana で視覚化できます。

IBM では、JVM ならびに Open Liberty ランタイムによって追跡されたメトリックを利用する Grafana ダッシュボードをいくつか提供しています。ここにアクセスして、適切なダッシュボードを見つけてください。

Grafana Operator を使用して Grafana ダッシュボードをインポートする

OpenShift Container Platform Web コンソールで、Prometheus/Grafana Operator スタックがインストールされているプロジェクトを表示して、「Installed Operators (インストール済み Operator)」にナビゲートします。

インストール済み Grafana Operator の下にある「Grafana Dashboard (Grafana ダッシュボード) 」をクリックします。

Grafana ダッシュボードを表示するためのリンクのスクリーンショット

既存のダッシュボードが表示されます。新しい Grafana ダッシュボードを作成するには、「Create Grafana Dashboard (Grafana ダッシュボードの作成)」をクリックします。

「Create Grafana Dashboard (Grafana ダッシュボードの作成)」ボタンのスクリーンショット

yaml ファイル内の JSON 定義の下にある既存の内容を削除して、目的のダッシュボードをコピーします。「Create (作成) 」をクリックして完了します。

目的のダッシュボードをコピーする部分を示す画面のスクリーンショット

Grafana で視覚化されたダッシュボードを表示するには、「Networking (ネットワーキング)」 > 「Routes (ルート)」にナビゲートして、Grafana の公開ルートにアクセスします。

目的のダッシュボードをコピーする部分を示す画面のスクリーンショット

まとめ

Java Open Liberty Appsody スタックを使用して、さまざまなモニタリング・ツールを組み合わせて可観測性を向上させるために、MicroProfile Health と MicroProfile Metrics の両方を使ったマイクロサービスを構成し、Liberty の JSON ロギングを有効にしました。さらに、Elasticsearch、Fluentd、Kibana という強力なモニタリング・ツールを統合して、ロギング・データの取得、保管、視覚化を行うとともに、Prometheus と Grafana を使用してメトリック・データの取得、保管、視覚化も実現しました。

次のステップ