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

Getting started with cross-cluster replication

원문 보기 위키 갱신

출처: 문서

본문

크로스 클러스터 복제 시작하기

크로스 클러스터 복제를 사용하면 리더 인덱스에 데이터를 색인하고, OpenSearch가 그 데이터를 하나 이상의 읽기 전용 팔로워 인덱스로 복제해요. 문서 생성, 업데이트, 삭제 같은 리더에 대한 모든 후속 작업은 팔로워에도 복제돼요.

사전 요구 사항

크로스 클러스터 복제를 설정하기 전에 다음 사전 요구 사항이 충족되었는지 확인하세요:

  • 리더 클러스터와 팔로워 클러스터 모두에 replication plugin이 설치되어 있어야 해요.

  • 팔로워 클러스터의 노드에서 opensearch.yml의 node.roles를 재정의했다면, node.roles 설정에 remote_cluster_client 역할이 포함되어 있는지 확인하세요:

    node.roles: [<other_roles>, remote_cluster_client]

    {% include copy.html %}

권한

Security plugin이 두 클러스터 모두에서 활성화되어 있거나 두 클러스터 모두에서 비활성화되어 있는지 확인하세요. Security plugin을 비활성화했다면 이 섹션은 건너뛰어도 돼요. 하지만 프로덕션 시나리오에서는 Security plugin을 활성화하는 것을 강력히 권장해요.

Security plugin이 활성화되어 있다면, 비관리자 사용자가 복제 작업을 수행할 수 있도록 적절한 권한에 매핑되어 있는지 확인하세요. 인덱스 및 클러스터 수준 권한 요구 사항은 크로스 클러스터 복제 권한을 참조하세요.

또한 팔로워에서 리더로의 연결을 허용하려면, 각 팔로워 클러스터 노드의 고유 이름(DN)을 확인해서 리더 클러스터에 추가해야 해요.

먼저 각 팔로워 클러스터에서 노드의 DN을 가져오세요:

curl -XGET -k -u 'admin:<custom-admin-password>' 'https://localhost:9200/_opendistro/_security/api/ssl/certs?pretty'

{
 "transport_certificates_list": [
    {
       "issuer_dn" : "CN=Test,OU=Server CA 1B,O=Test,C=US",
       "subject_dn" : "CN=follower.test.com", # To be added under leader's nodes_dn configuration
       "not_before" : "2021-11-12T00:00:00Z",
       "not_after" : "2022-12-11T23:59:59Z"
    }
 ]
}

그다음 opensearch.yml의 리더 클러스터 설정에 해당 DN이 포함되어 있는지 확인하세요. 포함되어 있지 않다면 다음 설정 아래에 추가하세요:

plugins.security.nodes_dn:
- "CN=*.leader.com, OU=SSL, O=Test, L=Test, C=DE" # Already part of the configuration
- "CN=follower.test.com" # From the above response from follower

예제 설정

같은 네트워크에서 두 개의 단일 노드 클러스터를 시작하려면, 이 샘플 파일을 docker-compose.yml로 저장하고 docker compose up을 실행하세요:

version: '3'
services:
  replication-node1:
    image: opensearchproject/opensearch:{{site.opensearch_version}}
    container_name: replication-node1
    environment:
      - cluster.name=leader-cluster
      - discovery.type=single-node
      - bootstrap.memory_lock=true
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
    ulimits:
      memlock:
        soft: -1
        hard: -1
    volumes:
      - opensearch-data2:/usr/share/opensearch/data
    ports:
      - 9201:9200
      - 9700:9600 # required for Performance Analyzer
    networks:
      - opensearch-net
  replication-node2:
    image: opensearchproject/opensearch:{{site.opensearch_version}}
    container_name: replication-node2
    environment:
      - cluster.name=follower-cluster
      - discovery.type=single-node
      - bootstrap.memory_lock=true
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
    ulimits:
      memlock:
        soft: -1
        hard: -1
    volumes:
      - opensearch-data1:/usr/share/opensearch/data
    ports:
      - 9200:9200
      - 9600:9600 # required for Performance Analyzer
    networks:
      - opensearch-net

volumes:
  opensearch-data1:
  opensearch-data2:

networks:
  opensearch-net:

클러스터가 시작되면 각 클러스터의 이름을 확인하세요:

curl -XGET -u 'admin:<custom-admin-password>' -k 'https://localhost:9201'
{
  "cluster_name" : "leader-cluster",
  ...
}

