Consul Watch
Consul Watch (감시)
watch는 업데이트를 감시하는 데이터 뷰(예: 노드 목록, KV 쌍, 헬스 체크)를 지정하는 방법이에요. 업데이트가 감지되면 외부 핸들러가 호출되고, 핸들러는 실행 파일이거나 HTTP 엔드포인트가 될 수 있어요.
출처: 문서
본문
watch는 업데이트를 감시하는 데이터 뷰(예: 노드 목록, KV 쌍, 헬스 체크)를 지정하는 방법입니다. 업데이트가 감지되면 외부 핸들러가 호출됩니다. 핸들러는 실행 파일이거나 HTTP 엔드포인트일 수 있습니다. 예를 들어 헬스 체크의 상태를 감시하고 체크가 critical이 되면 외부 시스템에 알릴 수 있습니다.
Watch는 HTTP API의 blocking query를 사용하여 구현됩니다. 에이전트는 변경을 감시하고 데이터 뷰가 업데이트되면 핸들러에 알리는 적절한 API 호출을 자동으로 수행합니다.
Watch는 에이전트 구성의 일부로 구성할 수 있으며, 에이전트가 초기화되면 실행됩니다. 에이전트 구성을 다시 로드하면 watch를 동적으로 추가하거나 제거할 수 있습니다.
또는 watch 명령을 사용하면 에이전트 외부에서 watch를 시작할 수 있습니다. 운영자는 이를 사용해 Consul의 데이터를 검사하거나 에이전트 수명주기에 얽매이지 않고 데이터를 프로세스로 쉽게 전달할 수 있습니다.
두 경우 모두 watch의 type을 지정해야 합니다. 각 watch 유형은 일부 필수, 일부 선택 매개변수를 지원합니다. 이러한 옵션은 에이전트 구성을 사용할 때 JSON 본문으로 지정하거나 watch 명령의 CLI 플래그로 지정합니다.
핸들러 (Handlers)
watch 구성은 감시할 데이터 뷰를 지정합니다. 해당 뷰가 업데이트되면 지정된 핸들러가 호출됩니다. 핸들러는 실행 파일이거나 HTTP 엔드포인트일 수 있습니다. 핸들러는 watch 유형에 따라 달라지는 형식의 호출 정보가 포함된 JSON 형식 데이터를 수신합니다. 각 watch 유형은 형식 유형을 문서화합니다. HTTP API에 직접 매핑되므로 핸들러는 입력이 API 형식과 일치할 것으로 예상해야 합니다. 또한 HTTP API의 응답에 해당하는 Consul index도 제공됩니다.
실행 파일 (Executable)
실행 파일 핸들러는 stdin에서 JSON 호출 정보를 읽습니다. 또한 CONSUL_INDEX 환경 변수가 Consul index로 설정됩니다. stdout에 기록된 모든 내용은 로그에 기록됩니다.
다음은 handler_type이 선택적으로 script로 설정된 구성 예시입니다.
에이전트 구성에 정의된 스크립트 핸들러가 있는 Consul watch
agent-config.hcl
watches = [
{
type = "key"
key = "foo/bar/baz"
handler_type = "script"
args = ["/usr/bin/my-service-handler.sh", "-redis"]
}
]
Consul 1.0 이전에는 watch가 실행할 명령을 정의하는 단일 handler 필드를 사용했으며 항상 셸에서 실행되었습니다. Consul 1.0에서는 핸들러가 셸 없이 실행될 수 있도록 args 배열이 추가되었습니다. handler 필드는 더 이상 사용되지 않으며(deprecated), 셸에서 실행하려면 셸을 args에 포함해야 합니다(예: "args": ["sh", "-c", "..."]).
HTTP 엔드포인트 (HTTP endpoint)
HTTP 핸들러는 watch가 호출될 때 HTTP 요청을 보냅니다. JSON 호출 정보가 요청과 함께 페이로드로 전송됩니다. 응답에는 X-Consul-Index라는 헤더로 Consul index도 포함됩니다.
HTTP 핸들러는 handler_type을 http로 설정하여 구성할 수 있습니다. 추가 핸들러 옵션은 http_handler_config를 사용하여 설정합니다. 필수 매개변수는 HTTP 엔드포인트의 URL을 지정하는 path 필드뿐입니다. Consul은 기본 HTTP 메서드로 POST를 사용하지만 이 역시 구성할 수 있습니다. 기타 선택 필드는 header, timeout, tls_skip_verify입니다. watch 호출 데이터는 항상 JSON 페이로드로 전송됩니다.
다음은 구성 예시입니다.
에이전트 구성에 정의된 HTTP 핸들러가 있는 Consul watch
agent-config.hcl
watches = [
{
type = "key"
key = "foo/bar/baz"
handler_type = "http"
http_handler_config {
path = "https://localhost:8000/watch"
method = "POST"
header = {
x-foo = ["bar", "baz"]
}
timeout = "10s"
tls_skip_verify = false
}
}
]
전역 매개변수 (Global Parameters)
각 옵션 유형이 지원하는 매개변수 외에도 모든 watch가 지원하는 몇 가지 전역 매개변수가 있습니다.
datacenter- 에이전트의 기본 데이터센터를 재정의하는 데 제공할 수 있습니다.token- 에이전트의 기본 ACL 토큰을 재정의하는 데 제공할 수 있습니다.args- 데이터 뷰가 업데이트될 때 호출할 핸들러 하위 프로세스와 인자.handler- 데이터 뷰가 업데이트될 때 호출할 핸들러 셸 명령.
Watch 유형 (Watch Types)
다음 유형이 지원됩니다. 각각에 대한 자세한 문서는 아래에 있습니다.
key- 특정 KV 쌍 감시keyprefix- KV 스토어의 접두사 감시services- 사용 가능한 서비스 목록 감시nodes- 노드 목록 감시service- 서비스의 인스턴스 감시checks- 헬스 체크 값 감시event- 사용자 지정 사용자 이벤트 감시
유형: key
"key" watch 유형은 KV 스토어의 특정 키를 감시하는 데 사용됩니다. key 매개변수를 지정해야 합니다.
내부적으로 /v1/kv/ API에 매핑됩니다.
다음은 구성 예시입니다.
key watch 유형 예시
{
type = "key"
key = "foo/bar/baz"
args = ["/usr/bin/my-service-handler.sh", "-redis"]
}
또는 watch 명령을 사용합니다.
$ consul watch -type=key -key=foo/bar/baz /usr/bin/my-key-handler.sh
이 명령의 출력 예시:
{
"Key": "foo/bar/baz",
"CreateIndex": 1793,
"ModifyIndex": 1793,
"LockIndex": 0,
"Flags": 0,
"Value": "aGV5",
"Session": ""
}
유형: keyprefix
keyprefix watch 유형은 KV 스토어의 키 접두사를 감시하는 데 사용됩니다. prefix 매개변수를 지정해야 합니다. 이 watch는 접두사와 일치하는 어떤 키가 변경될 때마다 접두사와 일치하는 모든 키를 반환합니다.
내부적으로 /v1/kv/ API에 매핑됩니다.
다음은 구성 예시입니다.
keyprefix watch 유형 예시
{
type = "keyprefix"
prefix = "foo/"
args = ["/usr/bin/my-prefix-handler.sh", "-redis"]
}
또는 watch 명령을 사용합니다.
$ consul watch -type=keyprefix -prefix=foo/ /usr/bin/my-prefix-handler.sh
이 명령의 출력 예시:
[
{
"Key": "foo/bar",
"CreateIndex": 1796,
"ModifyIndex": 1796,
"LockIndex": 0,
"Flags": 0,
"Value": "TU9BUg==",
"Session": ""
},
{
"Key": "foo/baz",
"CreateIndex": 1795,
"ModifyIndex": 1795,
"LockIndex": 0,
"Flags": 0,
"Value": "YXNkZg==",
"Session": ""
},
{
"Key": "foo/test",
"CreateIndex": 1793,
"ModifyIndex": 1793,
"LockIndex": 0,
"Flags": 0,
"Value": "aGV5",
"Session": ""
}
]
유형: services
"services" watch 유형은 사용 가능한 서비스 목록을 감시하는 데 사용됩니다. 매개변수가 없습니다.
내부적으로 /v1/catalog/services API에 매핑됩니다.
다음은 구성 예시입니다.
services watch 유형 예시
{
type = "services"
args = ["/usr/bin/my-services-handler.sh"]
}
또는 watch 명령을 사용합니다.
$ consul watch -type=services /usr/bin/my-services-handler.sh
이 명령의 출력 예시:
{
"consul": [],
"redis": [],
"web": []
}
유형: nodes
"nodes" watch 유형은 사용 가능한 노드 목록을 감시하는 데 사용됩니다. 매개변수가 없습니다.
내부적으로 /v1/catalog/nodes API에 매핑됩니다.
다음은 구성 예시입니다.
nodes watch 유형 예시
{
type = "nodes"
args = ["/usr/bin/my-nodes-handler.sh"]
}
또는 watch 명령을 사용합니다.
$ consul watch -type=nodes /usr/bin/my-nodes-handler.sh
이 명령의 출력 예시:
[
{
"ID": "8d3088b5-ce7d-0b94-f185-ae70c3445642",
"Node": "nyc1-consul-1",
"Address": "192.0.2.10",
"Datacenter": "dc1",
"TaggedAddresses": null,
"Meta": null,
"CreateIndex": 23792324,
"ModifyIndex": 23792324
},
{
"ID": "1edb564e-65ee-9e60-5e8a-83eae4637357",
"Node": "nyc1-worker-1",
"Address": "192.0.2.20",
"Datacenter": "dc1",
"TaggedAddresses": {
"lan": "192.0.2.20",
"lan_ipv4": "192.0.2.20",
"wan": "192.0.2.20",
"wan_ipv4": "192.0.2.20"
},
"Meta": {
"consul-network-segment": "",
"host-ip": "192.0.2.20",
"pod-name": "hashicorp-consul-q7nth"
},
"CreateIndex": 23792336,
"ModifyIndex": 23792338
}
]
유형: service
"service" watch 유형은 단일 서비스의 공급자를 모니터링하는 데 사용됩니다. service 매개변수가 필요하며 선택적으로 tag와 passingonly 매개변수를 사용합니다. tag 매개변수는 하나 이상의 태그로 필터링합니다. 단일 문자열 값이거나 문자열 조각일 수 있습니다. passingonly 매개변수는 모든 헬스 체크를 통과하는 인스턴스만으로 필터링하는 불리언입니다.
내부적으로 /v1/health/service API에 매핑됩니다.
단일 태그가 있는 구성 예시:
service watch 유형 예시
{
type = "service"
service = "redis"
args = ["/usr/bin/my-service-handler.sh", "-redis"]
tag = "bar"
}
여러 태그가 있는 구성 예시:
여러 태그가 있는 service watch 유형 예시
{
type = "service"
service = "redis"
args = ["/usr/bin/my-service-handler.sh", "-redis"]
tag = ["bar", "foo"]
}
또는 watch 명령을 사용합니다.
단일 태그:
$ consul watch -type=service -service=redis -tag=bar /usr/bin/my-service-handler.sh
여러 태그:
$ consul watch -type=service -service=redis -tag=bar -tag=foo /usr/bin/my-service-handler.sh
이 명령의 출력 예시:
[
{
"Node": {
"ID": "f013522f-aaa2-8fc6-c8ac-c84cb8a56405",
"Node": "hashicorp-consul-server-1",
"Address": "192.0.2.50",
"Datacenter": "dc1",
"TaggedAddresses": null,
"Meta": null,
"CreateIndex": 23785783,
"ModifyIndex": 23785783
},
"Service": {
"ID": "redis",
"Service": "redis",
"Tags": [],
"Meta": null,
"Port": 6379,
"Address": "",
"Weights": {
"Passing": 1,
"Warning": 1
},
"EnableTagOverride": false,
"CreateIndex": 23785794,
"ModifyIndex": 23785794,
"Proxy": {
"MeshGateway": {},
"Expose": {}
},
"Connect": {}
},
"Checks": [
{
"Node": "hashicorp-consul-server-1",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "Agent alive and reachable",
"ServiceID": "",
"ServiceName": "",
"ServiceTags": [],
"Type": "",
"Definition": {
"Interval": "0s",
"Timeout": "0s",
"DeregisterCriticalServiceAfter": "0s",
"HTTP": "",
"Header": null,
"Method": "",
"Body": "",
"TLSServerName": "",
"TLSSkipVerify": false,
"TCP": "",
"TCPUseTLS": false,
"GRPC": "",
"GRPCUseTLS": false
},
"CreateIndex": 23785783,
"ModifyIndex": 23791503
}
]
}
]
유형: checks
"checks" watch 유형은 주어진 서비스 또는 특정 상태의 체크를 모니터링하는 데 사용됩니다. 선택적으로 service 매개변수로 특정 서비스로 필터링하거나 state 매개변수로 특정 상태로 필터링합니다. 기본적으로 모든 체크를 감시합니다.
상태별 모니터링 시 내부적으로 /v1/health/state/ API, 서비스별 모니터링 시 /v1/health/checks/ API에 매핑됩니다.
상태별 모니터링 구성 예시:
passing 상태의 모든 서비스에 대한 checks watch 유형 예시
{
type = "checks"
state = "passing"
args = ["/usr/bin/my-check-handler.sh", "-passing"]
}
서비스별 모니터링 구성 예시:
특정 서비스에 대한 checks watch 유형 예시
{
type = "checks"
service = "redis"
args = ["/usr/bin/my-check-handler.sh", "-redis"]
}
또는 watch 명령을 사용합니다.
상태:
$ consul watch -type=checks -state=passing /usr/bin/my-check-handler.sh -passing
서비스:
$ consul watch -type=checks -service=redis /usr/bin/my-check-handler.sh -redis
이 명령의 출력 예시:
[
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
]
유형: event
"event" watch 유형은 사용자 지정 사용자 이벤트를 모니터링하는 데 사용됩니다. 이 이벤트는 consul event 명령으로 발생시킵니다. watch를 지정된 이름의 이벤트로 제한하는 단일 선택 name 매개변수만 사용합니다.
내부적으로 /v1/event/list API에 매핑됩니다.
다음은 구성 예시입니다.
event watch 유형 예시
{
type = "event"
name = "web-deploy"
args = ["/usr/bin/my-event-handler.sh", "-web-deploy"]
}
또는 watch 명령을 사용합니다.
$ consul watch -type=event -name=web-deploy /usr/bin/my-event-handler.sh -web-deploy
이 명령의 출력 예시:
[
{
"ID": "f07f3fcc-4b7d-3a7c-6d1e-cf414039fcee",
"Name": "web-deploy",
"Payload": "MTYwOTAzMA==",
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 18
}
]
새로운 web-deploy 이벤트를 발생시키려면 다음을 사용할 수 있습니다.
$ consul event -name=web-deploy 1609030