본문 바로가기
WIKI 기술 지식 베이스

Cross-Cluster Replication API

원문 보기 위키 갱신

출처: 문서

본문

크로스 클러스터 복제 API

이 복제 작업들을 사용해서 프로그래밍 방식으로 크로스 클러스터 복제를 관리할 수 있어요.

목차 {: .text-delta } - TOC {:toc}

복제 시작

1.1에서 도입 {: .label .label-purple }

리더 클러스터에서 팔로워 클러스터로 인덱스 복제를 시작해요. 이 요청은 팔로워 클러스터로 보내세요.

엔드포인트

PUT /_plugins/_replication/{follower-index}/_start

요청 본문 필드

다음 표에서 사용 가능한 요청 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명 필수 여부
leader_alias String 크로스 클러스터 연결의 이름이에요. 이 별칭은 크로스 클러스터 연결을 설정할 때 정의해요. 예
leader_index String 복제하려는 리더 클러스터의 인덱스예요. 예
use_roles Object 인덱스 간 이후 모든 백엔드 복제 작업에 사용할 역할이에요. leader_cluster_role과 follower_cluster_role을 지정하세요. 자세한 내용은 리더 및 팔로워 클러스터 역할 매핑을 참고하세요. Security 플러그인이 활성화된 경우

예제 요청

PUT /_plugins/_replication/follower-01/_start
{
   "leader_alias": "my-connection-alias",
   "leader_index": "leader-01",
   "use_roles": {
      "leader_cluster_role": "cross_cluster_replication_leader_full_access",
      "follower_cluster_role": "cross_cluster_replication_follower_full_access"
   }
}

{% include copy-curl.html %}

예제 응답

{
   "acknowledged": true
}

복제 중지

1.1에서 도입 {: .label .label-purple }

복제를 종료하고 팔로워 인덱스를 일반 인덱스로 변환해요. 이 요청은 팔로워 클러스터로 보내세요.

엔드포인트

POST /_plugins/_replication/{follower-index}/_stop

예제 요청

POST /_plugins/_replication/follower-01/_stop
{}

{% include copy-curl.html %}

예제 응답

{
   "acknowledged": true
}

복제 일시 중지

1.1에서 도입 {: .label .label-purple }

리더 인덱스의 복제를 일시 중지해요. 이 요청은 팔로워 클러스터로 보내세요.

엔드포인트

POST /_plugins/_replication/{follower-index}/_pause

예제 요청

POST /_plugins/_replication/follower-01/_pause
{}

{% include copy-curl.html %}

일시 중지 상태가 retention lease 기간보다 오래 지속되면 복제를 재개할 수 없어요. 복구하려면 리더의 스냅샷에서 팔로워 인덱스를 복원하는 force-resume을 사용하세요.

예제 응답

{
   "acknowledged": true
}

복제 재개

1.1에서 도입 {: .label .label-purple }

리더 인덱스의 복제를 재개해요. 이 요청은 팔로워 클러스터로 보내세요.

엔드포인트

POST /_plugins/_replication/{follower-index}/_resume

요청 본문 필드

다음 표에서 사용 가능한 요청 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명 필수 여부
force_resume Boolean true로 설정하면 retention lease가 만료되었을 때 stop-delete-start 사이클을 수행해서 리더에서 팔로워 인덱스를 복원해요. 복제가 12시간 이상 일시 중지되었고 일반적인 재개가 실패할 때 사용하세요. 자세한 내용은 복제 강제 재개를 참고하세요. 기본값은 false예요. 아니요

예제 요청

POST /_plugins/_replication/follower-01/_resume
{}

{% include copy-curl.html %}

예제 응답

{
   "acknowledged": true
}

오류 응답

다음 표에서 재개 작업의 일반적인 오류 응답을 확인할 수 있어요.

상태 코드 오류 설명
404 Retention lease doesn't exist. Use force_resume=true to restore from snapshot. retention lease가 만료되었고 force_resume이 true로 설정되지 않았어요. "force_resume": true로 요청을 다시 시도하세요.
400 복제가 PAUSED 상태가 아님 강제 재개는 복제가 일시 중지된 상태에서만 사용할 수 있어요. 먼저 복제 상태를 확인하세요.
500 복제 중지 실패 내부 중지 작업이 실패했어요. 클러스터 상태를 확인하고 다시 시도하세요.
500 팔로워 인덱스 삭제 실패 복제 중지 후 팔로워 인덱스를 삭제하지 못했어요. 수동 정리가 필요할 수 있어요.
500 복제 시작 실패 팔로워가 삭제된 후 내부 시작 작업이 실패했어요. 복제를 수동으로 다시 시작해야 할 수 있어요.

복제 상태 조회

1.1에서 도입 {: .label .label-purple }

