ISM policies

출처: 문서

본문

ISM 정책

정책(policy)은 다음 사항들을 정의하는 엔티티로, JSON 문서 형태로 저장돼요.

• 새 인덱스의 기본 상태를 포함해, 인덱스가 가질 수 있는 *상태(state)*예요. 예를 들어 상태 이름을 "hot", "warm", "delete" 같은 식으로 지을 수 있어요. 자세한 내용은 상태를 참고하세요.
• 인덱스가 상태에 진입했을 때 플러그인이 수행하길 원하는 *액션(action)*이에요. 예를 들어 rollover 수행 같은 것들이 있죠. 자세한 내용은 액션을 참고하세요.
• 인덱스가 새 상태로 이동하기 위해 충족해야 하는 조건으로, *트랜지션(transition)*이라고 불려요. 예를 들어 인덱스가 8주보다 오래됐다면 "delete" 상태로 옮기고 싶을 수 있어요. 자세한 내용은 트랜지션을 참고하세요.

액션과 트랜지션은 상태에 연결돼요. 인덱스 크기나 나이 같은 조건이 충족되면 새 상태로의 트랜지션이 트리거되고, 상태에 진입하면 그 상태의 액션이 실행돼요.

정책을 설계하는 방식은 완전히 자유로워요. 어떤 상태든 만들 수 있고, 다른 어떤 상태로든 전환할 수 있으며, 각 상태에 원하는 만큼 액션을 지정할 수 있어요.

다음 표는 정책의 필드를 정리한 거예요.

필드 | 설명 | 타입 | 필수 여부 | 읽기 전용 :--- | :--- |:--- |:--- | policy_id | 정책의 이름이에요. | String | 예 | 예 description | 사람이 읽기 쉬운 정책 설명이에요. | String | 예 | 아니요 ism_template | 새로 생성된 인덱스에 정책을 자동으로 적용하기 위한 ISM 템플릿이에요. | Nested list of objects | 아니요 | 아니요 ism_template.index_patterns | 새로 생성된 인덱스 이름과 매칭되는 패턴이에요. | List of strings | 아니요 | 아니요 ism_template.priority | 새로 생성된 인덱스 이름에 여러 정책이 매칭될 때 어느 정책을 적용할지 고르는 데 쓰이는 우선순위예요. | Integer | 아니요 | 아니요 last_updated_time | 정책이 마지막으로 업데이트된 시간이에요. | Timestamp | 예 | 예 error_notification | 에러 알림을 위한 대상(destination)과 메시지 템플릿이에요. 대상은 Amazon Chime, Slack, webhook URL이 될 수 있어요. | Object | 아니요 | 아니요 default_state | 이 정책을 사용하는 각 인덱스의 기본 시작 상태예요. | String | 예 | 아니요 states | 정책 안에서 정의하는 상태들이에요. | Nested list of objects | 예 | 아니요

상태

상태(state)는 관리 대상 인덱스의 상태를 정의해요. 관리 대상 인덱스는 한 번에 하나의 상태에만 있을 수 있어요. 상태의 액션은 상태에 진입하는 시점에 순차적으로 실행되고, 상태의 트랜지션은 모든 액션이 완료된 후 주기적으로 검사돼요.

다음 표는 상태에 대해 정의할 수 있는 파라미터를 정리한 거예요.

필드	설명	타입	필수 여부
name	상태의 이름이에요.	String	예
actions	상태에 진입한 후 실행할 액션들이에요. 이 필드를 생략하면 상태는 아무 액션도 수행하지 않아요. 자세한 내용은 액션을 참고하세요.	Nested list of objects	아니요
transitions	다음 상태들과 그 상태로 전환하기 위해 필요한 조건이에요. 트랜지션이 하나도 없으면 정책은 자신의 작업이 끝났다고 판단하고 인덱스 관리를 멈춰요. 자세한 내용은 트랜지션을 참고하세요.	Nested list of objects	아니요

액션

액션은 정책이 특정 상태에 진입했을 때 실행할 수 있는 오퍼레이션이에요.

ISM은 액션을 정의된 순서대로 실행해요. 액션이 하나 실패하면 해당 상태의 액션 실행은 중단되고, 남은 액션들은 실행되지 않아요.

예를 들어 액션을 [A,B,C,D]로 정의했다면 ISM은 다음과 같이 동작해요:

1. 액션 A를 실행해요.
2. 클러스터 설정 plugins.index_state_management.job_interval에 따라 정해진 기간만큼 대기해요.
3. 액션 B를 실행해요.

이런 식으로 계속 이어져요.

ISM이 액션 A를 성공적으로 실행하지 못하면 액션 B, C, D는 실행되지 않아요.

필요하다면 액션의 타임아웃 시간을 정의할 수도 있어요. 타임아웃이 만료되면 ISM은 그 액션을 실패 처리해요. 타임아웃은 한 번의 시도가 아니라 액션 전체에 적용돼요. 즉, ISM이 액션을 시작하는 순간 시계가 시작되고, 액션이 조건 충족을 기다리는 동안 잡 실행 사이의 시간까지 포함해서 모든 단계와 재시도, 재시도 지연 내내 계속 흘러가요.

ISM은 관리 인덱스 잡이 실행될 때에만 시계를 확인하는데, 기본 주기는 5분이에요. 예를 들어 min_index_age가 1d로 설정된 rollover 오퍼레이션은 인덱스가 1일이 될 때까지 잡이 실행될 때마다 min_index_age를 평가해요. 따라서 timeout이 1h라면 인덱스가 조건을 충족하기 전에 액션이 실패하고 말아요.

타임아웃이 만료되면 ISM은 액션을 실패로 표시하고, 여러분이 Retry failed index API를 호출할 때까지 인덱스 관리를 멈춰요. 이 API를 호출하면 액션과 그 시계가 다시 시작돼요. 타임아웃이 됐다고 해서 ISM이 이미 시작한 작업이 중단되거나, 액션이 이미 수행한 변경이 되돌아가지는 않아요.

ISM은 잡 실행마다 한 단계씩 처리하므로, 타임아웃은 액션에 필요한 총 시간보다 길게, 그리고 각 단계마다 잡 인터벌 하나씩 더한 값으로 잡으세요. timeout을 생략하면 액션은 절대 타임아웃되지 않고 retry 설정에 따라 계속 재시도해요.

다음 표는 액션에 대해 정의할 수 있는 파라미터를 정리한 거예요.

파라미터 | 설명 | 타입 | 필수 여부 | 기본값 :--- | :--- |:--- |:--- | timeout | 액션의 타임아웃 시간이에요. 분, 시간, 일에 해당하는 시간 단위를 사용할 수 있어요. | Time unit | 아니요 | - retry | 액션의 재시도 설정이에요. | Object | 아니요 | 액션에 따라 달라요

retry 오퍼레이션에는 다음 파라미터들이 있어요.

파라미터 | 설명 | 타입 | 필수 여부 | 기본값 :--- | :--- |:--- |:--- | count | 재시도 횟수예요. | Integer | 예 | - backoff | 재시도할 때 사용할 백오프 정책 타입이에요. 유효한 값은 Exponential, Constant, Linear예요. | String | 아니요 | Exponential delay | 재시도 사이에 대기하는 시간이에요. 분, 시간, 일에 해당하는 시간 단위를 사용할 수 있어요. | Time unit | 아니요 | 1분

액션 예제

다음 read_only 액션 예제는 타임아웃이 1시간이에요. 정책은 이 액션을 지수(exponential) 백오프 정책으로 세 번 재시도하고, 재시도 사이에는 10분씩 기다려요:

"actions": [
  {
    "timeout": "1h",
    "retry": {
      "count": 3,
      "backoff": "exponential",
      "delay": "10m"
    },
    "read_only": {}
  }
]

사용할 수 있는 단위 타입 목록은 지원되는 단위를 참고하세요.

트랜지션

트랜지션은 상태 변경을 트리거하는 조건을 정의해요. 현재 상태의 모든 액션이 완료되면 정책은 트랜지션 조건 검사를 시작해요.

ISM은 트랜지션을 정의된 순서대로 평가하고, true로 평가되는 첫 번째 트랜지션을 사용해요.

트랜지션에 조건을 하나도 지정하지 않으면 항상 true로 평가돼요. 정책이 이런 트랜지션을 검사하면 인덱스를 그 트랜지션에 정의된 상태로 즉시 전환해요.

예를 들어 트랜지션을 [A,B,C,D]로 정의했고, 트랜지션 A, B, C는 현재 false로 평가되며 D에는 조건이 없다고 가정해 봐요. ISM은 목록을 순서대로 순회하면서 다음 상태를 트랜지션 D에 정의된 상태로 설정해요. 다음 실행에서 ISM은 D가 정의한 상태에서 시작해요.

