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

Snapshot Management API

원문 보기 위키 갱신

출처: 문서

본문

스냅샷 관리 API

스냅샷 관리(SM) API를 사용하면 스냅샷 생성을 자동화할 수 있어요.

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

정책 생성 또는 업데이트

2.1부터 도입됨 {: .label .label-purple }

SM 정책을 생성하거나 업데이트해요.

엔드포인트

생성:

POST _plugins/_sm/policies/{policy_name}

업데이트:

PUT _plugins/_sm/policies/{policy_name}?if_seq_no=0&if_primary_term=1

업데이트 요청에는 seq_no와 primary_term 파라미터를 반드시 제공해야 해요.

요청 예시

POST _plugins/_sm/policies/daily-policy
{
  "description": "Daily snapshot policy",
  "creation": {
    "schedule": {
      "cron": {
        "expression": "0 8 * * *",
        "timezone": "UTC"
      }
    },
    "time_limit": "1h"
  },
  "deletion": {
    "schedule": {
      "cron": {
        "expression": "0 1 * * *",
        "timezone": "America/Los_Angeles"
      }
    },
    "condition": {
      "max_age": "7d",
      "max_count": 21,
      "min_count": 7
    },
    "time_limit": "1h",
    "snapshot_pattern": "external-backup-*"
  },
  "snapshot_config": {
    "date_format": "yyyy-MM-dd-HH:mm",
    "timezone": "America/Los_Angeles",
    "indices": "*",
    "repository": "s3-repo",
    "ignore_unavailable": "true",
    "include_global_state": "false",
    "partial": "true",
    "metadata": {
      "any_key": "any_value"
    }
  },
  "notification": {
    "channel": {
      "id": "NC3OpoEBzEoHMX183R3f"
    },
    "conditions": {
      "creation": true,
      "deletion": false,
      "failure": false,
      "time_limit_exceeded": false
    }
  }
}

응답 예시

{
  "_id" : "daily-policy-sm-policy",
  "_version" : 5,
  "_seq_no" : 54983,
  "_primary_term" : 21,
  "sm_policy" : {
    "name" : "daily-policy",
    "description" : "Daily snapshot policy",
    "schema_version" : 15,
    "creation" : {
      "schedule" : {
        "cron" : {
          "expression" : "0 8 * * *",
          "timezone" : "UTC"
        }
      },
      "time_limit" : "1h"
    },
    "deletion" : {
      "schedule" : {
        "cron" : {
          "expression" : "0 1 * * *",
          "timezone" : "America/Los_Angeles"
        }
      },
      "condition" : {
        "max_age" : "7d",
        "min_count" : 7,
        "max_count" : 21
      },
      "time_limit" : "1h",
      "snapshot_pattern" : "external-backup-*"
    },
    "snapshot_config" : {
      "indices" : "*",
      "metadata" : {
        "any_key" : "any_value"
      },
      "ignore_unavailable" : "true",
      "timezone" : "America/Los_Angeles",
      "include_global_state" : "false",
      "date_format" : "yyyy-MM-dd-HH:mm",
      "repository" : "s3-repo",
      "partial" : "true"
    },
    "schedule" : {
      "interval" : {
        "start_time" : 1656425122909,
        "period" : 1,
        "unit" : "Minutes"
      }
    },
    "enabled" : true,
    "last_updated_time" : 1656425122909,
    "enabled_time" : 1656425122909,
    "notification" : {
      "channel" : {
        "id" : "NC3OpoEBzEoHMX183R3f"
      },
      "conditions" : {
        "creation" : true,
        "deletion" : false,
        "failure" : false,
        "time_limit_exceeded" : false
      }
    }
  }
}

파라미터

SM 정책을 생성/업데이트할 때 다음 파라미터를 지정할 수 있어요.