인덱스 복제 상태를 조회해요. 가능한 상태는 SYNCING, BOOTSTRAPING, PAUSED, REPLICATION NOT IN PROGRESS예요. 동기화 세부 정보를 활용하면 복제 지연을 측정할 수 있어요. 이 요청은 팔로워 클러스터로 보내세요.

엔드포인트

GET /_plugins/_replication/{follower-index}/_status

예제 요청

GET /_plugins/_replication/follower-01/_status

{% include copy-curl.html %}

예제 응답

{
  "status" : "SYNCING",
  "reason" : "User initiated",
  "leader_alias" : "my-connection-name",
  "leader_index" : "leader-01",
  "follower_index" : "follower-01",
  "syncing_details" : {
    "leader_checkpoint" : 19,
    "follower_checkpoint" : 19,
    "seq_no" : 0
  }
}

응답에 샤드 복제 세부 정보를 포함하려면 &verbose=true 파라미터를 추가하세요.

리더와 팔로워 체크포인트 값은 음의 정수로 시작하며 샤드 수를 반영해요(샤드 1개면 -1, 샤드 5개면 -5 등). 이 값은 변경을 수행할 때마다 양의 정수 방향으로 증가해요. 예를 들어 리더 인덱스를 변경하면 leader_checkpoint가 0이 돼요. follower_checkpoint는 팔로워 인덱스가 리더에서 변경 사항을 가져올 때까지 처음에는 -1인 상태로 유지되다가, 그 시점에 0으로 증가해요. 두 값이 같으면 인덱스가 완전히 동기화된 거예요.

리더 클러스터 통계 조회

1.1에서 도입 {: .label .label-purple }

지정된 클러스터에서 복제된 리더 인덱스에 대한 정보를 조회해요.

엔드포인트

GET /_plugins/_replication/leader_stats

예제 요청

GET /_plugins/_replication/leader_stats

{% include copy-curl.html %}

예제 응답

{
   "num_replicated_indices": 2,
   "operations_read": 15,
   "translog_size_bytes": 1355,
   "operations_read_lucene": 0,
   "operations_read_translog": 15,
   "total_read_time_lucene_millis": 0,
   "total_read_time_translog_millis": 659,
   "bytes_read": 1000,
   "index_stats":{
      "leader-index-1":{
         "operations_read": 7,
         "translog_size_bytes": 639,
         "operations_read_lucene": 0,
         "operations_read_translog": 7,
         "total_read_time_lucene_millis": 0,
         "total_read_time_translog_millis": 353,
         "bytes_read":466
      },
      "leader-index-2":{
         "operations_read": 8,
         "translog_size_bytes": 716,
         "operations_read_lucene": 0,
         "operations_read_translog": 8,
         "total_read_time_lucene_millis": 0,
         "total_read_time_translog_millis": 306,
         "bytes_read": 534
      }
   }
}

팔로워 클러스터 통계 조회

1.1에서 도입 {: .label .label-purple }

지정된 클러스터에서 팔로워(동기화 중) 인덱스에 대한 정보를 조회해요.

엔드포인트

GET /_plugins/_replication/follower_stats

예제 요청

GET /_plugins/_replication/follower_stats

{% include copy-curl.html %}

예제 응답

{
   "num_syncing_indices": 2,
   "num_bootstrapping_indices": 0,
   "num_paused_indices": 0,
   "num_failed_indices": 0,
   "num_shard_tasks": 2,
   "num_index_tasks": 2,
   "operations_written": 3,
   "operations_read": 3,
   "failed_read_requests": 0,
   "throttled_read_requests": 0,
   "failed_write_requests": 0,
   "throttled_write_requests": 0,
   "follower_checkpoint": 1,
   "leader_checkpoint": 1,
   "total_write_time_millis": 2290,
   "index_stats":{
      "follower-index-1":{
         "operations_written": 2,
         "operations_read": 2,
         "failed_read_requests": 0,
         "throttled_read_requests": 0,
         "failed_write_requests": 0,
         "throttled_write_requests": 0,
         "follower_checkpoint": 1,
         "leader_checkpoint": 1,
         "total_write_time_millis": 1355
      },
      "follower-index-2":{
         "operations_written": 1,
         "operations_read": 1,
         "failed_read_requests": 0,
         "throttled_read_requests": 0,
         "failed_write_requests": 0,
         "throttled_write_requests": 0,
         "follower_checkpoint": 0,
         "leader_checkpoint": 0,
         "total_write_time_millis": 935
      }
   }
}

오토 팔로우 통계 조회

1.1에서 도입 {: .label .label-purple }

지정된 클러스터에 구성된 오토 팔로우 활동과 복제 규칙에 대한 정보를 조회해요.

엔드포인트

GET /_plugins/_replication/autofollow_stats

예제 요청

GET /_plugins/_replication/autofollow_stats

{% include copy-curl.html %}

