서비스 Health 보고

Health는 서비스 복제본의 운영 상태를 보고하는 고급 기능이며 Beta입니다. 일반 제공 기능이 아니므로 사용하려면 Palantir 담당자에게 활성화와 사용 조건을 확인해야 합니다. 프로세스의 생존 상태나 트래픽을 받을 준비 상태와 구분하여, 복구 작업, 디스크 부족, 데이터 일관성 문제 같은 애플리케이션 상태를 표현합니다.

여기서 사용하는 Health 명세는 버전 2입니다. 응답 JSON 자체에는 명세 버전 필드를 넣지 않습니다.

상태 수집 조건

스포크의 expected-state-k8s는 클러스터 상태와 Health를 수집하여 허브로 보냅니다. 사용자 정의 Health를 보고하려면 클러스터에 이 서비스가 설치되어 있어야 합니다. Apollo로 설치한 개체의 Pod에서 apollo.palantir.com/health.probe 어노테이션을 발견하면 해당 위치를 조회합니다.

Helm 차트의 Deployment 또는 StatefulSet에서 spec.template.metadata.annotations에 어노테이션을 넣습니다. 다음은 기존 Deployment에 추가할 구성 조각입니다. 전체 Deployment 명세를 대신하지 않습니다.

kind: Deployment
metadata:
  name: test-deployment
spec:
  template:
    metadata:
      annotations:
        apollo.palantir.com/health.probe: '{"containerProbes":{"test-container":{"path":"/telemetry","port":"8446"}}}'

예시 컨테이너 이름은 test-container이고, 실제 상태 엔드포인트는 8446 포트의 /telemetry/status/health입니다.

값	의미
`containerProbes`의 키	Health 엔드포인트를 제공하는 실제 컨테이너 이름
`path`	`/status/health` 앞의 컨텍스트 경로. 예를 들어 `/hello-world/status/health`이면 `/hello-world`이고, 직접 `/status/health`를 제공하면 `/`
`port`	해당 엔드포인트를 제공하는 포트

모든 조회는 HTTPS를 사용하므로 엔드포인트가 TLS 암호화 트래픽을 받아야 합니다.

클러스터 방화벽이나 NetworkPolicy 구성에 따라 스포크 제어 플레인에서 애플리케이션 Pod로 접근하도록 허용해야 합니다. 아래는 네임스페이스 단위로 통신을 허용하는 예시입니다. YOUR_APP_NAMESPACE와 APOLLO_CONTROL_PLANE_NAMESPACE는 실제 네임스페이스로 바꿉니다. 이 예시는 포트 제한을 두지 않으므로 조직의 네트워크 정책에 맞게 적용 범위를 검토해야 합니다.

애플리케이션 네임스페이스의 수신 허용 예시입니다.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-ingress-policy
  namespace: YOUR_APP_NAMESPACE
spec:
  podSelector:
    matchLabels:
      apollo.palantir.com/status.liveness_and_readiness: ""
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: APOLLO_CONTROL_PLANE_NAMESPACE

스포크 제어 플레인 네임스페이스의 송신 허용 예시입니다.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-egress-policy
  namespace: APOLLO_CONTROL_PLANE_NAMESPACE
spec:
  podSelector:
    matchLabels:
      apollo.palantir.com/status.liveness_and_readiness: ""
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: YOUR_APP_NAMESPACE

Pod 선택에 사용한 apollo.palantir.com/status.liveness_and_readiness: ""는 관리되는 Pod에 Apollo가 자동으로 추가하는 레이블입니다. 네임스페이스 이름과 실제 수집 Pod의 레이블이 정책 대상과 일치해야 합니다.

복제본 상태

각 복제본은 여러 독립 점검을 보고할 수 있습니다. 복제본의 전체 Health는 점검 중 가장 심각한 상태이며, 심각도는 다음 순서로 증가합니다.

