인덱스 복제 API

인덱스 복제 API (Clone Index API)

1.0에서 도입되었어요. clone index API는 기존 인덱스를 새 인덱스로 복제해요. 이때 원본의 각 프라이머리 샤드는 대상 인덱스의 새 프라이머리 샤드로 복제돼요.

이 API는 다음과 같은 상황에서 사용해요.

  • 파괴적인 변경을 하기 전에 같은 수의 샤드를 가진 인덱스의 백업 복사본을 만들 때
  • 원본 인덱스를 보존하면서 복제된 복사본에 설정 변경을 테스트할 때
  • 서로 다른 설정이나 별칭을 가진 병렬 처리 워크플로를 위해 인덱스를 복제할 때

clone 작업은 인덱스 데이터를 효율적으로 복제하기 위해 세 단계로 진행돼요.

  1. OpenSearch가 매핑과 설정을 포함해 원본 인덱스와 같은 정의를 가진 대상 인덱스를 만들어요.
  2. 시스템이 원본 인덱스 세그먼트에서 대상 인덱스로 하드 링크(hard link)를 만들어요. 파일 시스템이 하드 링크를 지원하지 않으면 OpenSearch가 모든 세그먼트를 대상 인덱스로 복사하는데, 이 경우 시간과 디스크 공간이 더 필요해요.
  3. OpenSearch가 대상 인덱스를 다시 열린 닫힌 인덱스처럼 복구(recover)해서 사용할 수 있게 만들어요.

출처: 문서

본문

사전 요구 사항 (Prerequisites)

인덱스를 복제하기 전에 원본 인덱스를 읽기 전용으로 표시하고 클러스터가 정상 상태인지 확인해야 해요.

  • 원본 인덱스의 index.blocks.write 설정이 true여야 복제 과정 중 쓰기 작업을 막을 수 있어요. 인덱스 삭제 같은 메타데이터 변경은 여전히 허용돼요.
  • 모든 프라이머리 샤드와 복제본 샤드를 사용할 수 있도록 클러스터 상태가 green이어야 해요.

다음 예제 요청은 products 인덱스를 읽기 전용 모드로 설정해 복제할 수 있게 만들어요.

엔드포인트 (Endpoints)

POST /{index}/_clone/{target}
PUT  /{index}/_clone/{target}

요구 사항 (Requirements)

인덱스는 다음 요구 사항을 충족해야 복제할 수 있어요.

  • 대상 인덱스가 이미 존재하면 안 돼요.
  • 원본 인덱스와 대상 인덱스의 프라이머리 샤드 수가 같아야 해요.
  • 원본 인덱스가 index.blocks.write를 true로 설정해 읽기 전용으로 표시되어야 해요.
  • 클러스터 상태가 green이어야 해요.
  • 복제 과정을 처리하는 노드에, 파일 시스템이 하드 링크를 지원하지 않을 때 인덱스의 두 번째 복사본을 저장할 충분한 여유 디스크 공간이 있어야 해요.

인덱스 이름 제한 (Index naming restrictions)

OpenSearch 인덱스에는 다음과 같은 이름 제한이 있어요.

  • 모든 글자는 소문자여야 해요.
  • 인덱스 이름은 밑줄(_)이나 하이픈(-)으로 시작할 수 없어요.
  • 인덱스 이름에 공백, 쉼표, 그리고 다음 문자를 포함할 수 없어요: :, ", *, +, /, \, |, ?, #, >, <

경로 파라미터 (Path parameters)

다음 표는 사용 가능한 경로 파라미터를 보여줘요.

파라미터 필수 데이터 타입 설명
index 필수 String 복제할 원본 인덱스의 이름이에요.
target 필수 String 만들 대상 인덱스의 이름이에요.

쿼리 파라미터 (Query parameters)

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명 기본값
cluster_manager_timeout String 클러스터 매니저 노드에 연결하기 위해 기다리는 시간이에요. 30s
task_execution_timeout String 작업이 완료되기까지 기다리는 시간이에요. wait_for_completion이 false일 때만 적용돼요. 1h
timeout String 응답을 기다리는 시간이에요. 제한 시간이 지나기 전에 응답이 없으면 요청이 실패하고 오류를 반환해요. 30s
wait_for_active_shards String 작업이 진행되기 위해 필요한 활성 샤드 복사본 수예요. all 또는 인덱스의 전체 샤드 수(number_of_replicas+1)까지의 양의 정수를 지정해요. 1 (프라이머리 샤드만)
wait_for_completion Boolean 응답을 반환하기 전에 작업 완료를 기다릴지 여부예요. true

