Bulk Replication API
출처: 문서
본문
Bulk Replication API
벌크 복제 작업을 사용하면 단일 API 호출로 여러 인덱스에 걸친 크로스 클러스터 복제를 프로그래밍 방식으로 관리할 수 있어요. 인덱스 패턴을 지정해서 일치하는 인덱스를 선택하고, 시작, 중지, 일시정지, 재개 작업을 한 번에 수행할 수 있어요.
모든 벌크 복제 작업은 비동기로 동작해요. 각 요청은 task_id를 반환하는데, 이걸 사용해서 작업 진행 상황을 확인하거나 작업을 취소할 수 있어요. 클러스터당 한 번에 하나의 벌크 복제 작업만 실행할 수 있고, 작업이 진행 중인 동안 새 벌크 복제 작업을 제출하면 409 Conflict 오류가 발생해요. 일부 인덱스에서 벌크 복제 작업이 실패하면 작업은 나머지 인덱스를 계속 처리하고, 성공한 인덱스와 실패한 인덱스 목록을 보고해요. 실행 중인 벌크 작업은 언제든지 취소할 수 있지만 이미 처리된 인덱스는 되돌려지지 않아요. 인덱스는 설정 가능한 배치 단위로 처리돼요(자세한 내용은 설정 참고). 벌크 복제 작업은 멱등하지 않아요. 이전 작업이 실행을 마친 후에 같은 요청을 다시 제출하면 새 작업이 생성돼요.
패턴 매칭
pattern 필드는 OpenSearch 인덱스 패턴과 같은 문법을 지원해요:
*는 임의 개수의 문자와 일치해요.?는 단일 문자와 일치해요.- 패턴은
_로 시작하면 안 돼요. - 패턴에는 공백, 따옴표(
"), 꺾쇠 괄호(<,>), 파이프(|), 백슬래시(\), 해시 기호(#), 쉼표(,)가 포함되면 안 돼요.
예시:
my-index-*는my-index-1,my-index-2,my-index-logs등과 일치해요.*는 모든 인덱스와 일치해요(.로 시작하는 시스템 인덱스는 제외).logs-2024-0?는logs-2024-01~logs-2024-09와 일치해요.
목차
{: .text-delta } - TOC {:toc}벌크 복제 시작
Introduced 3.7 {: .label .label-purple }
지정된 패턴과 일치하는 리더 클러스터의 모든 인덱스에 대해 복제를 시작해요. 이 요청은 팔로워 클러스터로 보내세요.
엔드포인트
POST /_plugins/_replication/_bulk_start
요청 본문 필드
다음 표는 사용할 수 있는 요청 본문 필드를 보여줘요.
| 필드 | 데이터 타입 | 설명 | 필수 여부 |
|---|---|---|---|
leader_alias |
String | 크로스 클러스터 연결의 이름이에요. 이 별칭은 크로스 클러스터 연결을 설정할 때 정의해요. | 필수 |
pattern |
String | 리더 클러스터에서 인덱스를 매칭할 인덱스 패턴이에요. 와일드카드 문자를 지원해요. 예를 들어 my-index-* 또는 모든 인덱스를 뜻하는 *를 쓸 수 있어요. |
필수 |
use_roles |
Object | 이후 인덱스 간에 수행되는 모든 백엔드 복제 작업에 사용할 역할이에요. leader_cluster_role과 follower_cluster_role을 지정하세요. 자세한 내용은 리더 및 팔로워 클러스터 역할 매핑을 참고하세요. |
Security 플러그인이 활성화된 경우 |
filters |
Object | 인덱스 선택을 세밀하게 조정하는 필터를 담은 오브젝트예요. | 선택 |
filters.exclude_index |
Array | 작업에서 제외할 인덱스 이름 목록이에요. | 선택 |
예시 요청
POST /_plugins/_replication/_bulk_start
{
"leader_alias": "<connection-alias-name>",
"pattern": "<index-pattern>",
"use_roles": {
"leader_cluster_role": "<role-name>",
"follower_cluster_role": "<role-name>"
},
"filters": {
"exclude_index": ["<index-name-1>", "<index-name-2>"]
}
}
{% include copy-curl.html %}
벌크 복제 중지
Introduced 3.7 {: .label .label-purple }
복제를 중지하고 일치하는 모든 팔로워 인덱스를 쓰기 작업을 허용하는 일반 인덱스로 변환해요. 이 요청은 팔로워 클러스터로 보내세요.
엔드포인트
POST /_plugins/_replication/_bulk_stop
요청 본문 필드
다음 표는 사용할 수 있는 요청 본문 필드를 보여줘요.
| 필드 | 데이터 타입 | 설명 | 필수 여부 |
|---|---|---|---|
pattern |
String | 팔로워 인덱스를 매칭할 인덱스 패턴이에요. 와일드카드 문자를 지원해요. 예를 들어 follower-* 또는 복제 중인 모든 인덱스를 뜻하는 *를 쓸 수 있어요. |
필수 |
filters |
Object | 인덱스 선택을 세밀하게 조정하는 필터를 담은 오브젝트예요. | 선택 |
filters.exclude_index |
Array | 작업에서 제외할 인덱스 이름 목록이에요. | 선택 |
예시 요청
POST /_plugins/_replication/_bulk_stop
{
"pattern": "<index-pattern>",
"filters": {
"exclude_index": ["<index-name-1>", "<index-name-2>"]
}
}
{% include copy-curl.html %}
벌크 복제 일시정지
Introduced 3.7 {: .label .label-purple }
일치하는 모든 팔로워 인덱스의 복제를 일시정지해요. 이 요청은 팔로워 클러스터로 보내세요.
복제가 12시간 이상 일시정지된 상태로 있으면 재개할 수 없어요. 복제를 중지하고, 팔로워 인덱스를 삭제한 다음, 리더에 대한 복제를 다시 시작해야 해요. {: .warning }
엔드포인트
POST /_plugins/_replication/_bulk_pause
요청 본문 필드
다음 표는 사용할 수 있는 요청 본문 필드를 보여줘요.
| 필드 | 데이터 타입 | 설명 | 필수 여부 |
|---|---|---|---|
pattern |
String | 팔로워 인덱스를 매칭할 인덱스 패턴이에요. 와일드카드 문자를 지원해요. | 필수 |
filters |
Object | 인덱스 선택을 세밀하게 조정하는 필터를 담은 오브젝트예요. | 선택 |
filters.exclude_index |
Array | 작업에서 제외할 인덱스 이름 목록이에요. | 선택 |
예시 요청
POST /_plugins/_replication/_bulk_pause
{
"pattern": "<index-pattern>",
"filters": {
"exclude_index": ["<index-name-1>", "<index-name-2>"]
}
}
{% include copy-curl.html %}
벌크 복제 재개
Introduced 3.7 {: .label .label-purple }
지정된 패턴과 일치하는, 일시정지된 모든 팔로워 인덱스의 복제를 재개해요. 리더 클러스터에 접근할 수 있어야 하고, 각 인덱스의 retention lease가 아직 유효해야 해요. 이 요청은 팔로워 클러스터로 보내세요.
엔드포인트
POST /_plugins/_replication/_bulk_resume
요청 본문 필드
다음 표는 사용할 수 있는 요청 본문 필드를 보여줘요.
| 필드 | 데이터 타입 | 설명 | 필수 여부 |
|---|---|---|---|
pattern |
String | 일시정지된 팔로워 인덱스를 매칭할 인덱스 패턴이에요. 와일드카드 문자를 지원해요. | 필수 |
filters |
Object | 인덱스 선택을 세밀하게 조정하는 필터를 담은 오브젝트예요. | 선택 |
filters.exclude_index |
Array | 작업에서 제외할 인덱스 이름 목록이에요. | 선택 |
예시 요청
POST /_plugins/_replication/_bulk_resume
{
"pattern": "<index-pattern>",
"filters": {
"exclude_index": ["<index-name-1>", "<index-name-2>"]
}
}
{% include copy-curl.html %}
벌크 복제 상태 조회
Introduced 3.7 {: .label .label-purple }
패턴과 일치하는 모든 인덱스의 현재 복제 상태를 반환해요. 벌크 작업 상태 조회 엔드포인트와 달리, 이 엔드포인트는 벌크 복제 작업의 진행 상황이 아니라 실시간 복제 상태를 반환해요. 이 요청은 팔로워 클러스터로 보내세요.
엔드포인트
GET /_plugins/_replication/_bulk_status?pattern={index-pattern}
쿼리 파라미터
다음 표는 사용할 수 있는 쿼리 파라미터를 보여줘요.
| 파라미터 | 데이터 타입 | 설명 | 필수 여부 |
|---|---|---|---|
pattern |
String | 팔로워 인덱스를 매칭할 인덱스 패턴이에요. 와일드카드 문자를 지원해요. | 필수 |
예시 응답
{
"indices": {
"bulk-test-3": {
"status": "SYNCING",
"reason": "User initiated",
"leader_alias": "leader-cluster",
"leader_index": "bulk-test-3",
"follower_index": "bulk-test-3",
"syncing_details": {
"leader_checkpoint": -1,
"follower_checkpoint": -1,
"seq_no": 0
}
},
"bulk-test-6": {
"status": "PAUSED",
"reason": "bulk_pause",
"leader_alias": "leader-cluster",
"leader_index": "bulk-test-6",
"follower_index": "bulk-test-6"
},
"bulk-test-9": {
"status": "BOOTSTRAPPING",
"reason": "User initiated",
"leader_alias": "leader-cluster",
"leader_index": "bulk-test-9",
"follower_index": "bulk-test-9",
"bootstrap_details": {
"status": "IN_PROGRESS",
"shard_restore_details": {
"total_shards": 5,
"successful_shards": 2,
"failed_shards": 0,
"in_progress_shards": 3
}
}
}
}
}
응답 본문 필드
다음 표는 응답 본문 필드를 보여줘요.
| 필드 | 데이터 타입 | 설명 |
|---|---|---|
indices |
Object | 인덱스 이름을 각 인덱스의 복제 상태 오브젝트에 매핑한 맵이에요. |
indices.<index>.status |
String | 현재 복제 상태예요. 가능한 값은 SYNCING, BOOTSTRAPPING, PAUSED, RESTORING이에요. |
indices.<index>.reason |
String | 현재 상태의 이유예요. |
indices.<index>.leader_alias |
String | 리더 클러스터의 크로스 클러스터 연결 별칭이에요. |
indices.<index>.leader_index |
String | 리더 클러스터에 있는 인덱스의 이름이에요. |
indices.<index>.follower_index |
String | 팔로워 클러스터에 있는 인덱스의 이름이에요. |
indices.<index>.syncing_details |
Object | 복제 진행 상세 정보예요. 상태가 SYNCING일 때 표시돼요. |
indices.<index>.syncing_details.leader_checkpoint |
Integer | 리더 인덱스의 최신 체크포인트예요. |
indices.<index>.syncing_details.follower_checkpoint |
Integer | 팔로워 인덱스의 최신 체크포인트예요. |
indices.<index>.syncing_details.seq_no |
Integer | 현재 시퀀스 번호예요. |
indices.<index>.bootstrap_details |
Object | 부트스트랩 진행 상세 정보예요. 상태가 BOOTSTRAPPING일 때만 표시돼요. 부트스트랩이 완료되고 복제가 syncing 단계에 들어가면 이 필드는 syncing_details로 대체돼요. |
indices.<index>.bootstrap_details.status |
String | 부트스트랩 상태예요. 가능한 값은 IN_PROGRESS, COMPLETED, FAILED예요. |
indices.<index>.bootstrap_details.shard_restore_details |
Object | 부트스트랩 중 샤드 단위 복원 진행 상황이에요. |
indices.<index>.bootstrap_details.shard_restore_details.total_shards |
Integer | 복원할 샤드의 총 개수예요. |
indices.<index>.bootstrap_details.shard_restore_details.successful_shards |
Integer | 성공적으로 복원된 샤드 개수예요. |
indices.<index>.bootstrap_details.shard_restore_details.failed_shards |
Integer | 복원에 실패한 샤드 개수예요. |
indices.<index>.bootstrap_details.shard_restore_details.in_progress_shards |
Integer | 현재 복원 중인 샤드 개수예요. |
벌크 작업 상태 조회
Introduced 3.7 {: .label .label-purple }
벌크 복제 작업의 진행 상황을 반환해요. 어떤 벌크 복제 작업이든 반환된 task_id를 사용해서 작업 상태를 확인하세요. 이 요청은 팔로워 클러스터로 보내세요.
엔드포인트
GET /_plugins/_replication/_task_status/{task_id}
경로 파라미터
다음 표는 사용할 수 있는 경로 파라미터를 보여줘요.
| 파라미터 | 데이터 타입 | 설명 | 필수 여부 |
|---|---|---|---|
task_id |
String | 벌크 복제 작업이 반환한 작업 ID예요. | 필수 |
예시 응답
{
"operation_type": "bulk_stop_replication",
"pattern": "my-index-*",
"start_time": 1717600000000,
"num_success": 7,
"num_failed": 1,
"num_pending": 2,
"num_cancelled": 0,
"failed_indices": [
{
"index": "my-index-3",
"failure_reason": "No replication in progress for index:my-index-3"
}
]
}
응답 본문 필드
다음 표는 응답 본문 필드를 보여줘요.
| 필드 | 데이터 타입 | 설명 |
|---|---|---|
operation_type |
String | 벌크 복제 작업의 유형이에요. 가능한 값은 bulk_start_replication, bulk_stop_replication, bulk_pause_replication, bulk_resume_replication이에요. |
pattern |
String | 작업에 사용된 인덱스 패턴이에요. |
start_time |
Long | 작업이 시작된 시점의 epoch 타임스탬프(밀리초)예요. |
num_success |
Integer | 작업이 성공적으로 완료된 인덱스 개수예요. |
num_failed |
Integer | 작업이 실패한 인덱스 개수예요. |
num_pending |
Integer | 처리 대기 중인 인덱스 개수예요. 이 값이 0이 되면 작업이 완료된 거예요. |
num_cancelled |
Integer | 작업 취소로 인해 처리되지 않은 인덱스 개수예요. |
failed_indices |
Array | 실패한 각 인덱스의 index 이름과 failure_reason을 담고 있는 오브젝트 배열이에요. |
벌크 작업 취소
Introduced 3.7 {: .label .label-purple }
실행 중인 벌크 복제 작업을 취소해요. 이미 처리된 인덱스는 작업이 적용한 상태 그대로 유지되고, 나머지 인덱스는 취소됨으로 표시돼요. 이 요청은 팔로워 클러스터로 보내세요.
엔드포인트
POST /_plugins/_replication/_task_cancel/{task_id}
경로 파라미터
다음 표는 사용할 수 있는 경로 파라미터를 보여줘요.
| 파라미터 | 데이터 타입 | 설명 | 필수 여부 |
|---|---|---|---|
task_id |
String | 취소할 벌크 복제 작업의 작업 ID예요. | 필수 |
설정
벌크 복제 설정에 대한 내용은 벌크 복제 설정을 참고하세요. 동적 설정 업데이트에 대해 알아보려면 동적 설정을 참고하세요.
오류 응답
다음 예시는 벌크 복제 API 작업을 사용할 때 마주칠 수 있는 일반적인 오류 응답을 보여줘요.
벌크 작업이 이미 실행 중인 경우
다른 벌크 복제 작업이 이미 진행 중인 상태에서 벌크 복제 작업을 제출하면 OpenSearch는 409 오류를 반환해요:
{
"error": {
"root_cause": [
{
"type": "resource_already_exists_exception",
"reason": "A bulk replication task is already running. Only one bulk task is allowed at a time."
}
],
"type": "resource_already_exists_exception",
"reason": "A bulk replication task is already running. Only one bulk task is allowed at a time."
},
"status": 409
}
새 작업을 제출하기 전에 현재 작업이 완료되기를 기다리거나 취소하세요.
패턴과 일치하는 인덱스가 없는 경우
지정된 패턴과 일치하는 인덱스를 찾지 못하면 OpenSearch는 404 오류를 반환해요:
{
"error": {
"root_cause": [
{
"type": "resource_not_found_exception",
"reason": "No indices found matching pattern: [non-existent-*] on leader cluster"
}
],
"type": "resource_not_found_exception",
"reason": "No indices found matching pattern: [non-existent-*] on leader cluster"
},
"status": 404
}
leader_alias 누락
leader_alias를 제공하지 않고 벌크 시작 요청을 제출하면 OpenSearch는 400 오류를 반환해요:
{
"error": {
"root_cause": [
{
"type": "action_request_validation_exception",
"reason": "Validation Failed: 1: leader_alias is required for bulk start;"
}
],
"type": "action_request_validation_exception",
"reason": "Validation Failed: 1: leader_alias is required for bulk start;"
},
"status": 400
}
모든 인덱스가 검증에 실패한 경우
매칭된 모든 인덱스가 이미 작업이 요청하는 상태에 있는 경우(예: 복제가 이미 일시정지된 인덱스에 복제 일시정지 작업을 보내는 경우) OpenSearch는 400 오류를 반환해요:
{
"error": {
"root_cause": [
{
"type": "illegal_argument_exception",
"reason": "Index bulk-test-1 is already paused; Index bulk-test-2 is already paused"
}
],
"type": "illegal_argument_exception",
"reason": "Index bulk-test-1 is already paused; Index bulk-test-2 is already paused"
},
"status": 400
}
작업을 찾을 수 없는 경우
존재하지 않거나 이미 완료된 작업을 취소하거나 조회하려고 하면 OpenSearch는 404 오류를 반환해요:
{
"error": {
"root_cause": [
{
"type": "resource_not_found_exception",
"reason": "Task a3PiBHTWTTulezYixxCwkw:7709 not found or already completed"
}
],
"type": "resource_not_found_exception",
"reason": "Task a3PiBHTWTTulezYixxCwkw:7709 not found or already completed"
},
"status": 404
}
제한 사항
다음 제한 사항에 유의하세요:
- Bulk Replication API는 실패