인덱스 축소 API

인덱스 축소 API (Shrink Index API)

1.0부터 도입되었어요.

인덱스 축소(Shrink Index) API는 샤드 수가 더 적은 새 대상 인덱스를 만들어 기존 인덱스의 프라이머리 샤드 수를 줄여요. 인덱스가 원래 과도하게 샤딩되었고 샤드를 통합해 리소스를 되찾거나 검색 성능을 개선하고 싶을 때 유용해요.

대상 인덱스의 프라이머리 샤드 수는 소스 인덱스의 프라이머리 샤드 수의 약수여야 해요. 예를 들어 프라이머리 샤드가 8개인 인덱스는 4개, 2개, 또는 1개의 프라이머리 샤드로 축소할 수 있어요. 소수(예: 7) 개의 샤드를 가진 인덱스는 1개의 프라이머리 샤드로만 축소할 수 있어요.

출처: 문서

본문

사전 요구 사항

인덱스를 축소하기 전에 다음 조건을 충족해야 해요:

인덱스가 읽기 전용이어야 해요. 인덱스를 읽기 전용으로 만들려면 동적 인덱스 수준 인덱스 설정 index.blocks.write를 true로 설정해요.
인덱스의 모든 샤드(프라이머리 또는 복제본)의 복사본이 같은 노드에 있어야 해요. 샤드 할당 필터링을 사용해 샤드를 같은 노드로 옮길 수 있어요.
클러스터 건강 상태가 green이어야 해요.

또한 축소 작업은 다음 제약을 적용해요:

대상 인덱스가 이미 존재하면 안 돼요.
소스 인덱스의 프라이머리 샤드 수가 대상 인덱스보다 많아야 해요.
대상 인덱스의 프라이머리 샤드 수는 소스 인덱스의 프라이머리 샤드 수의 약수여야 해요.
소스 인덱스는 단일 대상 샤드로 머지될 모든 샤드에 걸쳐 2,147,483,519개 이상의 문서를 포함할 수 없어요. 단일 Lucene 샤드가 담을 수 있는 최대 문서 수이기 때문이에요.
축소 과정을 처리하는 노드는 기존 인덱스의 두 번째 복사본을 수용할 충분한 여유 디스크 공간이 있어야 해요.

다음 요청은 모든 샤드를 단일 노드로 라우팅하고 쓰기 작업을 차단해 처음 세 가지 조건을 충족해요:

PUT /catalog-archive/_settings
{
  "settings": {
    "index.routing.allocation.require._name": "opensearch-node1",
    "index.blocks.write": true
  }
}

샤드 이전은 인덱스 크기에 따라 시간이 걸릴 수 있어요. CAT recovery API로 진행 상황을 추적하거나, Cluster Health API를 wait_for_no_relocating_shards 파라미터와 함께 사용해 완료를 기다릴 수 있어요.

축소 요청에는 매핑을 지정할 수 없어요. 대상 인덱스는 소스 인덱스의 모든 매핑을 상속해요.

축소 작업은 세 단계를 수행해요:

소스 인덱스와 같은 정의를 가지지만 프라이머리 샤드 수가 더 적은 새 대상 인덱스를 생성해요.
소스 인덱스 세그먼트에서 대상 인덱스로 하드 링크를 만들어요. 파일 시스템이 하드 링크를 지원하지 않으면 세그먼트를 새 인덱스에 물리적으로 복사하는데, 이는 훨씬 시간이 많이 걸리는 과정이에요.
닫힌 인덱스를 다시 열 때 적용되는 것과 같은 과정으로 대상 인덱스를 복구해요.

대상 인덱스를 만들 때 OpenSearch 인덱스 이름에는 다음 제한이 있다는 것을 기억해요:

모든 글자는 소문자여야 해요.
인덱스 이름은 밑줄(_)이나 하이픈(-)으로 시작할 수 없어요.
인덱스 이름에는 공백, 쉼표, 또는 다음 문자를 포함할 수 없어요:

:, ", *, +, /, \, |, ?, #, >, 또는 <

엔드포인트

POST /{index}/_shrink/{target}
PUT  /{index}/_shrink/{target}

경로 파라미터

사용할 수 있는 경로 파라미터는 아래 표와 같아요.

파라미터	필수	데이터 타입	설명
`index`	필수	String	축소할 소스 인덱스의 이름이에요.
`target`	필수	String	생성할 대상 인덱스의 이름이에요.

쿼리 파라미터

사용할 수 있는 쿼리 파라미터는 아래 표와 같아요. 모든 쿼리 파라미터는 선택사항이에요.

파라미터	데이터 타입	설명	기본값
`wait_for_active_shards`	String	OpenSearch가 응답을 반환하기 전에 사용할 수 있어야 하는 활성 샤드 복사본 수예요. 축소 작업은 새 인덱스를 만들기 때문에 인덱스 생성 시의 wait for active shards 설정이 여기에도 적용돼요. `all` 또는 양의 정수로 설정해요. 1보다 큰 값은 복제본이 필요해요. 예를 들어 값을 3으로 지정하면 요청이 성공하려면 인덱스에 두 개의 추가 노드에 분산된 복제본 두 개가 있어야 해요.	`1`
`cluster_manager_timeout`	String	클러스터 매니저 노드에 연결될 때까지 기다리는 시간이에요.	`30s`
`timeout`	String	응답을 기다리는 시간이에요. 시간 초과 전에 응답을 받지 못하면 요청이 실패하고 오류를 반환해요.	`30s`
`wait_for_completion`	Boolean	`false`로 설정하면 작업이 끝난 후가 아니라 즉시 요청이 반환돼요. 작업 상태를 모니터링하려면 요청이 반환한 작업 ID와 함께 Tasks API를 사용해요.	`true`
`task_execution_timeout`	String	작업이 완료될 때까지 기다리는 시간이에요. `wait_for_completion`이 `false`로 설정된 경우에만 적용돼요.	`1h`