요청 본문 필드 (Request body fields)

clone index API는 새 대상 인덱스를 만들기 때문에 요청 본문에서 대상 인덱스에 적용할 인덱스 설정과 별칭을 지정할 수 있어요. 요청 본문은 선택 사항이에요.

필드 데이터 타입 설명
settings Object 대상 인덱스의 구성 옵션이에요. 인덱스 설정 목록은 Index settings를 참고하세요. 선택 사항이에요.
settings.index.number_of_shards Integer 대상 인덱스의 프라이머리 샤드 수예요. 이 값은 원본 인덱스의 프라이머리 샤드 수와 같아야 해요. 선택 사항이에요. 기본값은 원본 인덱스와 같아요.
settings.index.number_of_replicas Integer 대상 인덱스 각 프라이머리 샤드의 복제본 샤드 수예요. 선택 사항이에요. 기본값은 원본 인덱스와 같아요.
aliases Object 대상 인덱스에 적용할 인덱스 별칭이에요. 각 키는 별칭 이름이고 값은 별칭 구성 객체예요. 자세한 내용은 Index aliases를 참고하세요. 선택 사항이에요.

참고: clone 요청에는 매핑을 지정할 수 없어요. 원본 인덱스의 매핑이 대상 인덱스에 자동으로 사용돼요.

예제: 인덱스 복제 (Example: Cloning an index)

다음 예제 요청은 products 인덱스를 products-clone이라는 새 인덱스로 복제해요.

예제: 설정과 별칭을 포함한 인덱스 복제 (Example: Cloning an index with settings and aliases)

다음 예제 요청은 custom 설정과 별칭으로 products 인덱스를 products-clone-configured라는 새 인덱스로 복제해요.

예제 응답 (Example response)

clone 요청이 성공하면 OpenSearch는 다음 응답을 반환해요. index 필드에는 만들어진 대상 인덱스의 이름이 들어 있어요.

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "products-clone"
}

대상 인덱스가 클러스터 상태에 추가되면 응답은 즉시 반환돼요. clone 작업이 완료될 때까지 기다리지 않아요.

응답 본문 필드 (Response body fields)

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
acknowledged Boolean 클러스터가 clone 요청을 받았는지 여부예요. true는 요청을 받았다는 뜻이에요.
shards_acknowledged Boolean wait_for_active_shards 설정이 지정한 샤드 복사본 수가 작업이 제한 시간을 넘기기 전에 활성화되었는지 여부예요. true는 목표 샤드 복사본 수가 활성화되었다는 뜻이고, false는 작업이 제한 시간을 넘길 때까지 목표 샤드 복사본 수가 활성화되지 않았다는 뜻이에요.
index String 새로 만들어진 대상 인덱스의 이름이에요.

복제 과정 모니터링 (Monitoring the cloning process)

clone API는 어떤 샤드도 할당되기 전에 대상 인덱스를 클러스터 상태에 추가하자마자 즉시 반환돼요. 이 시점에는 모든 샤드가 unassigned 상태예요. 어떤 이유로든 대상 인덱스를 할당할 수 없으면, 프라이머리 샤드는 노드에 할당될 수 있을 때까지 unassigned 상태로 남아요.

프라이머리 샤드가 할당되면 initializing 상태로 전환되고 clone 작업이 시작돼요. clone 작업이 완료되면 샤드는 active가 돼요. 그러면 OpenSearch가 복제본을 할당하려 시도하고 프라이머리 샤드를 다른 노드로 재배치할 수도 있어요.

다음 방법 중 하나로 복제 과정을 모니터링할 수 있어요.

  • 샤드 복구와 복제 진행 상황을 보려면 CAT recovery API를 사용해요.
  • 모든 프라이머리 샤드가 할당될 때까지 기다리려면 wait_for_status 파라미터를 yellow로 설정한 Cluster health API를 사용해요.

다음 예제 요청은 복제된 인덱스의 복구 과정을 모니터링해요.

활성 샤드 기다리기 (Wait for active shards)

clone 작업은 새 인덱스를 만들기 때문에 인덱스 생성의 wait_for_active_shards 설정도 clone 작업에 적용돼요. 이 설정은 작업이 응답을 반환하기 전에 몇 개의 샤드 복사본이 활성화되어야 하는지 결정해요. 자세한 내용은 Index settings를 참고하세요.

필요한 권한 (Required permissions)

Security plugin을 사용한다면 indices:admin/resize 권한이 있는지 확인하세요.

더 알아보기 (Learn more)