예제 응답

{
   "num_success_start_replication": 2,
   "num_failed_start_replication": 0,
   "num_failed_leader_calls": 0,
   "failed_indices":[
      
   ],
   "autofollow_stats":[
      {
         "name":"my-replication-rule",
         "pattern":"movies*",
         "num_success_start_replication": 2,
         "num_failed_start_replication": 0,
         "num_failed_leader_calls": 0,
         "failed_indices":[
            
         ]
      }
   ]
}

설정 업데이트

1.1에서 도입 {: .label .label-purple }

팔로워 인덱스의 설정을 업데이트해요.

엔드포인트

PUT /_plugins/_replication/{follower-index}/_update

예제 요청

PUT /_plugins/_replication/follower-01/_update
{
   "settings": {
      "index.number_of_shards": 4,
      "index.number_of_replicas": 2
   }
}

{% include copy-curl.html %}

예제 응답

{
   "acknowledged": true
}

복제 규칙 생성

1.1에서 도입 {: .label .label-purple }

지정된 패턴과 일치하는 인덱스에 대해 복제를 자동으로 시작해요. 리더 클러스터의 새 인덱스가 패턴과 일치하면 OpenSearch가 자동으로 팔로워 인덱스를 생성하고 복제를 시작해요. 기존 복제 규칙을 업데이트할 때도 이 API를 사용할 수 있어요.

이 요청은 팔로워 클러스터로 보내세요.

오토 팔로우 패턴을 생성한 후에는 반드시 이름을 기록해 두세요. 현재 replication 플러그인에는 기존 패턴 목록을 조회하는 API 작업이 없어요. {: .tip }

엔드포인트

POST /_plugins/_replication/_autofollow

요청 본문 필드

다음 표에서 사용 가능한 요청 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명 필수 여부
leader_alias String 크로스 클러스터 연결의 이름이에요. 이 별칭은 크로스 클러스터 연결을 설정할 때 정의해요. 예
name String 오토 팔로우 패턴의 이름이에요. 예
pattern String 지정된 리더 클러스터의 인덱스와 비교할 인덱스 패턴 배열이에요. 와일드카드 문자를 지원해요. 예를 들어 leader-*가 있어요. 예
follower_index_pattern String 팔로워 인덱스 이름의 패턴이에요. {% raw %}{{leader_index}}{% endraw %} 플레이스홀더를 사용해서 리더 인덱스 이름을 포함할 수 있어요. 예를 들어 {% raw %}{{leader_index}}{% endraw %}-replica는 <leader_index_name>-replica라는 이름의 팔로워 인덱스를 만들어요. 팔로워 클러스터에 같은 이름의 인덱스가 이미 있거나 여러 리더 클러스터에서 인덱스를 복제할 때 이름 충돌을 피하려면 이 필드를 사용하세요. 생략하면 팔로워 인덱스는 리더 인덱스와 같은 이름을 사용해요. 아니요
use_roles Object 인덱스 간 이후 모든 백엔드 복제 작업에 사용할 역할이에요. leader_cluster_role과 follower_cluster_role을 지정하세요. 자세한 내용은 리더 및 팔로워 클러스터 역할 매핑을 참고하세요. Security 플러그인이 활성화된 경우

예제 요청

POST /_plugins/_replication/_autofollow
{
   "leader_alias": "my-connection-alias",
   "name": "my-replication-rule",
   "pattern": "leader-*",
   "follower_index_pattern": "{% raw %}{{leader_index}}{% endraw %}-replica",
   "use_roles": {
      "leader_cluster_role": "cross_cluster_replication_leader_full_access",
      "follower_cluster_role": "cross_cluster_replication_follower_full_access"
   }
}

{% include copy-curl.html %}

예제 응답

{
   "acknowledged": true
}

복제 규칙 삭제

1.1에서 도입 {: .label .label-purple }

지정된 복제 규칙을 삭제해요. 이 작업을 하면 새 인덱스는 더 이상 복제되지 않지만, 규칙이 이미 시작한 기존 복제는 중지되지 않아요. 복제된 인덱스는 복제를 중지할 때까지 읽기 전용 상태로 유지돼요.

이 요청은 팔로워 클러스터로 보내세요.

엔드포인트

DELETE /_plugins/_replication/_autofollow

요청 본문 필드

다음 표에서 사용 가능한 요청 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명 필수 여부
leader_alias String 크로스 클러스터 연결의 이름이에요. 이 별칭은 크로스 클러스터 연결을 설정할 때 정의해요. 예
name String 패턴의 이름이에요. 예

예제 요청

DELETE /_plugins/_replication/_autofollow
{
   "leader_alias": "my-connection-alias",
   "name": "my-replication-rule"
}

{% include copy-curl.html %}

예제 응답

{
   "acknowledged": true
}

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.