인덱스 롤오버 API

인덱스 롤오버 API (Roll Over Index API)

1.0부터 도입되었어요.

인덱스 롤오버(roll over index) API 작업은 wait_for_active_shards 설정에 따라 데이터 스트림이나 인덱스 별칭에 대한 새 인덱스를 생성해요.

출처: 문서

본문

엔드포인트

POST /{rollover-target}/_rollover/
POST /{rollover-target}/_rollover/{target-index}

롤오버 유형

데이터 스트림, 인덱스 하나가 달린 인덱스 별칭, 또는 쓰기 인덱스가 있는 인덱스 별칭을 롤오버할 수 있어요.

데이터 스트림

데이터 스트림에서 롤오버 작업을 수행하면 API가 그 스트림을 위한 새 쓰기 인덱스를 생성해요. 동시에 스트림의 이전 쓰기 인덱스는 일반 백킹 인덱스로 바뀌어요. 또한 롤오버 과정은 데이터 스트림의 세대(generation) 수를 증가시켜요. 데이터 스트림 롤오버는 요청 본문에 인덱스 설정을 지정하는 것을 지원하지 않아요.

인덱스 하나가 달린 인덱스 별칭

단일 인덱스와 연결된 인덱스 별칭에서 롤오버를 시작하면 API가 새 인덱스를 생성하고 원래 인덱스를 별칭에서 분리해요.

쓰기 인덱스가 있는 인덱스 별칭

인덱스 별칭이 여러 인덱스를 가리킬 때는 인덱스 하나를 쓰기 인덱스로 지정해야 해요. 롤오버 중에 API는 이전 쓰기 인덱스의 is_write_index 속성을 false로 설정하면서, is_write_index 속성이 true로 설정된 새 쓰기 인덱스를 만들어요.

별칭의 인덱스 이름 증가시키기

인덱스 별칭 롤오버 과정에서 사용자 지정 이름을 지정하지 않고 현재 인덱스 이름이 하이픈과 숫자로 끝난다면(예: my-index-000001 또는 my-index-3), 롤오버 작업이 자동으로 새 인덱스 이름의 그 숫자를 증가시켜요. 예를 들어 my-index-000001을 롤오버하면 my-index-000002가 생성돼요. 숫자 부분은 항상 여섯 자리 길이를 유지하도록 앞에 0으로 채워져요.

날짜 수학을 인덱스 롤오버에 사용하기

시계열 데이터에 인덱스 별칭을 사용한다면 인덱스 이름에 date math를 사용해 롤오버 날짜를 추적할 수 있어요. 예를 들어 my-index-{now/d}-000001을 가리키는 별칭을 만들 수 있어요. 2029년 6월 11일에 별칭을 만들면 인덱스 이름은 my-index-2029.06.11-000001이 돼요. 2029년 6월 12일에 롤오버하면 새 인덱스 이름은 my-index-2029.06.12-000002예요. 실용적인 예는 쓰기 인덱스가 있는 인덱스 별칭 롤오버를 참고해요.

경로 파라미터

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

파라미터 데이터 타입 설명
rollover-target String 롤오버할 데이터 스트림 또는 인덱스 별칭의 이름이에요. 필수예요.
target-index String 생성할 인덱스의 이름이에요. 날짜 수학을 지원해요. 데이터 스트림은 이 파라미터를 지원하지 않아요. 별칭의 현재 쓰기 인덱스 이름이 my-index-000001이나 my-index-2처럼 -와 숫자로 끝나지 않는다면 이 파라미터는 필수예요.

쿼리 파라미터

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

파라미터 데이터 타입 설명
cluster_manager_timeout Time 클러스터 매니저 노드에 연결될 때까지 기다리는 시간이에요. 기본값은 30s예요.
timeout Time 응답을 기다리는 시간이에요. 기본값은 30s예요.
wait_for_active_shards String OpenSearch가 요청을 처리하기 전에 사용할 수 있어야 하는 활성 샤드 수예요. 기본값은 1(프라이머리 샤드만)이에요. all 또는 양의 정수로도 설정할 수 있어요. 1보다 큰 값은 복제본이 필요해요. 예를 들어 값을 3으로 지정하면 작업이 성공하려면 인덱스에 두 개의 추가 노드에 분산된 복제본 두 개가 있어야 해요.

요청 본문 필드

다음 요청 본문 필드를 지원해요.

alias

alias 파라미터는 별칭 이름을 키로 지정해요. 요청 본문에 template 옵션이 있을 때 필수예요. 객체 본문에는 다음 선택적 파라미터가 있어요.

