스냅샷 저장소 등록 또는 업데이트 API

스냅샷 저장소 등록 또는 업데이트 API (Registering Or Updating A Snapshot Repository API)

snapshots API를 사용하면 스냅샷을 저장할 새 저장소를 등록하거나 기존 저장소의 정보를 업데이트할 수 있어요.

도입 버전 1.0

스냅샷 저장소는 다음 유형이 될 수 있어요:

• 파일 시스템(fs): fs 저장소를 만드는 방법은 Register repository shared file system을 참고하세요.
• Amazon Simple Storage Service(Amazon S3) 버킷(s3): s3 저장소를 만드는 방법은 Register repository Amazon S3를 참고하세요.
• Hadoop Distributed File System(HDFS)(hdfs): hdfs 저장소를 만드는 방법은 Register an HDFS repository를 참고하세요.

저장소를 만드는 방법은 Register repository를 참고하세요.

엔드포인트

POST /_snapshot/{repository}/ 
PUT /_snapshot/{repository}/

경로 파라미터

요청 파라미터

요청 파라미터는 저장소 유형에 따라 달라져요:

• fs
• s3
• hdfs

공통 파라미터

다음 표는 fs와 s3 저장소 모두에서 사용할 수 있는 파라미터를 보여줘요.

shard_path_type 값

shard_path_type 설정에서 지원되는 값은 다음과 같아요:

• FIXED: <ROOT>/<BASE_PATH>/indices/<index-id>/0/<SHARD_BLOBS>처럼 기존 계층 구조 방식으로 경로 구조를 유지해요.
• HASHED_PREFIX: 각 고유 샤드 ID의 경로 시작 부분에 해시 접두어를 붙여요. 예: <ROOT>/<HASH-OF-INDEX-ID-AND-SHARD-ID>/<BASE_PATH>/indices/<index-id>/0/<SHARD_BLOBS>.
• HASHED_INFIX: 각 고유 샤드 ID의 기본 경로 뒤에 해시 접두어를 붙여요. 예: <ROOT>/<BASE-PATH>/<HASH-OF-INDEX-ID-AND-SHARD-ID>/indices/<index-id>/0/<SHARD_BLOBS>. 사용되는 해시 방식은 FNV_1A_COMPOSITE_1로, FNV1a 해시 함수를 사용해 대부분의 원격 저장소 옵션에서 잘 확장되는 사용자 지정 인코딩 64비트 해시 값을 생성해요. FNV1a는 가장 중요한 6비트를 가져와 URL 안전 Base64 문자를 만들고, 다음 14비트를 가져와 이진 문자열을 만듭니다.

fs 저장소

s3 저장소

server_side_encryption 설정은 OpenSearch 3.1.0부터 제거되었어요. S3는 모든 S3 버킷의 기본 암호화 수준으로 서버 측 암호화를 적용해요. 이를 비활성화할 수 없으므로 이 저장소 설정 값은 효과가 없었어요. 자세한 내용은 Protecting data with server-side encryption을 참고하세요.

기본 server_side_encryption_type이 OpenSearch 3.8.0에서 bucket_default에서 AES256으로 변경되었어요. 업그레이드 후 명시적인 server_side_encryption_type 없이 등록된 저장소는 모든 업로드 요청에 x-amz-server-side-encryption 헤더를 보내요. 이 헤더를 거부하는 S3 호환 스토리지 서비스는 오류를 반환해요. 이전 암호화 유형으로 복원하려면 server_side_encryption_type을 bucket_default로 설정하세요. 자세한 내용은 Breaking changes를 참고하세요.

s3_async_client_type

s3_async_client_type은 단일 저장소에 적용되므로 저장소의 settings 블록에 설정하세요. repository-s3 플러그인은 s3_async_client_type을 노드 설정으로도 등록하므로 opensearch.yml 에 설정이 있으면 노드가 성공적으로 시작되고 Nodes Info API가 이를 반환하지만, 플러그인은 저장소 정의에서만 값을 읽어요. s3_async_client_type을 설정하지 않은 저장소는 opensearch.yml 에 netty가 지정되어 있어도 crt를 사용해요.

AWS Common Runtime 네이티브 라이브러리를 노드 플랫폼에서 사용할 수 없으면 플러그인은 경고를 기록하고 Netty 클라이언트를 사용해요.

저장소가 사용하는 클라이언트를 확인하려면 org.opensearch.repositories.s3.S3AsyncService 로거에 대해 DEBUG 로깅을 활성화하고 S3 Http client type 메시지를 찾으세요.

hdfs 저장소

예제 요청

다음 예제들은 서로 다른 저장소 유형을 등록하는 방법을 보여줘요.

fs

다음 예제는 로컬 디렉터리 /mnt/snapshots를 location으로 사용해 fs 저장소를 등록해요:

PUT /_snapshot/my-fs-repository
{
  "type": "fs",
  "settings": {
    "location": "/mnt/snapshots"
  }
}

s3

다음 요청은 기존 버킷 my-open-search-bucket에 my-opensearch-repo라는 새 S3 저장소를 등록해요. 기본적으로 모든 스냅샷은 my/snapshot/directory에 저장돼요:

PUT /_snapshot/my-opensearch-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-open-search-bucket",
    "base_path": "my/snapshot/directory"
  }
}

다음 요청은 기존 버킷 my-open-search-bucket에 my-opensearch-repo라는 새 S3 저장소를 등록해요. 기본적으로 모든 스냅샷은 my/snapshot/directory에 저장돼요. 또한 이 저장소는 SSE-KMS를 사용하도록 구성되며, 예상 버킷 소유자 AWS 계정 ID는 123456789000이에요.

PUT /_snapshot/my-opensearch-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-open-search-bucket",
    "base_path": "my/snapshot/directory",
    "server_side_encryption_type": "aws:kms",
    "server_side_encryption_kms_key_id": "arn:aws:kms:us-east-1:123456789000:key/kms-key-id",
    "server_side_encryption_encryption_context": "{\"additional-enc-ctx\": \"sample-context\"}",
    "expected_bucket_owner": "123456789000",
  }
}

hdfs

다음 요청은 HDFS URI hdfs://namenode:8020과 HDFS 파일 시스템 경로 /opensearch/snapshots를 사용해 새 HDFS 저장소를 등록해요:

PUT /_snapshot/my-hdfs-repository
{
  "type": "hdfs",
  "settings": {
    "uri": "hdfs://namenode:8020",
    "path": "/opensearch/snapshots"
  }
}

예제 응답

성공하면 다음 JSON 객체가 반환돼요:

{
  "acknowledged": true
}

저장소가 실제로 등록되었는지 확인하려면 Get snapshot repository API를 사용하고, repository 경로 파라미터에 저장소 이름을 전달하세요.

필요한 권한

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

출처: 문서