Consul の Check definitions 研究

ども、 cloudpack の かっぱ (@inokara) です。

研究

というと大袈裟だが Consul の Check 定義について調べたのでメモっておく。

参考

• Check Definition – Consul by HashiCorp
• Consul関連ドキュメント(参考訳)Part2 | Pocketstudio.jp log3

俺訳 Check 定義

そもそも Check 定義とは

One of the primary roles of the agent is management of system-level and application-level health checks. A health check is considered to be application-level if it is associated with a service. If not associated with a service, the check monitors the health of the entire node.

• （Consul の）重要な役割としてシステムレベルとアプリケーションレベルのヘルスチェック管理がある
• サービスに関連付けられたヘルスチェックはアプリケーションレベルのヘルスチェックとなる
• サービスに関連付けられていない場合にはノード自体のヘルスチェックとなる

A check is defined in a configuration file or added at runtime over the HTTP interface. Checks created via the HTTP interface persist with that node.

• （ヘルス）チェックは設定ファイル又はHTTP インターフェースを利用して定義することが出来る
• HTTP インターフェースで作成された Checks はノードで永続される（超意訳）

Check 定義の確認

定義の確認は以下のように HTTP API で確認することが出来る。

curl -s localhost:8500/v1/agent/checks | python -m json.tool

以下のように出力される。

{
    "service:app": {
        "CheckID": "service:app",
        "Name": "Service 'app' check",
        "Node": "9c337cce1429",
        "Notes": "",
        "Output": "",
        "ServiceID": "app",
        "ServiceName": "app",
        "Status": "critical"
    },
    "web-app": {
        "CheckID": "web-app",
        "Name": "Web App Status",
        "Node": "9c337cce1429",
        "Notes": "",
        "Output": "TTL expired",
        "ServiceID": "",
        "ServiceName": "",
        "Status": "critical"
    }
}

三種類

Consul で定義出来る Check は以下の三種類。

• Script + Interval
• HTTP + Interval
• Time to Live (TTL)

Script + Interval Check とは

以下のようなステータスを返すスクリプトによる Check でスクリプトの言語は問わない。

• Exit code 0 – Check is passing（終了コードが 0 であれば Check は Passing）
• Exit code 1 – Check is warning（終了コードが 1 であれば Check は Warning）
• Any other code – Check is failing（上記以外であれば Check は Fail）

以下のように設定を行う。

{
  "check": {
    "id": "app-check",
    "name": "App Check",
    "script": "/opt/bin/app-check.sh",
    "interval": "10s"
  }
}

尚、 interval と一緒に設定する必要がある。また、Nagios のチェックプラグインと類似している（互換性がある）。

HTTP + Interval Check とは

HTTP Check は以下のような特徴がある。

• curl 等でアクセスするのと同等の機能
• ステータスコード 2xx が返却されれば passing となる
• 429 Too Many Requests が warning となる
• 2xx と 429 以外は failing となる
• timeout を指定してタイムアウトを指定することも出来る
• Script Check と同様に interval と一緒に設定を行う必要がある。

以下のように設定を行う。

{
  "check": {
    "id": "api",
    "name": "HTTP API on port 1919",
    "http": "http://localhost:1919/foo",
    "interval": "10s",
    "timeout": "1s"
  }
}

尚、HTTP Check は Consul 0.5 からサポート された。

TTL Check とは

以下、ドキュメントより抜粋。

Time to Live (TTL) – These checks retain their last known state for a given TTL. The state of the check must be updated periodically over the HTTP interface. If an external system fails to update the status within a given TTL, the check is set to the failed state. This mechanism, conceptually similar to a dead man’s switch, relies on the application to directly report its health. For example, a healthy app can periodically PUT a status update to the HTTP endpoint; if the app fails, the TTL will expire and the health check enters a critical state.

• TTL に与えられた時間だけ状態を保持する
• 状態は HTTP インターフェースを利用して更新する必要がある
• TTL 内に状態が更新されない場合には Check は失敗の状態と判断される

とのことで…ナンノコッチャかと思っていたが、以下のように考えるとシックリきた。

