작업 명세의 check 블록
작업 명세의 check 블록 (check block in the job specification)
| 배치 | job -> group -> service -> **check** |
| | job -> group -> task -> service -> **check** |
| | |
| | |
check 블록은 Nomad가 service와 연결된 체크를 Nomad 또는 Consul 서비스 제공자에 등록하도록 지시해요.
job "example" {
datacenters = ["dc1"]
group "cache" {
network {
port "db" { to = 6379 }
}
service {
provider = "nomad"
name = "redis"
port = "db"
check {
name = "redis_probe"
type = "tcp"
interval = "10s"
timeout = "1s"
}
}
task "redis" {
driver = "docker"
config {
image = "redis:7"
ports = ["db"]
}
}
}
}
출처: 문서
본문
매개변수 (Parameters)
address_mode(string: "host")— 이 서비스가 체크를 수행하는 데 사용할 주소(host, alloc, alloc IPv6 또는 드라이버별)를 지정해요.service의address_mode와 유사해요. 서비스가 Consul 제공자를 사용할 때, Consul은 HTTP나 TCP 체크에 대해 해당 주소에 접근할 수 있어야 해요.port와 달리 이 설정은service에서 상속되지 않아요. 서비스address가 설정되고 서비스address_mode가"auto"이며 체크address_mode가 설정되지 않았다면, Nomad는 체크 주소에 서비스address값을 사용해요.
유효한 옵션은:
-
alloc— 네트워크 네임스페이스를 만드는 할당의 경우, 이 주소 모드는 네임스페이스 안의 IP 주소를 사용해요. "bridge"와 "cni" 네트워킹 모드에서만 사용해요. 포트 매핑이 필요 없는 상황에서 숫자 포트를 지정할 수 있어요. "group" service 블록에 정의된 체크에만 이 모드를 설정해요. -
alloc_ipv6—alloc와 같지만 이중 스택 또는 IPv6 전용의 경우 IPv6 주소를 사용해요. -
driver— 드라이버가 지정한 IP와 포트 맵에 지정된 포트를 사용해요. 모든 네트워크 플러그인이 포트 맵을 요구하지 않으므로 숫자 포트를 지정할 수 있어요. SDN 및 오버레이 네트워크 주소를 확인하는 데 유용해요. 드라이버 네트워크를 결정할 수 없으면 태스크가 실패해요. Docker에서만 구현돼요. "task" service 블록에 정의된 체크에만 이 모드를 설정해요. 사용 예는 드라이버 주소 모드 사용을 참조하세요. -
host— 호스트 IP와 노출된 포트를 사용해요.
서비스와 달리 체크에는 "auto" 모드가 없다는 점에 유의하세요.
-
args(array<string>: [])—command에 대한 추가 인수를 지정해요. 이는 스크립트 기반 헬스 체크에만 적용돼요. -
check_restart—check_restart블록을 참조하세요. -
command(string: <varies>)— 헬스 체크를 수행하기 위해 실행할 명령을 지정해요. 스크립트는 다음으로 종료되어야 해요: 통과는 0, 경고는 1, 실패하는 헬스 체크는 다른 값. 이는 스크립트 기반 헬스 체크에 필요해요. Consul 서비스 제공자에서만 지원돼요.
주의사항: 명령은 디스크의 명령 경로여야 하며 기본적으로 셸이 존재하지 않아요. 즉 ||나 && 같은 연산자를 사용할 수 없어요. 또한 모든 인수는 args 매개변수를 통해 제공되어야 해요. 셸 연산자의 동작을 얻으려면 명령을 /bin/bash 같은 셸로 지정한 다음 args로 체크를 실행해요.
-
grpc_service(string: <optional>)— gRPC 헬스 체크에 지정할 서비스(있는 경우). gRPC 헬스 체크는 Consul 1.0.5 이상이 필요해요. -
grpc_use_tls(bool: false)— gRPC 헬스 체크를 수행할 때 TLS를 사용해요.tls_skip_verify와 함께 사용해 TLS는 사용하되 인증서 검증을 건너뛸 수 있어요.tls_server_name과 함께 사용해 SNI와 검사 중인 서버가 제시한 인증서의 검증에 사용할 ServerName을 지정할 수 있어요. -
initial_status(string: <enum>)— 서비스의 시작 상태를 지정해요. 유효한 옵션은passing,warning,critical이에요. 이 필드를 생략(또는 빈 문자열 제출)하면 Consul 기본 동작인critical이 돼요. Consul 서비스 제공자에서만 지원돼요. Nomad 서비스 제공자에서 체크의 초기 상태는 Nomad가 초기 체크 상태 결과를 생성할 때까지pending이에요. -
success_before_passing(int:0)— Consul이 서비스 상태를passing으로 전환하기 전에 필요한 연속 성공 체크 수. Consul 서비스 제공자에서만 지원되며 "script" 유형의 헬스 체크에는 적용되지 않아요. -
failures_before_critical(int:0)— Consul이 서비스 상태를critical로 전환하기 전에 필요한 연속 실패 체크 수. Consul 서비스 제공자에서만 지원되며 "script" 유형의 헬스 체크에는 적용되지 않아요. -
failures_before_warning(int:0)— Consul이 서비스 상태를warning으로 전환하기 전에 필요한 연속 실패 체크 수. Consul 서비스 제공자에서만 지원되며 "script" 유형의 헬스 체크에는 적용되지 않아요. -
interval(string: <required>)— Consul 또는 Nomad 서비스 제공자가 수행할 헬스 체크의 빈도를 지정해요. "30s"나 "1h" 같은 레이블 접미사를 사용해 지정해요. 이 값은 "1s"보다 크거나 같아야 해요. -
method(string: "GET")— HTTP 체크에 사용할 HTTP 메서드를 지정해요. 유효한 HTTP 메서드여야 해요. -
body(string: "")— HTTP 체크에 사용할 HTTP 본문을 지정해요. -
name(string: "service: <name> check")— 헬스 체크의 이름을 지정해요. 이름이 지정되지 않으면 Nomad가 서비스 이름에 기반해 생성해요. -
path(string: <varies>)— 서비스의 상태를 관찰하기 위해 조회될 HTTP 엔드포인트의 경로를 지정해요. Nomad가 서비스의 IP와 포트를 자동으로 추가하므로, 이는 헬스 체크 엔드포인트에 대한 상대 URL일 뿐이에요. HTTP 기반 헬스 체크에 필요해요. -
expose(bool: false)— 이 체크에 대해 Expose Path가 자동으로 생성되어야 하는지 지정해요. 기본 Connect 프록시를 사용하는 Connect 지원 태스크 그룹 서비스에서만 호환돼요. 설정하면 체크type이http또는grpc여야 하고 체크name이 설정되어야 해요. Consul 서비스 제공자에서만 지원돼요. -
port(string: <varies>)— 체크가 수행될 포트의 라벨을 지정해요. 이것은address_mode = driver가 아닌 한 포트 번호가 아니라 포트의 라벨 이라는 점에 유의하세요. 포트 라벨은network블록에 정의된 것과 일치해야 해요.service에 포트 값이 선언되었다면 제공하지 않았을 때 이 값을 상속해요. 제공되면 이 값이service.port값보다 우선해요. 여러 포트에서 작동하는 서비스에 유용해요.grpc,http,tcp체크는 포트가 필요하지만script체크는 필요 없어요. 체크는 기본적으로 호스트 IP와 포트를 사용해요. 체크에address_mode="driver"가 설정되면 숫자 포트를 사용할 수 있어요. -
protocol(string: "http")— HTTP 기반 헬스 체크의 프로토콜을 지정해요. 유효한 옵션은http와https예요. -
task(string: "")— 이 체크와 연결된 태스크를 지정해요. 스크립트는 태스크의 환경 안에서 실행되며check_restart블록은 지정된 태스크에 적용돼요. 설정되지 않으면service.task값을 상속해요. 태스크 수준 서비스에서는 설정되지 않거나service.task와 동일해야 해요. -
timeout(string: <required>)— 헬스 체크 조회가 성공하기까지 기다릴 시간을 지정해요. "30s"나 "1h" 같은 레이블 접미사를 사용해 지정해요. 이 값은 "1s"보다 크거나 같아야 해요.
주의사항: 스크립트 체크는 태스크 드라이버를 사용해 태스크 환경에서 실행돼요. docker나 exec 같은 네임스페이스 격리가 있는 태스크 드라이버의 경우, 스크립트 체크를 위한 컨텍스트 설정에 예기치 않게 오래 걸릴 수 있어요(약 1-2초), 특히 바쁜 호스트에서요. 타임아웃 구성은 이 설정과 스크립트 실행을 모두 허용해야 해요. 운영자는 스크립트 체크에 5초 이상의 긴 타임아웃을 사용하고 client.allocrunner.taskrunner.tasklet_timeout 텔레메트리를 모니터링해야 해요.
-
type(string: <required>)— Nomad가 지원하는 체크 유형을 나타내요. Consul 서비스 체크의 경우 유효한 옵션은grpc,http,script,tcp예요. Nomad 서비스 체크의 경우 유효한 옵션은http와tcp예요. -
tls_server_name(string: "")— TLS 활성 체크(https및grpc_use_tls가 있는grpc)를 수행할 때 SNI와 검사 중인 서버가 제시한 인증서의 검증에 사용할 ServerName을 나타내요. 지정하지 않으면 주소가 IP 주소가 아닌 한 ServerName이 검사 중인 서버의 주소에서 추론돼요. 여기서 유익한 두 가지 일반적인 경우가 있어요:- 체크 주소에 IP가 포함된 경우, SNI를 위해
tls_server_name을 지정할 수 있어요. 참고:tls_server_name을 설정하면 검사 중인 서버가 제시한 인증서를 검증하는 데 사용되는 호스트 이름도 덮어써요. - 체크 주소에 검사 중인 서버가 제시한 인증서의 SAN(Subject Alternative Name) 필드에 없는 호스트 이름이 포함된 경우. 참고:
tls_server_name을 설정하면 SNI에 사용되는 호스트 이름도 덮어써요.
- 체크 주소에 IP가 포함된 경우, SNI를 위해
이 필드는 Consul 서비스 제공자에서만 지원돼요.
-
tls_skip_verify(bool: false)—https및grpc_use_tls가 있는grpc체크에 대한 인증서 검증을 건너뛰어요. -
on_update(string: "require_healthy")— 배포 상태(작업의 초기 배포 포함)를 결정할 때 체크를 어떻게 평가해야 하는지 지정해요. 이를 통해 작업 제출자는 특정 체크를 준비(readiness) 체크로 정의해, 서비스의 체크가 아직 정상이 아니더라도 배포를 진행할 수 있어요. 체크는 기본적으로 서비스의 값을 상속해요. 체크 상태는 서비스 제공자에서 변경되지 않으며 업데이트 중 체크의 상태를 결정하는 데만 사용돼요.require_healthy— Nomad가 업데이트 중 체크를 정상으로 간주하려면 체크가 정상으로 보고되어야 해요.ignore_warnings— 서비스 체크가 warning으로 보고되면 Nomad는 체크를 정상으로 취급해요. 체크는 Consul에서 여전히 warning 상태로 유지돼요.ignore— 어떤 상태든 정상으로 취급돼요.
주의사항: on_update는 특정 check_restart 구성과만 호환돼요. on_update = "ignore_warnings"는 check_restart.ignore_warnings = true가 필요해요. check_restart는 on_update = "require_healthy"와 함께 ignore_warnings = true를 지정할 수 있어요. on_update가 ignore로 설정되면 check_restart는 완전히 생략해야 해요.
header 블록 (header block)
HTTP 체크는 HTTP 헤더를 설정하기 위해 header 블록을 포함할 수 있어요. header 블록 매개변수는 값으로 문자열 목록을 가져요. 여러 값은 각 값에 대해 헤더가 여러 번 설정되게 해요.
service {
# ...
check {
type = "http"
port = "lb"
path = "/_healthz"
interval = "5s"
timeout = "2s"
header {
Authorization = ["Basic ZWxhc3RpYzpjaGFuZ2VtZQ=="]
}
}
}
예제 (Examples)
HTTP 헬스 체크 (HTTP health check)
이 예제는 HTTP 헬스 체크가 있는 서비스를 보여줘요. 이는 Nomad에 등록된 IP와 포트에서 /_healthz를 5초마다 조회해 서비스에 응답을 반환할 최대 2초를 주며 Authorization 헤더를 포함해요. 2xx가 아닌 코드는 실패로 간주돼요.
service {
check {
type = "http"
port = "lb"
path = "/_healthz"
interval = "5s"
timeout = "2s"
header {
Authorization = ["Basic ZWxhc3RpYzpjaGFuZ2VtZQ=="]
}
}
}
여러 헬스 체크 (Multiple health checks)
이 예제는 여러 헬스 체크가 정의된 서비스를 보여줘요. 서비스가 정상으로 등록되려면 모든 헬스 체크가 통과해야 해요.
service {
check {
name = "HTTP Check"
type = "http"
port = "lb"
path = "/_healthz"
interval = "5s"
timeout = "2s"
}
check {
name = "HTTPS Check"
type = "http"
protocol = "https"
port = "lb"
path = "/_healthz"
interval = "5s"
timeout = "2s"
method = "POST"
}
check {
name = "Postgres Check"
type = "script"
command = "/usr/local/bin/pg-tools"
args = ["verify", "database", "prod", "up"]
interval = "5s"
timeout = "2s"
on_update = "ignore_warnings"
}
}
gRPC 헬스 체크 (gRPC health check)
gRPC 헬스 체크는 http와 tcp 체크와 동일한 호스트와 포트 동작을 사용하지만, gRPC 체크에는 헬스 체크할 선택적 gRPC 서비스도 있어요. 모든 gRPC 애플리케이션이 헬스 체크할 서비스를 요구하는 것은 아니에요.
service {
check {
type = "grpc"
port = "rpc"
interval = "5s"
timeout = "2s"
grpc_service = "example.Service"
grpc_use_tls = true
tls_skip_verify = true
}
}
이 예제에서 Consul은 태스크의 네트워크 리소스 블록에 정의된 rpc 포트에서 example.Service 서비스를 헬스 체크해요.
셸이 있는 스크립트 체크 (Script checks with shells)
스크립트 체크는 태스크 안에서 실행된다는 점에 유의하세요. 태스크가 Docker 컨테이너라면 스크립트가 Docker 컨테이너 안에서 실행돼요. 태스크가 chroot에서 실행 중이라면 chroot에서 실행돼요. 체크 스크립트를 작성할 때 이를 명심하세요.
이 예제는 셸에서 평가·보간되는 스크립트 체크가 있는 서비스를 보여줘요. ${HEALTH_CHECK_FILE} 환경 변수에 파일이 존재하는지 테스트해요:
service {
check {
type = "script"
command = "/bin/bash"
args = ["-c", "test -f ${HEALTH_CHECK_FILE}"]
}
}
${HEALTH_CHECK_FILE} 값을 보간하려면 여기서 /bin/bash(또는 다른 셸)를 사용해야 해요.
다음 command 필드의 예제들은 작동하지 않아요:
# invalid because command is not a path
check {
type = "script"
command = "test -f /tmp/file.txt"
}
# invalid because path will not be interpolated
check {
type = "script"
command = "/bin/test"
args = ["-f", "${HEALTH_CHECK_FILE}"]
}
정상성 대비 준비 체크 (Healthiness versus readiness checks)
서비스에 대한 여러 체크를 구성해 on_update를 설정함으로써 정상성(healthiness)과 준비(readiness) 체크를 만들 수 있어요.
service {
# This is a healthiness check that will be used to verify the service
# is responsive to tcp connections and behaving as expected.
check {
name = "connection_tcp"
type = "tcp"
port = 6379
interval = "10s"
timeout = "2s"
}
# This is a readiness check that is used to verify that, for example, the
# application has elected a leader by making a request to its /leader endpoint.
# Failures of this check are ignored during deployments.
check {
name = "leader_elected"
type = "http"
path = "/leader"
interval = "10s"
timeout = "2s"
on_update = "ignore"
}
}
Nomad 서비스 제공자에 등록된 체크의 경우, 상태 정보는 준비 체크에 대해 Mode = readiness를, 정상 체크에 대해 Mode = healthiness를 나타내요.
CLI에서 체크 상태 확인하기 (Check status on CLI)
Nomad 서비스 제공자에 등록된 체크의 경우 체크의 상태 정보를 할당별로 볼 수 있어요. alloc status 명령은 이제 Nomad 서비스 체크에 대한 요약 정보를 포함해요.
$ nomad alloc status <allocation-id>
Nomad Service Checks:
Service Task Name Mode Status
database task db_tcp_probe readiness success
web (group) healthz healthiness failure
web (group) index-page healthiness success
alloc checks 명령은 할당의 모든 체크에 대한 완전한 체크 상태 정보를 보는 데 사용할 수 있어요.
$ nomad alloc checks <allocation-id>
Status of 3 Nomad Service Checks
ID = d8651d93a50b9e28375a7beb9418c418
Name = db_tcp_probe
Group = example.group[0]
Task = task
Service = database
Status = success
Mode = readiness
Timestamp = 2022-08-22T10:41:23-05:00
Output = nomad: tcp ok
ID = 0413b61bda7014f02671675d7e146373
Name = index-page
Group = example.group[0]
Task = (group)
Service = web
Status = success
StatusCode = 200
Mode = healthiness
Timestamp = 2022-08-22T10:41:23-05:00
Output = nomad: http ok
ID = c3cce3f0c97975f84bbf39bdd50deaea
Name = healthz
Group = example.group[0]
Task = (group)
Service = web
Status = failure
Mode = healthiness
Timestamp = 2022-08-22T10:41:23-05:00
Output = nomad: Get "http://:9999/": dial tcp :9999: connect: connection refused
- 스크립트 체크는 QEMU 드라이버에 대해 지원되지 않아요. Nomad 클라이언트가 해당 드라이버의 태스크 파일시스템에 접근할 수 없기 때문이에요.