다음 표는 트랜지션에 대해 정의할 수 있는 파라미터를 정리한 거예요.

파라미터	설명	타입	필수 여부
state_name	조건이 충족됐을 때 전환할 상태의 이름이에요.	String	예
conditions	트랜지션 조건을 나열해요.	List	예

conditions 객체에는 다음 파라미터들이 있어요.

파라미터	설명	타입	필수 여부
min_index_age	전환에 필요한 인덱스의 최소 나이예요.	String	아니요
min_rollover_age	rollover가 발생한 후 다음 상태로 전환하기까지 필요한 최소 경과 시간이에요.	String	아니요
min_state_age	전환하기 전에 인덱스가 현재 상태에 머물러야 하는 최소 시간이에요.	String	아니요
min_doc_count	전환에 필요한 인덱스의 최소 문서 수예요.	Integer	아니요
min_size	전환에 필요한 프라이머리 샤드 저장소의 최소 총 크기예요(레플리카는 제외). 예를 들어 min_size를 100 GiB로 설정하고 인덱스가 각각 20 GiB인 프라이머리 샤드 5개와 레플리카 샤드 5개를 가진다면, 모든 프라이머리 샤드의 총 크기는 100 GiB이므로 인덱스는 다음 상태로 전환돼요.	String	아니요
no_alias	alias 존재 여부를 기준으로 전환을 제어해요. true이면 인덱스에 alias가 없을 때만 전환되고, false이면 최소 한 개의 alias가 존재할 때만 전환돼요.	Boolean	아니요
cron	다른 트랜지션이 먼저 일어나지 않을 경우 트랜지션을 트리거하는 cron 잡이에요.	Object	아니요
cron.cron.expression	트랜지션을 트리거하는 cron 표현식이에요. 문법은 cron 표현식을 참고하세요.	String	예
cron.cron.timezone	트랜지션을 트리거하는 cron 표현식의 시간대예요.	String	예

시간 기반 값(min_index_age, min_rollover_age, min_state_age)은 모두 표준 OpenSearch 시간 단위를 사용해요. {: .note}

다음 예제는 30일이 지나면 인덱스를 cold 상태로 전환해요:

"transitions": [
  {
    "state_name": "cold",
    "conditions": {
      "min_index_age": "30d"
    }
  }
]

ISM은 job_interval 설정에 따라 정책이 실행될 때마다 조건을 검사해요.

이 예제는 cron 조건을 사용해 매주 토요일 5:00 PT에 인덱스를 전환해요:

"transitions": [
  {
    "state_name": "cold",
    "conditions": {
      "cron": {
        "cron": {
          "expression": "* 17 * * SAT",
          "timezone": "America/Los_Angeles"
        }
      }
    }
  }
]

이 조건이 정확히 5:00 PM에 실행되지는 않는다는 점에 유의하세요. 잡은 여전히 job_interval 설정에 정의된 대로 실행되거든요. 이런 시작 시점의 편차와, 트랜지션 조건을 검사하기 전에 액션을 완료하는 데 걸릴 수 있는 시간 때문에, 지나치게 좁은 cron 표현식은 쓰지 않는 걸 권해요. 예를 들어 15 17 * * SAT(토요일 5:15 PM)는 쓰지 마세요.

이 예제에서 사용한 것처럼 1시간짜리 윈도우면 일반적으로 충분하지만, 윈도우를 놓쳐서 트랜지션 때문에 한 주를 기다리는 상황을 피하려면 2~3시간으로 늘릴 수도 있어요. 또는 * * * * SAT,SUN처럼 더 넓은 표현식을 써서 주말 동안 언제든 트랜지션이 일어나게 할 수도 있어요.

cron 표현식 작성 방법은 cron 표현식을 참고하세요.

에러 알림

error_notification은 관리 인덱스가 실패했을 때 알림을 보내요. default_state 및 states와 함께 정책 레벨에서 설정해요:

PUT _plugins/_ism/policies/hot_delete_workflow
{
  "policy": {
    "description": "hot delete workflow",
    "default_state": "hot",
    "error_notification": {
      "channel": {
        "id": "<channel_id>"
      },
      "message_template": {
        "source": "The index {% raw %}{{ctx.index}}{% endraw %} failed during policy execution."
      }
    },
    "states": [
      {
        "name": "hot",
        "actions": [],
        "transitions": []
      }
    ]
  }
}