파라미터 타입 설명
filter Query DSL object 별칭이 접근할 수 있는 문서 수를 제한하는 쿼리예요.
index_routing String 인덱싱 작업을 특정 샤드로 라우팅하는 값이에요. 지정하면 인덱싱 작업의 routing 값을 덮어써요.
is_hidden Boolean 별칭을 숨기거나 표시해요. true이면 별칭이 숨겨져요. 기본값은 false예요. 별칭의 인덱스들은 이 설정에 대해 일치하는 값을 가져야 해요.
is_write_index Boolean 쓰기 인덱스를 지정해요. true이면 그 인덱스가 별칭의 쓰기 인덱스예요. 기본값은 false예요.
routing String 인덱스와 검색 작업을 특정 샤드로 라우팅하는 데 사용하는 값이에요.
search_routing String 검색 작업을 특정 샤드로 라우팅해요. 지정하면 검색 작업의 routing을 덮어써요.

mappings

mappings 파라미터는 인덱스 필드 매핑을 지정해요. 선택사항이에요. 자세한 내용은 Mappings and field types를 참고해요.

conditions

conditions 파라미터는 롤오버를 트리거하는 기준을 정의하는 선택적 객체예요. 제공되면 OpenSearch는 현재 인덱스가 하나 이상의 지정된 조건을 충족할 때만 롤오버해요. 생략하면 사전 조건 없이 무조건 롤오버가 발생해요.

객체 본문은 다음 파라미터를 지원해요.

파라미터 데이터 타입 설명
max_age Time units 인덱스 생성 후 최대 경과 시간에 도달하면 롤오버를 트리거해요. 경과 시간은 index.lifecycle.parse_origination_date 또는 index.lifecycle.origination_date 설정을 사용해 인덱스 시작 날짜를 사용자 지정 날짜로 구성한 경우에도 항상 인덱스 생성 시간부터 계산돼요. 선택사항이에요.
max_docs Integer 마지막 리프레시 이후 추가된 문서와 복제본 샤드의 문서를 제외한 문서 수가 지정된 최대값에 도달하면 롤오버를 트리거해요. 선택사항이에요.
max_size Byte units 인덱스가 지정된 크기에 도달하면 롤오버를 트리거해요. 모든 프라이머리 샤드의 총 크기로 계산되며 복제본은 계산하지 않아요. 현재 인덱스 크기를 보려면 _cat indices API를 사용하고 pri.store.size 값을 확인해요. 선택사항이에요.

settings

settings 파라미터는 인덱스 구성 옵션을 지정해요. 자세한 내용은 Index settings를 참고해요.

요청 예시

다음 예제들은 롤오버 인덱스 API 사용법을 보여줘요. 지정된 조건 중 하나 이상이 충족되면 롤오버가 발생해요:

  • 인덱스가 5일 이상 전에 생성됨
  • 인덱스가 500개 이상의 문서를 포함함
  • 인덱스가 100GB 이상

데이터 스트림 롤오버

다음 요청은 현재 쓰기 인덱스가 지정된 조건 중 하나라도 충족하면 데이터 스트림을 롤오버해요:

POST /my-alias/_rollover
{
  "conditions": {
    "max_age": "5d",
    "max_docs": 500,
    "max_size": "100gb"
  }
}

쓰기 인덱스가 있는 인덱스 별칭 롤오버

다음 요청은 날짜-시간 인덱스를 생성하고 my-alias의 쓰기 인덱스로 설정해요. 인덱스 이름은 URL 인코딩이 필요해요: %3Cmy-index-%7Bnow%2Fd%7D-000001%3E는 <my-index-{now/d}-000001>의 인코딩된 형태이고, {now/d}는 현재 날짜로 해석돼요:

PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-alias": {
      "is_write_index": true
    }
  }
}

다음 요청은 별칭을 사용해 롤오버를 수행해요:

POST /my-data-stream/_rollover
{
  "conditions": {
    "max_age": "5d",
    "max_docs": 500,
    "max_size": "100gb"
  }
}

롤오버 중 설정 지정

대부분의 경우 인덱스 템플릿을 사용해 롤오버 작업 중 생성되는 인덱스를 자동으로 구성할 수 있어요. 하지만 인덱스 별칭을 롤오버할 때는 롤오버 인덱스 API를 사용해 템플릿에 정의된 설정에 추가 설정을 도입하거나 템플릿 설정을 덮어쓸 수 있어요. 다음 요청을 보내면 돼요:

POST /my-alias/_rollover
{
  "settings": {
    "index.number_of_shards": 4
  }
}

응답 예시

OpenSearch는 max_size를 제외한 모든 조건이 충족되었음을 확인하는 다음 응답을 반환해요:

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": ".ds-my-data-stream-2029.06.11-000001",
  "new_index": ".ds-my-data-stream-2029.06.12-000002",
  "rolled_over": true,
  "dry_run": false,
  "conditions": {
    "[max_age: 5d]": true,
    "[max_docs: 500]": true,
    "[max_size: 100gb]": false
  }
}

필요한 권한

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

더 알아보기 (Learn more)