파라미터 타입 설명
description String SM 정책에 대한 설명이에요. 선택 사항이에요.
enabled Boolean 생성 시 이 SM 정책을 활성화할지 여부예요. 선택 사항이에요.
snapshot_config Object 스냅샷 생성을 위한 설정 옵션이에요. 필수예요.
snapshot_config.date_format String 스냅샷 이름은 <policy_name>-<date>-<random number> 형식을 가져요. date_format은 스냅샷 이름에서 날짜의 형식을 지정해요. OpenSearch가 지원하는 모든 날짜 형식을 지원해요. 선택 사항이에요. 기본값은 "yyyy-MM-dd'T'HH:mm:ss"예요.
snapshot_config.date_format_timezone String 스냅샷 이름은 <policy_name>-<date>-<random number> 형식을 가져요. date_format_timezone은 스냅샷 이름에서 날짜의 시간대를 지정해요. 선택 사항이에요. 기본값은 UTC예요.
snapshot_config.indices String 스냅샷에 포함할 인덱스 이름이에요. 여러 인덱스 이름은 ,로 구분해요. 와일드카드(*)를 지원해요. 선택 사항이에요. 기본값은 *(모든 인덱스)예요.
snapshot_config.repository String 스냅샷을 저장할 리포지토리예요. 필수예요.
snapshot_config.ignore_unavailable Boolean 사용할 수 없는 인덱스를 무시할지 여부예요. 선택 사항이에요. 기본값은 false예요.
snapshot_config.include_global_state Boolean 클러스터 상태를 포함할지 여부예요. 보안 플러그인 고려 사항 때문에 기본값은 true예요.
snapshot_config.partial Boolean 부분 스냅샷을 허용할지 여부예요. 선택 사항이에요. 기본값은 false예요.
snapshot_config.metadata Object 키-값 쌍 형태의 메타데이터예요. 선택 사항이에요.
creation Object 스냅샷 생성을 위한 설정이에요. OpenSearch 3.3 이상에서는 선택 사항이에요. 중요: 모든 노드가 OpenSearch 3.3 이상으로 업그레이드되기 전까지는 이 값을 설정하지 않은 채로 두면 안 돼요.
creation.schedule String 스냅샷을 생성하는 데 사용되는 cron 스케줄이에요. 필수예요.
creation.time_limit String 스냅샷 생성이 끝나기를 기다리는 최대 시간을 설정해요. time_limit이 스냅샷 생성 예약 간격보다 길면 time_limit이 지날 때까지 예약된 스냅샷은 생성되지 않아요. 예를 들어 time_limit이 35분으로 설정되어 있고 자정부터 30분 간격으로 스냅샷을 생성한다면, 00:00과 01:00의 스냅샷은 생성되지만 00:30의 스냅샷은 건너뛰게 돼요. 선택 사항이에요.
deletion Object 스냅샷 삭제를 위한 설정이에요. 선택 사항이에요. 기본값은 모든 스냅샷을 보존하는 거예요.
deletion.schedule String 스냅샷을 삭제하는 데 사용되는 cron 스케줄이에요. 선택 사항이에요. 기본값은 필수 항목인 creation.schedule을 사용하는 거예요.
deletion.time_limit String 스냅샷 삭제가 끝나기를 기다리는 최대 시간을 설정해요. 선택 사항이에요.
deletion.condition Object 스냅샷 삭제 조건이에요. 필수예요.
deletion.condition.max_count Integer 보존할 스냅샷의 최대 개수예요. 선택 사항이에요. max_age, max_count 중 하나 또는 둘 다를 반드시 지정해야 해요.
deletion.condition.max_age String 스냅샷이 보존되는 최대 시간이에요. 선택 사항이에요. max_age, max_count 중 하나 또는 둘 다를 반드시 지정해야 해요.
deletion.condition.min_count Integer 보존할 스냅샷의 최소 개수예요. 선택 사항이에요. 기본값은 1이에요.
deletion.snapshot_pattern String 삭제에 포함할 추가 스냅샷 패턴이에요. 정책 자체의 스냅샷 외에 지정된 패턴과 일치하는 스냅샷도 삭제할 수 있어요. 와일드카드(*)를 지원해요. 선택 사항이에요.
notification Object SM 이벤트에 대한 알림을 정의해요. 선택 사항이에요.
notification.channel Object 알림에 사용할 채널을 정의해요. SM 알림을 설정하기 전에 알림 채널을 생성하고 구성해야 해요. 필수예요.
notification.channel.id String 알림에 사용되는 채널의 채널 ID예요. 생성된 모든 채널의 채널 ID를 가져오려면 GET _plugins/_notifications/configs를 사용하세요. 필수예요.
notification.conditions Object 알림을 받고 싶은 SM 이벤트예요. 관심 있는 항목은 true로 설정하세요.
notification.conditions.creation Boolean 스냅샷 생성에 대한 알림을 받을지 여부예요. 선택 사항이에요. 기본값은 true예요.
notification.conditions.deletion Boolean 스냅샷 삭제에 대한 알림을 받을지 여부예요. 선택 사항이에요. 기본값은 false예요.
notification.conditions.failure Boolean 생성 또는 삭제 실패에 대한 알림을 받을지 여부예요. 선택 사항이에요. 기본값은 false예요.
notification.conditions.time_limit_exceeded Boolean 스냅샷 작업이 time_limit보다 오래 걸릴 때 알림을 받을지 여부예요. 선택 사항이에요. 기본값은 false예요.

