MachineHealthCheck 설정

1 개요

Configure a MachineHealthCheck

MachineHealthCheck 설정

• https://cluster-api.sigs.k8s.io/tasks/automated-machine-management/healthchecking

2 사전 준비

MachineHealthCheck를 구성하기 전에, 최소 한 개 이상의 MachineDeployment 또는 MachineSet이 배포된 작동 중인 관리 클러스터가 있어야 한다.

중요 현재 MachineHealthCheck는 MachineSet 또는 KubeadmControlPlane이 소유한 Machine만 지원한다. 전체 제한 사항은 MachineHealthCheck의 제한사항 및 주의 사항을 확인한다.

3 MachineHealthCheck란?

MachineHealthCheck는 Cluster API 리소스로, 클러스터 내 Machine이 비정상으로 간주되어야 하는 조건을 정의할 수 있다. MachineHealthCheck는 관리 클러스터에 생성되며 특정 워크로드 클러스터에 범위가 지정된다.

MachineHealthCheck를 정의할 때, 사용자는 Machine이 생성한 Node의 상태 조건마다 타임아웃을 지정한다. 지정된 조건이 해당 타임아웃 동안 충족되면 해당 Machine은 복구(remediation) 대상이 된다. 기본적으로 복구는 실패한 Machine을 대체할 새 Machine을 생성하도록 트리거되지만, 인프라 제공자는 보다 고급의 외부 복구 방식을 플러그인할 수 있다.

4 MachineHealthCheck 만들기

다음 예시는 워커 노드용 MachineHealthCheck의 기본 예시이다.

apiVersion: cluster.x-k8s.io/v1beta2
kind: MachineHealthCheck
metadata:
  name: capi-quickstart-node-unhealthy-5m
spec:
  # 특정 클러스터와 이 MachineHealthCheck를 연관시키기 위해 필수
  clusterName: capi-quickstart
  # (선택) 클러스터가 이미 일부 비정상인 경우 추가 복구를 차단
  maxUnhealthy: 40%
  # (선택) Node가 클러스터에 조인할 때까지 대기할 시간
  # 지정하지 않으면 기본 10분. 0으로 설정하면 비활성화.
  nodeStartupTimeout: 10m
  # 라벨 셀렉터로 헬스 체크 대상 Machine을 결정
  selector:
    matchLabels:
      nodepool: nodepool-0
  # Node 조건: 지정 시간 동안 일치하면 해당 Machine은 비정상
  unhealthyNodeConditions:
  - type: Ready
    status: Unknown
    timeout: 300s
  - type: Ready
    status: "False"
    timeout: 300s
  # Machine 조건: 지정 시간 동안 일치하면 비정상
  unhealthyMachineConditions:
  - type: "Ready"
    status: Unknown
    timeout: 300s
  - type: "Ready"
    status: "False"
    timeout: 300s

KubeadmControlPlane로 관리되는 컨트롤 플레인 노드용 MachineHealthCheck 예시는 다음과 같다.

apiVersion: cluster.x-k8s.io/v1beta2
kind: MachineHealthCheck
metadata:
  name: capi-quickstart-kcp-unhealthy-5m
spec:
  clusterName: capi-quickstart
  maxUnhealthy: 100%
  selector:
    matchLabels:
      cluster.x-k8s.io/control-plane: ""
  unhealthyNodeConditions:
    - type: Ready
      status: Unknown
      timeout: 300s
    - type: Ready
      status: "False"
      timeout: 300s

중요 같은 클러스터에 대해 둘 이상의 MachineHealthCheck를 정의한다면, 셀렉터가 서로 겹치지 않도록 하여 복구 충돌이나 예기치 않은 동작을 방지한다.

5 복구 재시도 제어

중요 이 기능은 KubeadmControlPlane에만 적용된다.

KubeadmControlPlane은 선택적 remediationStrategy로 복구 방식을 제어할 수 있다. 이는 예를 들어 할당량 문제로 인한 불필요한 인프라 부하를 방지하거나, 일시적 문제 후 인프라가 안정화될 시간을 주는 데 유용하다.

apiVersion: cluster.x-k8s.io/v1beta2
kind: KubeadmControlPlane
metadata:
  name: my-control-plane
spec:
  ...
  remediationStrategy:
    maxRetry: 5
    retryPeriod: 2m
    minHealthyPeriod: 2h

- maxRetry: 비정상 Machine을 복구하는 동안 허용되는 최대 재시도 횟수다. 새로 생성된 대체 Machine도 실패할 경우 재시도가 발생한다.

 예: 컨트롤 플레인 M1, M2, M3가 있을 때
 - M1이 비정상이 되어 복구가 실행되고 대체 M1-1이 생성된다.
 - M1-1이 부팅 문제로 비정상이 되면 재복구가 일어나며, 이는 재시도 #1로 계산한다.
 - M1-2가 또 비정상이 되면 재시도 #2가 된다.