curl -XGET -u 'admin:<custom-admin-password>' -k 'https://localhost:9200'
{
  "cluster_name" : "follower-cluster",
  ...
}

이 예제에서는 포트 9201(replication-node1)을 리더로, 포트 9200(replication-node2)을 팔로워 클러스터로 사용해요.

리더 클러스터의 IP 주소를 가져오려면, 먼저 컨테이너 ID를 확인하세요:

docker ps
CONTAINER ID    IMAGE                                       PORTS                                                      NAMES
3b8cdc698be5    opensearchproject/opensearch:{{site.opensearch_version}}   0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp   replication-node2
731f5e8b0f4b    opensearchproject/opensearch:{{site.opensearch_version}}   9300/tcp, 0.0.0.0:9201->9200/tcp, 0.0.0.0:9700->9600/tcp   replication-node1

그다음 해당 컨테이너의 IP 주소를 가져오세요:

docker inspect --format='{% raw %}{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}{% endraw %}' 731f5e8b0f4b
172.22.0.3

크로스 클러스터 연결 설정

크로스 클러스터 복제는 "pull" 모델을 따르기 때문에, 대부분의 변경은 리더 클러스터가 아닌 팔로워 클러스터에서 발생해요.

원격 클러스터 연결 모드

연결 모드에는 _sniff mode_와 _proxy mode_가 있어요.

sniff mode에서는 팔로워 클러스터가 이름과 리더 클러스터의 시드 노드 목록을 지정해서 리더 클러스터에 원격 연결을 설정해요. 연결 설정 과정에서 팔로워 클러스터는 제공된 시드 노드 중 하나에서 리더 클러스터의 상태를 가져와요. 이 모드에서는 리더 클러스터에 있는 시드 노드들의 publish 주소를 팔로워 클러스터에서 접근할 수 있어야 해요. sniff mode가 기본 연결 모드예요.

팔로워 클러스터에서 각 시드 노드의 IP 주소(포트 9300 포함)를 추가하세요. 단일 노드 클러스터이기 때문에 시드 노드는 하나뿐이에요. 연결에 알아보기 쉬운 이름을 지정하세요. 이 이름은 복제를 시작하는 요청에서 사용하게 돼요:

curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9200/_cluster/settings?pretty' -d '
{
  "persistent": {
    "cluster": {
      "remote": {
        "my-connection-alias": {
          "seeds": ["172.22.0.3:9300"]
        }
      }
    }
  }
}'

proxy mode에서는 팔로워 클러스터가 이름과 단일 프록시 주소를 지정해서 리더 클러스터에 원격 연결을 설정해요. 연결 설정 과정에서 제공된 프록시 주소로 설정 가능한 개수만큼의 소켓 연결이 열려요. 프록시는 이 연결들을 리더 클러스터의 적절한 노드로 전달하는 역할을 담당해요. 다른 연결 모드와 달리, proxy mode는 리더 클러스터의 노드가 공개적으로 접근 가능한 publish 주소를 가질 필요가 없어요:

curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9200/_cluster/settings?pretty' -d '
{
  "persistent": {
    "cluster": {
      "remote": {
        "my-connection-alias": {
          "mode": "proxy"
          "proxy_address": "172.22.0.3:9300"
        }
      }
    }
  }
}'

복제 시작하기

시작하려면 리더 클러스터에 leader-01이라는 인덱스를 생성하세요:

curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9201/leader-01?pretty'

그다음 팔로워 클러스터에서 복제를 시작하세요. 요청 본문에 복제하려는 연결 이름과 리더 인덱스, 그리고 사용하려는 보안 역할을 함께 제공하세요:

curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d '
{
   "leader_alias": "my-connection-alias",
   "leader_index": "leader-01",
   "use_roles":{
      "leader_cluster_role": "all_access",
      "follower_cluster_role": "all_access"
   }
}'

Security plugin이 비활성화되어 있다면 use_roles 파라미터는 생략하세요. 하지만 활성화되어 있다면, OpenSearch가 요청을 인증할 때 사용할 리더 및 팔로워 클러스터 역할을 반드시 지정해야 해요. 이 예제에서는 단순화를 위해 all_access를 사용하지만, 각 클러스터에서 복제 전용 사용자를 생성하고 그에 맞게 매핑하는 것을 권장해요. {: .tip }

이 명령은 팔로워 클러스터에 follower-01이라는 이름의 동일한 읽기 전용 인덱스를 생성하고, 이 인덱스는 리더 클러스터의 leader-01 인덱스 변경 사항을 지속적으로 따라가며 업데이트돼요. 복제를 시작하면 새로운 팔로워 인덱스가 생성돼요---기존 인덱스를 팔로워 인덱스로 변환할 수는 없어요.