{% include copy-curl.html %}

error_notification에는 message_template이 필요하고, destination 또는 channel 중 하나는 반드시 지정해야 해요. 따라서 빈 객체는 400으로 거절돼요. {: .note}

에러 알림은 커스텀 메시지와 함께 단일 대상 또는 알림 채널로 전송돼요.

파라미터	설명	타입	필수 여부
destination	대상 URL이에요.	Slack, Amazon Chime, or webhook URL	channel을 지정하지 않으면 필수
channel	알림 채널의 ID예요.	String	destination을 지정하지 않으면 필수
message_template	메시지 본문이에요. Mustache templates를 사용해 메시지에 변수를 추가할 수 있어요.	Object	예

대상 시스템은 반드시 응답을 반환해야 해요. 그렇지 않으면 error_notification 오퍼레이션에서 에러가 발생해요.

예제 1: Chime 알림

{
  "error_notification": {
    "destination": {
      "chime": {
        "url": "<url>"
      }
    },
    "message_template": {
      "source": "The index {% raw %}{{ctx.index}}{% endraw %} failed during policy execution."
    }
  }
}

예제 2: 커스텀 webhook 알림

{
  "error_notification": {
    "destination": {
      "custom_webhook": {
        "url": "https://<your_webhook>"
      }
    },
    "message_template": {
      "source": "The index {% raw %}{{ctx.index}}{% endraw %} failed during policy execution."
    }
  }
}

예제 3: Slack 알림

{
  "error_notification": {
    "destination": {
      "slack": {
        "url": "https://hooks.slack.com/services/xxx/xxxxxx"
      }
    },
    "message_template": {
      "source": "The index {% raw %}{{ctx.index}}{% endraw %} failed during policy execution."
    }
  }
}

예제 4: 알림 채널 사용하기

{
  "error_notification": {
    "channel": {
      "id": "some-channel-config-id"
    },
    "message_template": {
      "source": "The index {% raw %}{{ctx.index}}{% endraw %} failed during policy execution."
    }
  }
}

ctx 변수에는 Notification 오퍼레이션과 동일한 옵션을 사용할 수 있어요.

OpenSearch Dashboards의 정책

Index Management 페이지로 이동하려면 상단 메뉴에서 Management > Index Management로 가세요. State management policies를 선택하면 클러스터에 있는 정책의 목록이 표시돼요.

정책은 비주얼 에디터 또는 JSON 에디터에서 만들어요. 비주얼 에디터는 정책의 구성 요소를---오류 알림, ISM 템플릿, 상태---별도의 패널로 나타내고, 사용 가능한 액션과 전환 조건을 목록으로 보여주기 때문에 새 정책을 작성할 때는 비주얼 에디터를 사용하세요. 이미 가지고 있는 정책을 붙여넣을 때는 JSON 에디터를 사용하세요.

다음 이미지는 State management policies 페이지를 보여줘요.

정책 조회하기

1. Index Management에서 State management policies를 선택하세요.
2. Policy 열에서 정책을 선택하세요.

페이지에는 Policy settings, ISM templates, States 패널이 표시돼요. 상태의 액션과 전환을 보려면 상태 이름 옆의 {::nomarkdown}{:/} (expand) 아이콘을 선택하세요.

정책 생성하기

1. Index Management에서 State management policies를 선택한 다음 Create policy를 선택하세요.
2. Visual editor 또는 JSON editor를 선택한 다음 Continue를 선택하세요.
3. Policy info에서 정책이 하는 일을 설명하는 고유한 Policy ID(예: hot_cold_workflow)를 입력하고, 필요에 따라 설명도 입력하세요.
4. 필요에 따라 Error notification에서 정책 실행이 실패했을 때 알림을 받을 Channel ID를 선택하세요. 자세한 내용은 오류 알림을 참조하세요. 정책이 인덱스를 자동으로 롤오버하는 경우에는 이 알림을 구성하세요. 롤오버가 실패하면 예상 외로 큰 인덱스를 알려주기 때문이에요.
5. 필요에 따라 ISM templates에서 이 정책을 새 인덱스에 연결할 인덱스 패턴을 추가하세요. 자세한 내용은 ISM 템플릿 추가하기를 참조하세요.
6. States에서 Add state를 선택해 정책의 각 상태를 추가하세요. 자세한 내용은 상태 추가하기를 참조하세요. 정책에는 최소 한 개의 상태가 반드시 있어야 해요.
7. Initial state에서 새로 관리 대상이 되는 인덱스가 처음 시작되는 상태를 선택하세요.
8. Create를 선택하세요.

