클러스터 상태 API

클러스터 상태 API (Cluster Health API)

클러스터가 지금 정상인지 한눈에 확인하고 싶으시죠? 클러스터 상태 API가 클러스터의 운영 상태를 빠르게 보여줘요. OpenSearch는 샤드 할당 상태를 나타내는 세 가지 색으로 클러스터 상태를 표현해요.

출처: 문서

본문

1.0에서 도입

클러스터 상태 API는 클러스터의 운영 상태를 빠르게 보여줘요. OpenSearch는 샤드 할당 상태를 나타내는 세 가지 색으로 클러스터 상태를 표현해요.

• Green(최상): 모든 primary 샤드와 그 replica가 노드에 할당됐어요. 클러스터가 완전히 운영 중이에요.
• Yellow: 모든 primary 샤드가 할당됐지만 일부 replica 샤드가 unassigned 상태예요. 클러스터는 운영되지만 완전히 중복되지는 않아요.
• Red(최악): primary 샤드가 하나 이상 unassigned 상태예요. 일부 데이터를 사용할 수 없고, 검색 결과가 불완전할 수 있어요.

전반적인 상태를 결정할 때 최악의 상태가 우선해요. 여러 인덱스에 대해 상태를 요청하면 전체 상태는 최악의 인덱스 상태에 의해 결정돼요. 마찬가지로 인덱스 상태는 그 안에서 최악의 샤드 상태에 의해 결정돼요.

엔드포인트

GET /_cluster/health
GET /_cluster/health/{index}

경로 파라미터

다음 표는 사용 가능한 경로 파라미터예요. 모든 경로 파라미터는 선택적이에요.

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터예요. 모든 쿼리 파라미터는 선택적이에요.

예시 요청: 모든 인덱스의 클러스터 상태 검색

다음 요청은 클러스터의 모든 인덱스에 대한 클러스터 상태를 검색해요.

GET /_cluster/health

예시 응답

응답에 클러스터 상태 정보가 포함돼요.

{
  "cluster_name" : "opensearch-cluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "discovered_master" : true,
  "discovered_cluster_manager" : true,
  "active_primary_shards" : 138,
  "active_shards" : 138,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 110,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 55.64516129032258
}

응답이 yellow 상태를 보여주는 이유는 이것이 할당할 수 없는 replica 샤드가 있는 단일 노드 클러스터이기 때문이에요. timed_out 필드가 false라서 응답이 기본 타임아웃 기간 내에 반환됐음을 나타내요.

예시 요청: 특정 상태 대기하기

다음 요청은 클러스터가 yellow 상태 이상에 도달할 때까지 50초를 기다려요.

GET /_cluster/health?wait_for_status=yellow&timeout=50s

클러스터 상태가 50초가 경과하기 전에 yellow나 green이 되면 요청은 즉시 응답을 반환해요. 그렇지 않으면 타임아웃을 초과하는 즉시 응답을 반환해요.

예시 요청: awareness 속성별 클러스터 상태 검색

awareness 속성(예: zone 또는 rack)별로 클러스터 상태를 확인하려면 level 쿼리 파라미터에 awareness_attributes를 지정해요.

GET /_cluster/health?level=awareness_attributes

응답에 awareness 속성별로 분할된 클러스터 상태 지표가 포함돼요.

{
  "cluster_name": "runTask",
  "status": "green",
  "timed_out": false,
  "number_of_nodes": 3,
  "number_of_data_nodes": 3,
  "discovered_master": true,
  "discovered_cluster_manager": true,
  "active_primary_shards": 0,
  "active_shards": 0,
  "relocating_shards": 0,
  "initializing_shards": 0,
  "unassigned_shards": 0,
  "delayed_unassigned_shards": 0,
  "number_of_pending_tasks": 0,
  "number_of_in_flight_fetch": 0,
  "task_max_waiting_in_queue_millis": 0,
  "active_shards_percent_as_number": 100,
  "awareness_attributes": {
    "zone": {
      "zone-3": {
        "active_shards": 0,
        "initializing_shards": 0,
        "relocating_shards": 0,
        "unassigned_shards": 0,
        "data_nodes": 1,
        "weight": 1
      },
      "zone-1": {
        "active_shards": 0,
        "initializing_shards": 0,
        "relocating_shards": 0,
        "unassigned_shards": 0,
        "data_nodes": 1,
        "weight": 1
      },
      "zone-2": {
        "active_shards": 0,
        "initializing_shards": 0,
        "relocating_shards": 0,
        "unassigned_shards": 0,
        "data_nodes": 1,
        "weight": 1
      }
    },
    "rack": {
      "rack-3": {
        "active_shards": 0,
        "initializing_shards": 0,
        "relocating_shards": 0,
        "unassigned_shards": 0,
        "data_nodes": 1,
        "weight": 1
      },
      "rack-1": {
        "active_shards": 0,
        "initializing_shards": 0,
        "relocating_shards": 0,
        "unassigned_shards": 0,
        "data_nodes": 1,
        "weight": 1
      },
      "rack-2": {
        "active_shards": 0,
        "initializing_shards": 0,
        "relocating_shards": 0,
        "unassigned_shards": 0,
        "data_nodes": 1,
        "weight": 1
      }
    }
  }
}

특정 awareness 속성이 궁금하다면 awareness 속성 이름을 쿼리 파라미터로 포함할 수 있어요.

GET /_cluster/health?level=awareness_attributes&awareness_attribute=zone

위 요청에 대한 응답으로 OpenSearch는 zone awareness 속성에 대해서만 클러스터 상태 정보를 반환해요.

unassigned 샤드 정보는 awareness 속성에 대해 replica 수 강제(replica count enforcement)와 forced awareness를 클러스터 시작 전이나 클러스터 시작 후지만 인덱싱 요청 전에 구성한 경우에만 정확해요. 클러스터가 인덱싱 요청을 받은 후 replica enforcement를 활성화하면 unassigned 샤드 정보가 부정확할 수 있어요. replica 수 강제와 forced awareness를 구성하지 않으면 unassigned_shards 필드에 -1이 포함돼요.

응답 본문 필드

다음 표는 모든 응답 필드예요.

보안

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인해야 해요: cluster:monitor/health.

더 알아보기 (Learn more)

• 샤드 할당 이유를 자세히 보려면 Cluster Allocation Explain API를 참고하세요.
• awareness_attribute 파라미터와 클러스터 상태의 level 조합으로 zone/rack 단위 상태를 확인할 수 있어요.