상태	의미
`HEALTHY`	복제본이 문제없이 동작합니다.
`REPAIRING`	성능이나 기능이 저하되었지만 스스로 복구할 수 있습니다. 이때 복제본을 재시작하면 진행 중인 상태 전환이 실패할 수 있습니다. 예를 들어 Cassandra의 첫 부트스트랩 중 자신이나 다른 복제본이 재시작되면 부트스트랩이 실패할 수 있습니다.
`WARNING`	조치하지 않으면 `ERROR`로 진행할 것으로 예상되는 상태입니다.
`ERROR`	복제본의 운영 상태가 비정상입니다.

REPAIRING은 즉시 재시작해야 한다는 신호가 아닙니다. 복구 작업이 진행 중이라는 의미와 재시작의 영향을 함께 고려합니다.

엔드포인트 계약

서비스는 GET을 받는 REST 엔드포인트 하나로 전체 점검을 반환합니다.

5초마다 호출해도 서비스 성능에 영향을 주지 않아야 합니다. 비용이 큰 점검은 내부에서 결과를 캐시하여 더 낮은 빈도로 수행합니다.
설정한 상태 엔드포인트의 컨텍스트 경로 아래 /status/health를 제공합니다. 형태는 https://<host>:<port>/<context>/status/health입니다.
오픈 소스 소프트웨어에 사이드카를 붙이는 경우 주 서비스와 다른 포트를 사용할 수 있습니다. Palantir가 개발한 소프트웨어는 주 포트를 사용하도록 권장합니다.
Health가 ERROR여도 정상적인 점검 응답은 HTTP 200 OK를 반환합니다. HTTP 5xx는 점검 실행 중 내부 서버 오류로 해석하며 Health의 ERROR와 동등하게 처리합니다.

JSON 응답

최상위 checks는 점검 유형에서 Check 객체로의 맵입니다. 각 키는 해당 객체의 type과 일치해야 합니다.

Check 필드	자료형과 요구사항
`type`	비어 있지 않은 문자열입니다. 공백 없이 ASCII 대문자와 밑줄만 사용합니다.
`state`	`HEALTHY`, `REPAIRING`, `WARNING`, `ERROR` 중 하나입니다.
`message`	알림에서 조치할 수 있을 만큼 상태를 설명하는 문자열입니다. 환경 밖으로 전달해도 안전하도록 민감한 정보를 제거합니다.
`params`	추가 정보를 담는 `map<string, any>`입니다. 이 값도 환경 밖으로 전달해도 안전해야 합니다.

전체 응답은 10,000바이트보다 작아야 합니다. 한도를 넘으면 보고 인프라가 저장 전에 점검 메시지와 매개변수를 제거할 수 있습니다. 길이 때문에 응답을 수정하면 HEALTH_CHECK_MAX_LEN 점검을 WARNING 상태로 추가합니다.

아래는 각 상태를 보여 주는 독립적인 응답 예시입니다. 시간과 건수는 예시 값입니다.

정상

{
  "checks": {
    "SOME_BACKGROUND_JOB": {
      "type": "SOME_BACKGROUND_JOB",
      "state": "HEALTHY",
      "message": "Job running healthy",
      "params": {
        "lastSuccessTimestamp": 1052240400,
        "itemsProcessed": 9001
      }
    }
  }
}

복구 중

{
  "checks": {
    "REPAIR": {
      "type": "REPAIR",
      "state": "REPAIRING",
      "message": "Currently running repair"
    }
  }
}

경고

{
  "checks": {
    "DISK_CAPACITY": {
      "type": "DISK_CAPACITY",
      "state": "WARNING",
      "message": "low disk capacity available. 25% available, but compactions may require up to 30%"
    }
  }
}

오류

{
  "checks": {
    "QUORUM_READ_AND_WRITE": {
      "type": "QUORUM_READ_AND_WRITE",
      "state": "ERROR",
      "message": "Failed quorum reads. Unable to ensure data consistency"
    }
  }
}

팔란티어 플랫폼 한국어 해설