- retryPeriod: 이전 재시도 이후 다음 재시도까지 대기할 시간이다. 설정하지 않으면 즉시 재시도한다. - minHealthyPeriod: 이전 복구 이후 이 기간(기본 1시간)이 지나고 새 문제가 발생하면, 이전 문제와 무관한 것으로 간주하여 재시도로 계산하지 않는다. - maxRetry를 설정하지 않으면(기본값) 무한히 재시도한다.

참고: maxRetry 소진 후 다시 시도하기 maxRetry를 모두 소진했더라도 다시 복구를 시도하려면 다음 중 하나를 사용한다. - 일시적으로 maxRetry 값을 늘린다(권장). - 비정상 Machine에서 controlplane.cluster.x-k8s.io/remediation-for 어노테이션을 제거하거나 해당 값의 retryCount를 줄인다.

6 복구 단락(Short-Circuiting)

클러스터가 건강하지 않을 때 무분별한 복구를 방지하기 위해, MachineHealthCheck는 spec의 maxUnhealthy 및 unhealthyRange를 통해 복구를 단락한다.

6.1 Max Unhealthy

maxUnhealthy에 절대값 또는 퍼센트를 지정하면, 복구 전에 현재 비정상 Machine 수와 비교하여 한도를 초과하면 복구를 수행하지 않는다.

경고 maxUnhealthy의 기본값은 100%다. 즉, 기본적으로 단락 메커니즘은 비활성화되어 상태와 무관하게 복구가 실행된다.

6.1.1 절대값 예시

maxUnhealthy=2일 때: - 비정상이 2대 이하 → 복구 수행 - 비정상이 3대 이상 → 복구 미수행 전체 대상 Machine 수와 관계없이 동작한다.

6.1.2 퍼센트 예시

대상 Machine이 25대이고 maxUnhealthy=40%: - 비정상 10대 이하 → 복구 수행 - 11대 이상 → 복구 미수행

대상 Machine이 6대이고 maxUnhealthy=40%: - 비정상 2대 이하 → 복구 수행 - 3대 이상 → 복구 미수행

퍼센트 계산 결과가 정수가 아니면 내림(버림)한다.

6.2 Unhealthy Range

unhealthyRange에 구간([시작-끝])을 지정하면, 현재 비정상 Machine 수가 해당 구간 안에 있을 때만 복구한다. 구간 밖이면 복구하지 않는다.

중요 maxUnhealthy와 unhealthyRange를 모두 지정한 경우, unhealthyRange가 우선한다.

6.2.1 구간 예시

대상 Machine 10대, unhealthyRange=[3-5]: - 비정상 2대 이하 → 복구 안 함 - 비정상 6대 이상 → 복구 안 함 - 그 외(3~5대) → 복구 수행

이 로직은 대상 수가 동적으로 변해도 동일하게 적용된다.

7 복구 건너뛰기

다음 조건 중 하나라도 만족하면 해당 Machine은 복구 대상에서 제외한다(예: clusterctl move 중).

• Machine에 cluster.x-k8s.io/skip-remediation 어노테이션이 있다.
• Machine에 cluster.x-k8s.io/paused 어노테이션이 있다.
• MachineHealthCheck에 cluster.x-k8s.io/paused 어노테이션이 있다.
• Cluster의 .spec.paused가 true이다.

8 MachineHealthCheck의 제한사항 및 주의 사항

- MachineSet 또는 KubeadmControlPlane이 소유한 Machine만 복구된다(MachineDeployment 관리 Machine은 내부적으로 MachineSet이므로 포함한다). - KubeadmControlPlane이 관리하는 Machine은 제안서의 삭제-재생성 지침에 따라 복구된다.

 - 다음 중 하나를 만족해야 복구를 시작한다.
   - 클러스터가 아직 초기화되지 않았다(KCP가 initialized 상태에 도달하기 전 실패).
   - 컨트롤 플레인 Machine이 최소 2대 이상이다(복구 가능한 최소 규모).
 - 이전 복구(삭제 및 재생성)가 완료되어 있어야 한다(이전 대체 Machine 미생성 상태에서 추가 복구 금지).
 - 삭제 타임스탬프가 있는 Machine이 없어야 한다(과도기 상태에서 조치 금지).
 - etcd 정족수(quorum)를 유지해야 한다(초기화된 CP에서 관리형 etcd인 경우 다수파 상실 방지).

- Machine의 Node가 클러스터에서 제거되면, MachineHealthCheck는 해당 Machine을 즉시 비정상으로 간주하고 복구한다. - NodeStartupTimeout 동안 해당 Machine의 Node가 조인하지 않으면, 해당 Machine을 복구한다. - 중요: etcd 리더 멤버가 있는 노드의 kubelet이 동작하지 않으면, KCP가 리더에서 수행해야 하는 특정 체크가 불가능해져 복구가 차단될 수 있다. 이 경우 일시적으로 리더십을 다른 etcd 멤버로 전환하고 해당 Machine을 수동으로 삭제하는 것을 권장한다. 관련 논의: https://github.com/kubernetes-sigs/cluster-api/issues/8465

9 참고

- 관리 클러스터 정의: https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/reference/glossary.md#management-cluster - KubeadmControlPlane 복구 제안서: https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20191017-kubeadm-based-control-plane.md#remediation-using-delete-and-recreate