정책 조회

2.1부터 도입됨 {: .label .label-purple }

SM 정책을 조회해요.

엔드포인트

모든 SM 정책 조회:

GET _plugins/_sm/policies

쿼리 문자열을 사용해 페이징, 정렬 기준 필드, 정렬 순서를 지정할 수 있어요:

GET _plugins/_sm/policies?from=0&size=20&sortField=sm_policy.name&sortOrder=desc&queryString=*

특정 SM 정책 조회:

GET _plugins/_sm/policies/{policy_name}

요청 예시

GET _plugins/_sm/policies/daily-policy

응답 예시

{
  "_id" : "daily-policy-sm-policy",
  "_version" : 6,
  "_seq_no" : 44696,
  "_primary_term" : 19,
  "sm_policy" : {
    "name" : "daily-policy",
    "description" : "Daily snapshot policy",
    "schema_version" : 15,
    "creation" : {
      "schedule" : {
        "cron" : {
          "expression" : "0 8 * * *",
          "timezone" : "UTC"
        }
      },
      "time_limit" : "1h"
    },
    "deletion" : {
      "schedule" : {
        "cron" : {
          "expression" : "0 1 * * *",
          "timezone" : "America/Los_Angeles"
        }
      },
      "condition" : {
        "max_age" : "7d",
        "min_count" : 7,
        "max_count" : 21
      },
      "time_limit" : "1h",
      "snapshot_pattern" : "external-backup-*"
    },
    "snapshot_config" : {
      "metadata" : {
        "any_key" : "any_value"
      },
      "ignore_unavailable" : "true",
      "include_global_state" : "false",
      "date_format" : "yyyy-MM-dd-HH:mm",
      "repository" : "s3-repo",
      "partial" : "true"
    },
    "schedule" : {
      "interval" : {
        "start_time" : 1656341042874,
        "period" : 1,
        "unit" : "Minutes"
      }
    },
    "enabled" : true,
    "last_updated_time" : 1656341042874,
    "enabled_time" : 1656341042874
  }
}

Explain

2.1부터 도입됨 {: .label .label-purple }

지정된 모든 정책의 활성화/비활성화 상태와 메타데이터를 제공해요. 여러 정책 이름은 ,로 구분해요. 원하는 정책을 와일드카드 패턴으로 지정할 수도 있어요.

SM 상태 머신{: width="150" style="float: left; margin-right: 15px;" }

SM은 스냅샷 생성과 삭제에 상태 머신을 사용해요. 왼쪽 이미지는 CREATION_START 상태에서 CREATION_FINISHED 상태까지 생성 워크플로의 한 실행 주기를 보여줘요. 삭제 워크플로는 생성 워크플로와 같은 패턴을 따라요.

생성 워크플로는 CREATION_START 상태에서 시작해 생성 cron 스케줄의 조건이 충족되는지 계속 확인해요. 조건이 충족되면 생성 워크플로는 CREATION_CONDITION_MET 상태로 전환된 다음 CREATING 상태로 넘어가요. CREATING 상태에서는 Create Snapshot API를 비동기로 호출한 뒤 CREATION_FINISHED 상태에서 스냅샷 생성이 끝나기를 기다려요. 스냅샷 생성이 끝나면 생성 워크플로는 다시 CREATION_START 상태로 돌아가고 주기가 계속돼요. metadata.creation과 metadata.deletion의 current_state 필드는 상태 머신의 현재 상태를 반환해요.

엔드포인트