• アプリケーション自身が自身の状態を通知する
• 通知された状態は TTL の時間だけ Consul 内に保持される

ついでに図示してみたのが以下。

なるほど、なるほど。

実験

Script Check

以下は Check の定義。

{
  "check": {
    "id": "app-check",
    "name": "App Check",
    "script": "/opt/bin/app-check.sh",
    "interval": "10s"
  }
}

以下は Check で利用するスクリプト。

#!/usr/bin/env bash
status=`curl -LI http://localhost:1919/foo -o /dev/null -w '%{http_code}n' -s`
if [ $status = "200" ];then
  exit 0
else
  exit 2
fi

Check の確認。

$ curl -s localhost:8500/v1/agent/checks | python -m json.tool
{
    "app-check": {
        "CheckID": "app-check",
        "Name": "App Check",
        "Node": "9c337cce1429",
        "Notes": "",
        "Output": "",
        "ServiceID": "",
        "ServiceName": "",
        "Status": "passing"
    }
}

Check 対象に異常発生（監視対象のアプリケーションが停止）後に Check を確認。

$ curl -s localhost:8500/v1/agent/checks | python -m json.tool
{
    "app-check": {
        "CheckID": "app-check",
        "Name": "App Check",
        "Node": "9c337cce1429",
        "Notes": "",
        "Output": "",
        "ServiceID": "",
        "ServiceName": "",
        "Status": "critical"
    }
}

Status が critical となっているの判る。

TTL Check

以下は Check の定義。

{
  "check": {
      "id": "web-app",
      "name": "Web App Status",
      "ttl": "30s"
  }
}

Check の確認。

$ curl -s localhost:8500/v1/agent/checks | python -m json.tool
{
    "web-app": {
        "CheckID": "web-app",
        "Name": "Web App Status",
        "Node": "9c337cce1429",
        "Notes": "",
        "Output": "TTL expired",
        "ServiceID": "",
        "ServiceName": "",
        "Status": "critical"
    }
}

Check の状態を以下のように HTTP API にアクセスして更新する。

$ curl -sI localhost:8500/v1/agent/check/pass/web-app
HTTP/1.1 200 OK
Date: Wed, 11 Mar 2015 15:47:30 GMT
Content-Type: text/plain; charset=utf-8

上記を実行後に Check の状態を確認。

$ curl -s localhost:8500/v1/agent/checks | python -m json.tool
{
    "web-app": {
        "CheckID": "web-app",
        "Name": "Web App Status",
        "Node": "9c337cce1429",
        "Notes": "",
        "Output": "",
        "ServiceID": "",
        "ServiceName": "",
        "Status": "passing"
    }
}

Status が passing に変わっている。
上記の例では passing へ変更を行ったが 、以下のように実行することで warning へ変更することも可能。

$ curl -sI localhost:8500/v1/agent/check/pass/web-app
HTTP/1.1 200 OK
Date: Wed, 11 Mar 2015 15:51:55 GMT
Content-Type: text/plain; charset=utf-8

以下のように Status が warning に変更されている。

$ curl -s localhost:8500/v1/agent/checks | python -m json.tool
{
    "web-app": {
        "CheckID": "web-app",
        "Name": "Web App Status",
        "Node": "9c337cce1429",
        "Notes": "",
        "Output": "",
        "ServiceID": "",
        "ServiceName": "",
        "Status": "warning"
    }
}

passing や warning 以外にも HTTP API にて /v1/agent/check/fail/ にアクセスすることで critical の状態に設定することも可能。詳細については以下に記載されている。

• AGENT HTTP ENDPOINT

ということで…

そもそも

Check 定義について調べたきっかけが TTL って何に使うの？ってところだったので TTL がナニモノかが判って今日は寝れそう。

Check は…

• Consul の主要な機能の一つ
• 三種盛り（Script / HTTP / TTL）
• Service と Check は関連している（Service 登録すると Check は自動的に追加される）
• TTL の使いドコロは今でもちょっと不明

ということでお疲れ様でした。おやすみさい。

元記事はこちらです。
「Consul の Check definitions 研究」