5 ヘルス・チェックAPIの使用
ノート:
ヘルス・チェックを有効にするには、ブートストラップAPIを使用してCoherenceクラスタ・メンバーを起動する必要があります。「ブートストラップAPIの使用」を参照してください。この章の内容は次のとおりです。
- ヘルス・チェックAPIについて
アプリケーション・コードからヘルス・チェックAPIを使用して、Coherenceが正常かどうかを判断できます。また、HTTPエンドポイントから使用して、KubernetesやDockerなどのコンテナ化された環境でのヘルス・チェックに役立てることもできます。 - 組込みヘルス・チェックの使用
Coherenceには、すぐに使用できるヘルス・チェックが数多くあります。 - HTTPヘルス・チェックの有効化
ヘルス・チェックHTTPエンドポイントは、ブートストラップAPIを使用してCoherenceを実行するか、com.tangosol.net.Coherence
をメイン・クラスとして使用してCoherenceを起動すると有効になります。それ以外の方法でCoherenceを起動した場合、ヘルス・チェックAPIは使用できますが、HTTPエンドポイントは実行されません。 - アプリケーション・ヘルス・チェックの使用
ヘルス・チェックAPIを使用すると、アプリケーション開発者はカスタム・ヘルス・チェックを追加できます。これは、Coherenceメンバーの全体的なヘルスを判別するために使用する必要があるサービスをアプリケーションが提供する場合に役立ちます。 - コンテナ化されたヘルス・チェックの使用
Coherenceアプリケーションをコンテナ内で(DockerやKubernetesなどで)実行する場合は、ヘルス・チェックと準備状況チェックを使用できると便利です。ヘルスHTTPエンドポイントを有効にしてCoherenceを実行すると、コンテナのヘルスの構成が簡単になります。
ヘルス・チェックAPIについて
アプリケーション・コードからヘルス・チェックAPIを使用して、Coherenceが正常かどうかを判断できます。また、HTTPエンドポイントから使用して、KubernetesやDockerなどのコンテナ化された環境でのヘルス・チェックに役立てることもできます。
public interface HealthCheck
{
/**
* Returns the unique name of this health check.
*
* @return the unique name of this health check
*/
String getName();
/**
* Return {@code true} if this {@link HealthCheck} should
* be included when working out this Coherence member's
* health status.
*
* @return {@code true} if this {@link HealthCheck} should
* be included in the member's health status
*/
default boolean isMemberHealthCheck()
{
return true;
}
/**
* Returns {@link true} if the resource represented by
* this {@link HealthCheck} is ready, otherwise returns
* {@code false}.
* <p>
* The concept of what "ready" means may vary for different
* types of resources.
*
* @return {@link true} if the resource represented by this
* {@link HealthCheck} is ready, otherwise {@code false}
*/
boolean isReady();
/**
* Returns {@link true} if the resource represented by
* this {@link HealthCheck} is alive, otherwise returns
* {@code false}.
* <p>
* The concept of what "alive" means may vary for different
* types of resources.
*
* @return {@link true} if the resource represented by this
* {@link HealthCheck} is alive, otherwise returns
* {@code false}
*/
boolean isLive();
/**
* Returns {@link true} if the resource represented by
* this {@link HealthCheck} is started, otherwise returns
* {@code false}.
* <p>
* The concept of what "started" means may vary for different
* types of resources.
*
* @return {@link true} if the resource represented by this
* {@link HealthCheck} is started, otherwise returns
* {@code false}
*/
boolean isStarted();
/**
* Returns {@link true} if the resource represented by this
* {@link HealthCheck} is in a safe state to allow a rolling
* upgrade to proceed, otherwise returns {@code false}.
* <p>
* The concept of what "safe" means may vary for different
* types of resources.
*
* @return {@link true} if the resource represented by this
* {@link HealthCheck} is in a safe state to allow
* a rolling upgrade to proceed, otherwise returns
* {@code false}
*/
boolean isSafe();
}
メソッドは、Coherenceが実行される他のシステム(たとえば、Kubernetesなど、同様の開始済ヘルス・チェック、稼働中ヘルス・チェックおよび準備状況ヘルス・チェックを使用するシステム)と統合するために選択されたものです。安全チェックはCoherenceに固有であり、次のクラスタ・メンバーのローリング前にクラスタが安全であると判断することが重要である、ローリング・アップグレードなどのユースケースを制御するために使用されます。
com.tangosol.net.management.Registryクラス
からアクセスできます。Registry
は通常、現在のCoherence Cluster
インスタンスから取得されます。たとえば、com.tangosol.net.Coherence.main()
を実行するか、ブートストラップAPIを使用してCoherenceを起動した場合は、次に示すように管理Registry
を取得できます:Cluster cluster = Coherence.getInstance().getCluster();
Registry registry = cluster.getManagement();
ヘルス・チェックAPIでは、クラスタ全体のAPIではないため、ローカルCoherenceメンバーの登録済ヘルス・チェックのみを表示できます。クラスタ全体のヘルス・チェックには、Coherence管理API、JMX、またはREST経由の管理を介して、対応するヘルスMBeanを使用します。
この項には次のトピックが含まれます:
- すべてのヘルス・チェックの取得
- 名前によるヘルス・チェックの取得
- すべてのヘルス・チェックが準備完了していることの確認
- すべてのヘルス・チェックが開始されていることの確認
- すべてのヘルス・チェックが稼働していることの確認
- すべてのヘルス・チェックが安全であることの確認
親トピック: ヘルス・チェックAPIの使用
すべてのヘルス・チェックの取得
すべての登録済ヘルス・チェックのコレクションを取得するには、Registry
インスタンスでgetHealthChecks()
メソッドをコールできます。このメソッドは、登録済HealthCheck
インスタンスの不変コレクションを返します。
HealthCheck
インスタンスの名前のSet
を取得します:Coherence coherence = Coherence.getInstance();
Registry registry = coherence.getManagement();
Collection<HealthCheck> healthChecks = registry.getHealthChecks();
Set<String> names = healthChecks.stream()
.filter(hc -> !hc.isReady())
.map(HealthCheck::getName)
.collect(Collectors.toSet());
親トピック: ヘルス・チェックAPIについて
名前によるヘルス・チェックの取得
特定のヘルス・チェックを名前で取得するには、Registry
インスタンスでgetHealthCheck(String name)
メソッドをコールします。このメソッドは、リクエストされたHealthCheck
を含むOptional
を返します(リクエストされた名前に登録されているものがある場合)。リクエスト名にHealthCheck
が登録されていない場合は空のOptional
を返します。
HealthCheck
を取得します:Coherence coherence = Coherence.getInstance();
Registry registry = coherence.getManagement();
Optional<HealthCheck> healthChecks = registry.getHealthCheck("Foo");
親トピック: ヘルス・チェックAPIについて
すべてのヘルス・チェックが準備完了していることの確認
Registry
インスタンスでallHealthChecksReady()
メソッドを使用すると、ローカルに登録されているすべてのヘルス・チェックが準備完了しているかどうかを判断できます。準備完了チェックには、isMemberHealthCheck()
メソッドからtrue
を返すヘルス・チェックのみが含まれます。Coherence coherence = Coherence.getInstance();
Registry registry = coherence.getManagement();
boolean ready = registry.allHealthChecksReady();
親トピック: ヘルス・チェックAPIについて
すべてのヘルス・チェックが開始されていることの確認
Registry
インスタンスでallHealthChecksStarted()
メソッドを使用すると、ローカルに登録されているすべてのヘルス・チェックが開始されているかどうかを判断できます。開始済チェックには、isMemberHealthCheck()
メソッドからtrue
を返すヘルス・チェックのみが含まれます。
Coherence coherence = Coherence.getInstance();
Registry registry = coherence.getManagement();
boolean started = registry.allHealthChecksStarted();
親トピック: ヘルス・チェックAPIについて
すべてのヘルス・チェックが稼働していることの確認
Registry
インスタンスでallHealthChecksLive()
メソッドを使用すると、ローカルに登録されたすべてのヘルス・チェックが稼働中かどうかを判断できます。稼働チェックには、isMemberHealthCheck()
メソッドからtrue
を返すヘルス・チェックのみが含まれます。Coherence coherence = Coherence.getInstance();
Registry registry = coherence.getManagement();
boolean live = registry.allHealthChecksLive();
親トピック: ヘルス・チェックAPIについて
すべてのヘルス・チェックが安全であることの確認
Registry
インスタンスでallHealthChecksSafe()
メソッドを使用すると、ローカルに登録されたすべてのヘルス・チェックが安全かどうかを判断できます。安全チェックには、isMemberHealthCheck()
メソッドからtrue
を返すヘルス・チェックのみが含まれます。Coherence coherence = Coherence.getInstance();
Registry registry = coherence.getManagement();
boolean safe = registry.allHealthChecksSafe();
親トピック: ヘルス・チェックAPIについて
組込みヘルス・チェックの使用
- 各Coherenceサービスには、対応するヘルス・チェックがあります。
-
com.tangosol.net.Coherence
のインスタンスは、対応するヘルス・チェックを提供します。 - Coherence gRPC統合を使用している場合、gRPCプロキシ・サーバーにはヘルス・チェックがあります。
この項には次のトピックが含まれます:
親トピック: ヘルス・チェックAPIの使用
サービス・ヘルス・チェックの使用
- 開始済: サービス・ヘルス・チェックの
isStarted()
メソッドは、対応するサービスが実行されている場合はtrue
を返します。 - 稼働中: サービス・ヘルス・チェックの
isLive()
メソッドは、対応するサービスが実行されている場合はtrue
を返します。 - 準備完了: サービスの場合、
isReady()
メソッドは、サービスが安全になるまではfalse
を返し、その後は準備完了状態がtrue
のままになります。これは具体的には、Kubernetesなど、Ready
でなければポッドがService
から削除されるようなユース・ケースに対応しています。ただし、この動作は通常はCoherenceに必要ありません。 - 安全: パーティション化されたキャッシュ・サービスを除くすべてのサービスの場合、
isSafe()
メソッドは常にtrue
を返します。
親トピック: 組込みヘルス・チェックの使用
PartitionedCacheサービスのisSafeチェックの使用
Coherence PartitionedCache
サービスは、Coherenceのほとんどのサービスよりも複雑であるため、そのヘルス・チェックで行われる処理も多くなります。PartitionedCache
サービスのisSafe()
チェックでは、サービスが安定していて安全であることを確認するための多数のチェックが実行されます。安全チェックの主なユースケースは、ローリング・アップグレードを実行する場合、またはクラスタを安全にスケール・ダウンする場合です。
- 記憶域が有効になっていないメンバーに対する
PartitionedCache
サービスのisSafe()
ヘルス・チェックは、サービスが実行されているかぎりはtrue
を返します。 PartitionedCache
サービスのisSafe()
ヘルス・チェックは、サービスでこのメンバーが記憶域が有効になった唯一のメンバーであるが、すべてのパーティションを所有しているわけではない場合に、false
を返します。これは、クラスタの他のすべてのメンバーが停止された直後、パーティションのリカバリおよび再割当てロジックがまだ進行中である場合に発生する可能性があります。したがって、このメンバーは、すべてのパーティションを所有していることをまだ認識していません。- バックアップ数が0より大きい値に構成されており、サービスのStatusHA状態が
endangered
になっている場合、PartitionedCache
サービスのisSafe()
ヘルス・チェックはfalse
を返します。キャッシュ構成ファイルで個々のサービスに対するこの動作を変更して、それぞれが危険にさらされることを許可できます。バックアップ数が0のサービスは、安全チェックで危険にさらされることが許可されています。 - パーティション再分散が進行中の場合、
PartitionedCache
サービスのisSafe()
ヘルス・チェックはfalse
を返します。 - 永続記憶域からのリカバリが進行中の場合、
PartitionedCache
サービスのisSafe()
ヘルス・チェックはfalse
を返します。
親トピック: 組込みヘルス・チェックの使用
メンバー・ヘルスからのサービスの除外
Coherenceサービスをメンバーの全体的なヘルス・チェックから除外することが望ましい場合もあります。これを行うには、キャッシュ構成ファイルでサービスの<health>
要素に<member-health-check>
要素を設定します。
たとえば、次のproxy-schemeでは<member-health-check>
要素の値がfalse
に設定されています。Proxy
サービスのヘルス・チェックにはヘルスAPIを介してまだアクセスできますが、Registry
クラスのallHealthChecksReady()
メソッドなど、メンバー・ヘルス全体のチェックからはProxy
サービスが除外されます。
<proxy-scheme>
<service-name>Proxy</service-name>
<autostart>true</autostart>
<health>
<member-health-check>false</member-health-check>
</health>
</proxy-scheme>
親トピック: 組込みヘルス・チェックの使用
危険にさらされたサービスの許可
意図的に危険にさらすことができる分散キャッシュ・サービスをアプリケーションで構成する場合もあります。ただし、この状態がメンバーの全体的なヘルスに反映されないようにします。これを行うには、キャッシュ構成ファイルで分散スキームの<health>
要素に<allow-endangered>
要素を設定します。
たとえば、次のdistributed-scheme
では<allow-endangered>
要素の値がtrue
に設定されています。PartitionedCache
のヘルス・チェックでは、サービスのStatusHA値が'ENDANGERED'であっても、サービスが準備完了または安全であることが報告されます。
<distributed-scheme>
<scheme-name>distributed-scheme</scheme-name>
<service-name>PartitionedCacheOne</service-name>
<backing-map-scheme>
<local-scheme/>
</backing-map-scheme>
<autostart>true</autostart>
<health>
<allow-endangered>true</allow-endangered>
</health>
</distributed-scheme>
親トピック: 組込みヘルス・チェックの使用
HTTPヘルス・チェックの有効化
com.tangosol.net.Coherence
をメイン・クラスとして使用してCoherenceを起動すると有効になります。それ以外の方法でCoherenceを起動した場合、ヘルス・チェックAPIは使用できますが、HTTPエンドポイントは実行されません。デフォルトでは、HTTPサーバーはエフェメラル・ポートにバインドされますが、これはcoherence.health.HTTP.port
システム・プロパティまたはCOHERENCE_HEALTH_HTTP_PORT
環境変数を設定することで変更できます。
http://localhost:6676
のヘルス・エンドポイントを使用して起動されます:java -cp coherence.jar -Dcoherence.health.http.port=6676 \
com.tangosol.net.Coherence
java -p coherence.jar \
-Dcoherence.health.http.port=6676 \
--module com.oracle.coherence
curl
ユーティリティを使用して、エンドポイントの1つ(/ready
など)をポーリングできます:curl -i -X GET http://localhost:6676/ready
HTTP/1.1 200 OK Date: Tue, 19 Apr 2022 17:59:05 GMT Content-type: application/json Vary: Accept-Encoding Content-length: 0 X-content-type-options: nosniff
Coherenceヘルス・チェックが失敗した場合、レスポンス・コードは503 (サービス使用不可を表す)になります。
親トピック: ヘルス・チェックAPIの使用
ヘルスHTTPエンドポイント
ヘルス・チェックHTTPサーバーには、多数のエンドポイントがあります。
ノート:
いずれのエンドポイントも、ペイロードを受け入れたり、レスポンス本文を返すことはありません。レスポンスは、ステータス・コード200または503のみです。つまり、SSL/TLSを使用するようにヘルス・エンドポイントを構成できますが、暗号化の必要性はほとんどなく、Kubernetesやその他のコンテナ環境などの外部ツールで使用するほうが簡単です。表5-1 ヘルス・チェックHTTPサーバー・エンドポイント
エンドポイント | 説明 |
---|---|
|
リクエストの送信先のメンバーのすべてのヘルス・チェックが開始されている場合、このエンドポイントはレスポンスとしてステータス・コード200を返します。開始されていないヘルス・チェックが1つ以上ある場合、エンドポイントは503のレスポンスを返します。 |
|
リクエストの送信先のメンバーのすべてのヘルス・チェックが稼働している場合、このエンドポイントはレスポンスとしてステータス・コード200を返します。稼働していないヘルス・チェックが1つ以上ある場合、エンドポイントは503のレスポンスを返します。 |
|
リクエストの送信先のメンバーのすべてのヘルス・チェックが準備完了している場合、このエンドポイントはレスポンスとしてステータス・コード200を返します。準備完了していないヘルス・チェックが1つ以上ある場合、エンドポイントは503のレスポンスを返します。 |
|
リクエストの送信先のメンバーのすべてのヘルス・チェックが安全である場合、このエンドポイントはステータス・コード200のレスポンスを返します。安全でないヘルス・チェックが1つ以上ある場合、エンドポイントは503のレスポンスを返します。 |
親トピック: HTTPヘルス・チェックの有効化
アプリケーション・ヘルス・チェックの使用
カスタム・ヘルス・チェックを登録するには、com.tangosol.util.HealthCheck
の実装を記述するだけです。
カスタム・ヘルス・チェックのgetName()
メソッドは、このヘルス・チェックを表す一意の名前を返す必要があります。ヘルス・チェックはMBeanとして公開されるため、JMX MBeanオブジェクト名で有効な名前である必要があります。
次に、ヘルス・チェック実装で、関連するアプリケーション・ロジックを使用して、各メソッドに対して返す結果を決定する必要があります。一部のメソッドは該当しない可能性もあるため、その場合はtrue
のみを返す必要があります。
様々なヘルス・チェック・メソッドの結果がアプリケーション・コードの外側でどのように使用されるかを理解することが重要です。たとえば、アプリケーションが、アプリケーションの状態をモニターする外部システムによってデプロイおよび管理されている場合です。たとえば、Kubernetesにデプロイされたアプリケーションが稼働中でないことが何度も報告される場合に、アプリケーションを中断します。準備完了であることが報告されないアプリケーションを、リクエストのルーティングなどから除外します。安全でないアプリケーションは、Coherenceクラスタのローリング・アップグレードまたは安全なスケーリングをブロックします。
メンバー・ヘルスからのカスタム・ヘルス・チェックの除外
アプリケーション開発者が、アプリケーション・サービスのカスタム・ヘルス・チェックを追加するが、これらのチェックを全体的なCoherenceメンバー・ヘルスに反映させないようにする必要があることもあります。HealthCheck
インタフェースには、この目的のための isMemberHealthCheck()
メソッドがあります。isMemberHealthCheck()
のデフォルト実装では常にtrue
が返されるため、デフォルトではすべてのヘルス・チェックがメンバーのヘルスに含められます。メンバーのヘルスからヘルス・チェックを除外するには、false
を返すようにisMemberHealthCheck()
メソッドをオーバーライドします。
親トピック: アプリケーション・ヘルス・チェックの使用
コンテナ化されたヘルス・チェックの使用
Coherenceアプリケーションをコンテナ内で(DockerやKubernetesなどで)実行する場合は、ヘルス・チェックと準備状況チェックを使用できると便利です。ヘルスHTTPエンドポイントを有効にしてCoherenceを実行すると、コンテナのヘルスの構成が簡単になります。
コンテナ内でヘルス・チェック・エンドポイントを使用している場合は、イメージのヘルス・チェックを構成できるようにHTTPポートを修正する必要があります。デフォルトの動作ではエフェメラル・ポートにバインドされるため、システムはヘルス・チェックAPIがバインドされているポートを認識しません。HTTPポートを設定するには、coherence.health.HTTP.port
システム・プロパティまたはCOHERENCE_HEALTH_HTTP_PORT環境変数を使用します。イメージを作成するときは、通常、環境変数を使用するほうが簡単です。これについては、この項で例を挙げて説明します。
この項には次のトピックが含まれます:
Dockerヘルス・チェックの使用
DockerfileのHEALTHCHECK
構成を使用して、ヘルス・チェックで構成されたCoherence Dockerイメージを構築できます。
Dockerfile
の例では、ENV COHERENCE_HEALTH_HTTP_PORT=6676
設定を使用してヘルス・チェック・ポートを6676
に設定しています。次に、Dockerfile
をHEALTHCHECK
で構成しています。このコマンドはHTTP://127.0.0.1:6676/ready
のHTTPエンドポイントに対してcurl
を実行します。レスポンスが200
でない場合、このコマンドは失敗します。FROM openjdk:11-jre
ADD coherence.jar /coherence/lib/coherence.jar
ENTRYPOINT [ "java" ]
CMD [ "-cp", "/coherence/lib/*", "com.tangosol.net.Coherence" ]
ENV COHERENCE_HEALTH_HTTP_PORT=6676
HEALTHCHECK CMD curl --fail http://127.0.0.1:6676/ready || exit 1
前述のチェックでは、ベース・イメージにcurl
がインストールされていることを前提としています。常にそうであるとはかぎりません。たとえば、非常にスリムなLinuxベース・イメージや歪みのないイメージには、curl
などの追加ツールがないものもあります。この場合、すべてのイメージにあるものはJavaです。したがって、Coherence jarに組み込まれているJavaヘルス・チェック・クライアント・クラスcom.tangosol.util.HealthCheckClient
を使用するようにヘルス・チェックを構成できます。このクラスは、チェックするHTTPエンドポイントのURLである単一パラメータを使用して実行できます。
Dockerfile
の例では、LinuxカーネルおよびJava 11のみがインストールされている歪みのないベース・イメージを使用しています。ヘルス・チェック・ポートは、ENV COHERENCE_HEALTH_HTTP_PORT=6676
設定を使用して6676
に設定されています。次に、Dockerfile
をHEALTHCHECK
で構成しています。このコマンドはjava -cp /coherence/lib/coherence.jar com.tangosol.util.HealthCheckClient http://127.0.0.1:6676/ready
を実行します。レスポンスが200でない場合、このコマンドは失敗します。FROM gcr.io/distroless/java11
ADD coherence.jar /coherence/lib/coherence.jar
ENTRYPOINT [ "java" ]
CMD [ "-cp", "/coherence/lib/*", "com.tangosol.net.Coherence" ]
ENV COHERENCE_HEALTH_HTTP_PORT=6676
HEALTHCHECK CMD java -cp /coherence/lib/coherence.jar com.tangosol.util.HealthCheckClient http://127.0.0.1:6676/ready
親トピック: コンテナ化されたヘルス・チェックの使用
Kubernetesの準備状況プローブおよび有効性プローブの使用
Kubernetesには、様々な構成可能な準備状況プローブおよび有効性プローブがあります。Kubernetesの準備状況と有効性はイメージとは無関係なので、イメージそのものはヘルス・チェックを必要としません(「Dockerヘルス・チェックの使用」を参照)。Kubernetesの準備状況および有効性の構成の詳細は、Kubernetesのドキュメントを参照してください。
Pod
です。COHERENCE_HEALTH_HTTP_PORT
環境変数は、ヘルス・チェックHTTPポートを6676
に修正するために使用されます。次に、readinessProbe
を、リクエスト・パス/ready
を使用してポート6676
でHTTP GETリクエストを使用するように構成しています。リクエストのホストはデフォルトでポッドIPアドレスになるため、事実上http://<pod-ip>:6676/ready
と同じです。apiVersion: v1
kind: Pod
metadata:
name: coherence
spec:
containers:
- name: coherence
image: ghcr.io/oracle/coherence-ce:22.06
env:
- name: COHERENCE_HEALTH_HTTP_PORT
value: "6676"
- name: COHERENCE_WKA
value: coherence_wka.svc.cluster.local
readinessProbe:
httpGet:
path: "/ready"
port: 6676
initialDelaySeconds: 30
periodSeconds: 30
親トピック: コンテナ化されたヘルス・チェックの使用