JSON 에디터에서는 Name policy에 정책 ID를 입력하고, Define policy에 정책을 입력한 다음 Create를 선택하세요.

상태 추가하기

Create policy 페이지의 States에서 Add state를 선택한 다음 다음을 수행하세요:

1. 인덱스 생명 주기의 단계를 설명하는 State name(예: hot, warm, delete)을 입력하세요.

2. 이미 정의해 둔 상태를 기준으로 이 상태의 위치를 지정하려면 Order에서 Add before 또는 Add after를 선택한 다음 기준이 될 상태를 선택하세요. 첫 번째 상태에서는 이 단계를 건너뛰세요.

3. 상태가 수행하는 각 오퍼레이션에 대해 다음을 수행하세요:

   1. Add action을 선택하세요.
   2. Action type을 선택하세요. 사용 가능한 타입과 파라미터는 ISM 지원 오퍼레이션을 참조하세요.
   3. 액션의 파라미터를 입력하세요. 예를 들어 snapshot 액션에는 리포지토리와 스냅샷 이름이 필요해요.
   4. 필요에 따라 액션이 실패하기까지의 Timeout 기간(예: 5h)과 Retry count, Retry backoff 정책, Retry delay(예: 1d)를 입력하세요.
   5. Add action을 선택하세요.

4. 상태에서 나가는 각 전환에 대해 다음을 수행하세요:

   1. Add transition을 선택하세요.
   2. Destination state에서 전환할 상태를 선택하세요. 상태를 자기 자신으로 전환하려면 목록에 없기 때문에 이름을 직접 입력하세요.
   3. Condition을 선택하고 해당 파라미터를 입력하세요. 예를 들어 최소 문서 수 조건에는 전환을 트리거하는 문서 수가 필요해요. 조건이 없는 전환은 항상 true로 평가돼요.
   4. Add transition을 선택하세요.

5. Save state를 선택하세요.

ISM 템플릿 추가하기

ISM 템플릿은 이름이 인덱스 패턴 중 하나와 일치하는 새 인덱스마다 정책을 연결해요:

1. Create policy 페이지의 ISM templates에서 Add template을 선택하세요.
2. Index patterns에 인덱스 패턴을 입력하세요. 예를 들어 sample-index-* 패턴은 이름이 sample-index-로 시작하는 모든 새 인덱스에 정책을 연결해요. 인덱스 패턴에는 다음 문자를 포함할 수 없어요: :, ", +, /, \, |, ?, #, >, 또는 <.
3. Priority에 패턴의 우선순위를 입력하세요. 여러 템플릿이 새 인덱스의 이름과 일치하면 ISM은 우선순위가 가장 높은 템플릿을 적용해요.
4. 필요에 따라 앞의 단계를 반복해 템플릿을 더 추가하세요.

ISM 템플릿은 템플릿이 만들어진 이후에 생성된 인덱스에만 적용돼요. 자세한 내용은 새 인덱스에 정책 연결하기를 참조하세요.

정책 편집하기

1. Index Management에서 State management policies를 선택하세요.
2. Policy 열에서 정책을 선택한 다음 Edit를 선택하세요.
3. Visual editor 또는 JSON editor를 선택하세요.
4. 정책 ID를 제외한 정책의 어떤 부분이든 변경한 다음 Update를 선택하세요.

변경 사항은 정책이 다음에 실행될 때 적용돼요. 그때까지 정책이 이미 관리하고 있는 인덱스는 캐시된 정책 버전으로 계속 진행해요. 관리 중인 인덱스를 다른 정책으로 옮기려면 관리되는 인덱스를 참조하세요.

정책 삭제하기

1. Index Management에서 State management policies를 선택하세요.
2. 삭제하려는 각 정책 옆의 체크박스를 선택한 다음 Delete를 선택하세요.
3. 확인 대화상자에서 Delete를 선택하세요.

삭제된 정책은 즉시 인덱스 관리를 중지하며 복구할 수 없어요. {: .warning}

더 알아보기 (Learn more)

• 원문 전체: https://docs.opensearch.org/latest/im-plugin/ism/policies/