스냅샷 복원 API

스냅샷 복원 API (Restore Snapshot API)

클러스터 또는 지정된 데이터 스트림과 인덱스의 스냅샷을 복원해요.

도입 버전 1.0

• 인덱스와 클러스터에 대한 정보는 Introduction to OpenSearch를 참고하세요.
• 데이터 스트림에 대한 정보는 Data streams를 참고하세요.

복원하려는 것과 같은 이름의 열린 인덱스가 클러스터에 이미 존재한다면 해당 인덱스를 닫거나, 삭제하거나, 이름을 바꿔야 해요. 인덱스 이름 바꾸기에 대한 정보는 예제 요청을, 인덱스 닫기에 대한 정보는 Close index를 참고하세요.

엔드포인트

POST _snapshot/{repository}/{snapshot}/_restore

경로 파라미터

쿼리 파라미터

요청 본문 필드

모든 요청 본문 파라미터는 선택 사항이에요.

1클러스터 상태에는 다음이 포함돼요:

• 영구 클러스터 설정(Persistent cluster settings)
• 인덱스 템플릿
• 레거시 인덱스 템플릿
• Ingest 파이프라인
• 인덱스 수명 주기 정책

예제 요청

다음 예제들은 서로 다른 스냅샷 복원 시나리오를 보여줘요.

기본 복원

다음 요청은 my-first-snapshot에서 opendistro-reports-definitions 인덱스를 복원해요. rename_pattern과 rename_replacement 조합으로 인해 클러스터에 중복된 열린 인덱스 이름이 허용되지 않으므로 인덱스 이름이 opendistro-reports-definitions_restored로 바뀌어요.

POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore
{
  "indices": "opendistro-reports-definitions",
  "ignore_unavailable": true,
  "include_global_state": false,
  "rename_pattern": "(.+)",
  "rename_replacement": "$1_restored",
  "include_aliases": false
}

원격 지원 저장소를 사용한 크로스 클러스터 복원

원격 지원 저장소(remote-backed storage)는 OpenSearch가 세그먼트와 트랜스로그를 원격 저장소에 자동으로 백업하는 기능이에요. 둘 다 원격 지원 저장소를 사용하고 원격 저장소 저장소가 다른 클러스터 간에 스냅샷을 복원할 때는 source_remote_store_repository와 source_remote_translog_repository 파라미터를 모두 사용하세요.

다음 예제는 원본 클러스터에서 찍은 스냅샷의 인덱스를 대상 클러스터로 복원해요. 이 예제에서 source-cluster-snapshots는 원본 클러스터의 스냅샷이 들어 있는 스냅샷 저장소, snapshot-1은 스냅샷 이름, my-remote-index는 복원할 인덱스, source-remote-segment-repo는 원본 클러스터의 원격 세그먼트 저장소(대상 클러스터에서 읽기 전용으로 등록되어야 함), source-remote-translog-repo는 원본 클러스터의 원격 트랜스로그 저장소(대상 클러스터에서 읽기 전용으로 등록되어야 함)예요:

POST /_snapshot/source-cluster-snapshots/snapshot-1/_restore
{
  "indices": "my-remote-index",
  "source_remote_store_repository": "source-remote-segment-repo",
  "source_remote_translog_repository": "source-remote-translog-repo"
}

대상 클러스터는 인덱스를 복원하고 원본 클러스터의 원격 저장소 저장소에서 원격 세그먼트와 트랜스로그를 읽도록 구성해요.

전체 단계별 절차는 Restoring snapshots across remote-backed clusters를 참고하세요.

복원된 백킹 인덱스를 데이터 스트림에 연결

도입 버전 3.8

이 기능은 실험적이며 프로덕션 환경에서 사용하지 않는 것이 좋아요. 기능 진행 상황에 대한 업데이트나 피드백을 남기고 싶다면 관련 GitHub issue를 참고하세요.

복원된 백킹 인덱스를 같은 이름의 기존 데이터 스트림에 연결하려면 attach_to_data_stream을 true로 설정하세요. 복원된 인덱스 이름은 .ds-<data_stream>-NNNNNN 백킹 인덱스 규칙과 일치해야 하고, 인덱스는 스트림의 타임스탬프 필드를 date로 매핑해야 해요. 다음 요청은 .ds-logs-foo-000001 백킹 인덱스를 복원해 기존 logs-foo 데이터 스트림에 연결하며, 필요에 따라 스트림 세대를 전진시켜요:

POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore
{
  "indices": ".ds-logs-foo-000001",
  "attach_to_data_stream": true
}

스냅샷에서 인덱스를 복원하지 않고 데이터 스트림의 백킹 인덱스를 추가하거나 제거하려면 Modify Data Stream API를 사용하세요.

예제 응답

성공하면 응답이 다음 JSON 객체를 반환해요:

{
  "snapshot" : {
    "snapshot" : "my-first-snapshot",
    "indices" : [ ],
    "shards" : {
      "total" : 0,
      "failed" : 0,
      "successful" : 0
    }
  }
}

스냅샷 이름을 제외한 모든 속성이 비어 있거나 0이에요. 이는 스냅샷이 생성된 후 볼륨에서 이루어진 변경 사항이 모두 손실되기 때문이에요. 하지만 Get snapshot API를 호출해 스냅샷을 살펴보면 완전히 채워진 스냅샷 객체가 반환돼요.

응답 본문 필드

다음 표는 사용 가능한 모든 응답 본문 필드를 보여줘요.

스냅샷 안의 열린 인덱스가 클러스터에 이미 존재하고, 그것을 삭제·닫기·이름 바꾸기를 하지 않으면 API는 다음처럼 오류를 반환해요:

{
  "error" : {
    "root_cause" : [
      {
        "type" : "snapshot_restore_exception",
        "reason" : "[my-opensearch-repo:my-first-snapshot/dCK4Qth-TymRQ7Tu7Iga0g] cannot restore index [.opendistro-reports-definitions] because an open index with same name already exists in the cluster. Either close or delete the existing index or restore the index under a different name by providing a rename pattern and replacement name"
      }
    ],
    "type" : "snapshot_restore_exception",
    "reason" : "[my-opensearch-repo:my-first-snapshot/dCK4Qth-TymRQ7Tu7Iga0g] cannot restore index [.opendistro-reports-definitions] because an open index with same name already exists in the cluster. Either close or delete the existing index or restore the index under a different name by providing a rename pattern and replacement name"
  },
  "status" : 500
}

필요한 권한

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인하세요: cluster:admin/snapshot/restore.

출처: 문서