GET _plugins/_sm/policies/{policy_names}/_explain

요청 예시

GET _plugins/_sm/policies/daily*/_explain

응답 예시

{
  "policies" : [
    {
      "name" : "daily-policy",
      "creation" : {
        "current_state" : "CREATION_START",
        "trigger" : {
          "time" : 1656403200000
        }
      },
      "deletion" : {
        "current_state" : "DELETION_START",
        "trigger" : {
          "time" : 1656403200000
        }
      },
      "policy_seq_no" : 44696,
      "policy_primary_term" : 19,
      "enabled" : true
    }
  ]
}

다음 표는 응답에서 각 정책의 모든 필드를 정리한 거예요.

필드 설명
name SM 정책의 이름이에요.
creation 가장 최근 생성 작업에 대한 정보예요. 다음 하위 필드를 참고하세요.
deletion 가장 최근 삭제 작업에 대한 정보예요. 다음 하위 필드를 참고하세요.
policy_seq_no
policy_primary_term		 SM 정책의 버전이에요.
enabled 정책이 실행 중인가요?

다음 표는 각 정책의 creation과 deletion 객체에 있는 모든 필드를 정리한 거예요.

필드 설명
current_state 앞 섹션에서 설명한 것처럼 스냅샷 생성/삭제를 실행하는 상태 머신의 현재 상태예요.
trigger.time 다음 생성/삭제 실행 시간이에요. epoch로부터 밀리초 단위예요.
latest_execution 가장 최근 생성/삭제 실행을 설명해요.
latest_execution.status 가장 최근 생성/삭제의 실행 상태예요. 가능한 값은 다음과 같아요:
IN_PROGRESS: 스냅샷 생성/삭제가 시작됐어요.
SUCCESS: 스냅샷 생성/삭제가 성공적으로 끝났어요.
RETRYING: 생성/삭제 시도가 실패했어요. 세 번 재시도해요.
FAILED: 세 번의 재시도 후에도 생성/삭제 시도가 실패했어요. 현재 실행 주기를 끝내고 다음 실행 주기로 넘어가요.
TIME_LIMIT_EXCEEDED: 생성/삭제 시간이 정책에 설정된 time_limit을 초과했어요. 현재 실행 주기를 끝내고 다음 실행 주기로 넘어가요.
latest_execution.start_time 가장 최근 실행의 시작 시간이에요. epoch로부터 밀리초 단위예요.
latest_execution.end_time 가장 최근 실행의 종료 시간이에요. epoch로부터 밀리초 단위예요.
latest_execution.info.message 가장 최근 실행의 상태를 설명하는 사용자 친화적인 메시지예요.
latest_execution.info.cause 가장 최근 실행이 실패하면 실패 원인을 담고 있어요.
retry.count 남은 실행 재시도 횟수예요.

정책 시작

2.1부터 도입됨 {: .label .label-purple }

enabled 플래그를 true로 설정해서 정책을 시작해요.

엔드포인트

POST  _plugins/_sm/policies/{policy_name}/_start

요청 예시

POST  _plugins/_sm/policies/daily-policy/_start

응답 예시

{
  "acknowledged" : true
}

정책 중지

2.1부터 도입됨 {: .label .label-purple }

SM 정책의 enabled 플래그를 false로 설정해요. 시작하기 전까지는 정책이 실행되지 않아요.

엔드포인트

POST  _plugins/_sm/policies/{policy_name}/_stop

요청 예시

POST  _plugins/_sm/policies/daily-policy/_stop

응답 예시

{
  "acknowledged" : true
}

정책 삭제

2.1부터 도입됨 {: .label .label-purple }

지정된 SM 정책을 삭제해요.

엔드포인트

DELETE  _plugins/_sm/policies/{policy_name}

요청 예시

DELETE _plugins/_sm/policies/daily-policy

응답 예시

{
  "_index" : ".opendistro-ism-config",
  "_id" : "daily-policy-sm-policy",
  "_version" : 8,
  "result" : "deleted",
  "forced_refresh" : true,
  "_shards" : {
    "total" : 2,
    "successful" : 2,
    "failed" : 0
  },
  "_seq_no" : 45366,
  "_primary_term" : 20
}

더 알아보기 (Learn more)

함께 읽는 실무 이야기

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