요청 본문 필드

사용할 수 있는 요청 본문 필드는 아래 표와 같아요. 모든 필드는 선택사항이에요.

필드	데이터 타입	설명
`settings`	Object	대상 인덱스에 적용할 인덱스 설정이에요. Index settings를 참고해요.
`aliases`	Object	대상 인덱스와 연결할 별칭이에요. Alias APIs를 참고해요.
`max_shard_size`	String	대상 인덱스에서 프라이머리 샤드의 최대 크기예요. OpenSearch는 총 저장 공간과 이 제한을 바탕으로 최적의 샤드 수를 계산해요. `index.number_of_shards`와 함께 사용할 수 없어요. `max_shard_size` 파라미터를 참고해요.

`max_shard_size` 파라미터

max_shard_size 파라미터는 대상 인덱스에서 프라이머리 샤드의 최대 크기를 지정해요. OpenSearch는 max_shard_size와 소스 인덱스의 모든 프라이머리 샤드의 총 저장 공간을 사용해 대상 인덱스의 프라이머리 샤드 수와 크기를 계산해요.

대상 인덱스의 프라이머리 샤드 수는 샤드 크기가 max_shard_size를 초과하지 않는 소스 인덱스 프라이머리 샤드 수의 가장 작은 약수예요. 예를 들어 소스 인덱스에 총 400GB 저장 공간을 차지하는 프라이머리 샤드가 8개 있고 max_shard_size가 150GB라면, OpenSearch는 다음 단계로 프라이머리 샤드 수를 계산해요:

최소 프라이머리 샤드 수를 400/150으로 계산하고 가장 가까운 정수로 반올림해요. 최소 프라이머리 샤드 수는 3이에요.
8의 약수 중 3보다 크거나 같은 가장 작은 값을 찾아요. 프라이머리 샤드 수는 4예요.

대상 인덱스의 최대 프라이머리 샤드 수는 소스 인덱스의 프라이머리 샤드 수와 같아요. 예를 들어 소스 인덱스에 600GB를 차지하는 프라이머리 샤드가 5개 있고 max_shard_size가 100GB라면 최소값은 600/100 = 6이에요. 6이 소스 샤드 수인 5를 초과하므로 대상은 5개의 프라이머리 샤드를 유지해요.

대상 인덱스의 최소 프라이머리 샤드 수는 1이에요.

축소 과정 모니터링

인덱스 축소 API는 대상 인덱스가 클러스터 상태에 추가되자마자 반환돼요 — 축소 작업이 완료될 때까지 기다리지 않아요. 축소 과정은 다음 샤드 상태를 거쳐 진행돼요:

Unassigned : 대상 인덱스의 모든 샤드는 API가 반환된 직후 이 상태로 시작해요.
Initializing : 프라이머리 샤드가 축소 노드에 할당되면 이 상태로 전환되고 데이터 통합이 시작돼요.
Active : 축소가 완료되면 샤드가 활성 상태가 돼요. 그러면 OpenSearch가 구성된 복제본을 할당하려 시도하고, 균형을 맞추기 위해 프라이머리 샤드를 다른 노드로 옮길 수도 있어요.

샤드 복구 진행 상황은 CAT recovery API로 추적하거나, Cluster Health API를 wait_for_status=yellow와 함께 사용해 모든 프라이머리 샤드가 할당될 때까지 기다릴 수 있어요.

인덱스 코덱 고려 사항

인덱스 코덱 고려 사항은 Index codecs를 참고해요.

예시: 인덱스 축소

다음 예제는 catalog-archive 인덱스를 4개의 프라이머리 샤드에서 2개로 축소하고, 소스에서 복사된 할당 요구 사항과 쓰기 블록을 지우고, 별칭을 연결해요:

POST /catalog-archive/_shrink/catalog-archive-shrunk
{
  "settings": {
    "index.number_of_shards": 2,
    "index.number_of_replicas": 0,
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null
  },
  "aliases": {
    "catalog-current": {}
  }
}

예시: `max_shard_size`로 축소

정확한 샤드 수를 지정하는 대신 최대 샤드 크기를 기준으로 OpenSearch가 최적의 샤드 수를 결정하게 할 수 있어요. 다음 예제는 어떤 프라이머리 샤드도 100MB를 초과하지 않도록 catalog-source 인덱스를 축소해요:

POST /catalog-source/_shrink/catalog-source-compact
{
  "max_shard_size": "100mb",
  "settings": {
    "index.number_of_replicas": 0,
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null
  }
}

응답 예시

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "catalog-archive-shrunk"
}

응답 본문 필드

모든 응답 본문 필드는 아래 표와 같아요.

필드	데이터 타입	설명
`acknowledged`	Boolean	클러스터의 관련 노드들이 요청을 승인했는지 여부를 나타내요.
`shards_acknowledged`	Boolean	요청이 시간 초과되기 전에 필요한 수의 샤드 복사본이 시작되었는지 여부를 나타내요.
`index`	String	생성된 대상 인덱스의 이름이에요.

필요한 권한

보안 플러그인을 사용한다면 다음 권한이 필요해요: indices:admin/resize.

더 알아보기 (Learn more)

OpenSearch 공식 문서

인덱스 축소 API