복제 확인하기

복제가 시작되면 상태를 조회하세요:

curl -XGET -k -u 'admin:<custom-admin-password>' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty'

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

가능한 상태는 SYNCING, BOOTSTRAPPING, PAUSED, REPLICATION NOT IN PROGRESS예요.

리더와 팔로워의 checkpoint 값은 음수로 시작하며 샤드 개수를 반영해요 (샤드 1개면 -1, 샤드 5개면 -5 등). 이 값은 변경이 있을 때마다 증가하며, 팔로워가 리더보다 얼마나 뒤처져 있는지를 보여줘요. 인덱스가 완전히 동기화되면 두 값은 같아져요.

복제가 실제로 이루어지고 있는지 확인하려면 리더 인덱스에 문서를 추가하세요:

curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9201/leader-01/_doc/1?pretty' -d '{"The Shining": "Stephen King"}'

그다음 팔로워 인덱스에서 복제된 내용을 검증하세요:

curl -XGET -k -u 'admin:<custom-admin-password>' 'https://localhost:9200/follower-01/_search?pretty'

{
  ...
  "hits": [{
    "_index": "follower-01",
    "_id": "1",
    "_score": 1.0,
    "_source": {
      "The Shining": "Stephen King"
    }
  }]
}

.replication-metadata-store 인덱스

.replication-metadata-store 인덱스는 클러스터 내부에서 복제 관련 메타데이터와 auto-follow 규칙을 저장하는 영구 데이터 저장소예요. 리더 클러스터에서 팔로워 클러스터로 복제되는 각 인덱스의 복제 메타데이터를 저장해요.

첫 번째 복제 API 호출이 트리거되면 팔로워 클러스터 내부에 .replication-metadata-store 인덱스가 생성돼요. 복제 작업이나 규칙에 대한 업데이트나 추가 사항도 이 인덱스에 반영돼요. 이를 통해 플러그인은 클러스터 전반에 걸친 복제 상태와 규칙에 대한 포괄적인 기록을 유지할 수 있어요.

.replication-metdata-store는 숨김 인덱스예요. {: .note}

복제 일시 중지 및 재개

문제를 해결하거나 리더 클러스터의 부하를 줄여야 하는 경우, 인덱스의 복제를 일시적으로 중지할 수 있어요:

curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9200/_plugins/_replication/follower-01/_pause?pretty' -d '{}'

복제가 일시 중지되었는지 확인하려면 상태를 조회하세요:

curl -XGET -k -u 'admin:<custom-admin-password>' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty'

{
  "status" : "PAUSED",
  "reason" : "User initiated",
  "leader_alias" : "my-connection-alias",
  "leader_index" : "leader-01",
  "follower_index" : "follower-01"
}

변경을 마쳤다면 복제를 재개하세요:

curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9200/_plugins/_replication/follower-01/_resume?pretty' -d '{}'

복제가 재개되면 팔로워 인덱스는 복제가 일시 중지된 동안 리더 인덱스에 적용된 모든 변경 사항을 가져와요.

retention lease 기간보다 오래 일시 중지된 복제는 retention lease가 만료되기 때문에 재개할 수 없어요. 복구하려면 force-resume을 사용하세요. force-resume은 리더의 스냅샷에서 팔로워 인덱스를 복원해요. 자세한 내용은 복제 강제 재개를 참조하세요.

복제 중지

인덱스를 더 이상 복제할 필요가 없다면, 팔로워 클러스터에서 복제를 종료하세요:

curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:<custom-admin-password>' 'https://localhost:9200/_plugins/_replication/follower-01/_stop?pretty' -d '{}'

복제를 중지하면 팔로워 인덱스는 리더를 더 이상 따르지 않고, 쓰기 가능한 일반 인덱스가 돼요. 복제를 중지한 후에는 다시 시작할 수 없어요.

인덱스가 더 이상 복제되지 않는지 확인하려면 상태를 조회하세요:

curl -XGET -k -u 'admin:<custom-admin-password>' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty'

{
  "status" : "REPLICATION NOT IN PROGRESS"
}

리더 인덱스에 변경을 가하고 그 변경이 팔로워 인덱스에 나타나지 않는지 확인하면, 복제가 중지되었는지 더 확실하게 확인할 수 있어요.

더 알아보기 (Learn more)

함께 읽는 실무 이야기

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