Consul の Check definitions 研究 - ようへいの日々精進XP

ども、かっぱです。

研究

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

参考

俺訳 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 内に保持される

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

f:id:inokara:20150311235113p:plain

なるほど、なるほど。

実験

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/<checkId> にアクセスすることで critical の状態に設定することも可能。詳細については以下に記載されている。