클러스터 설정 API

클러스터 설정 API (Cluster Settings API)

클러스터 전체에 적용되는 설정을 조회하거나 수정하고 싶으시죠? 클러스터 설정 API가 OpenSearch 클러스터의 모든 노드에 적용되는 클러스터 차원의 설정을 검색하거나 수정해요. 이 API로 업데이트한 설정은 opensearch.yml 설정 파일에 정의된 것보다 우선해요.

출처: 문서

본문

1.0에서 도입

클러스터 설정 API는 OpenSearch 클러스터의 모든 노드에 적용되는 클러스터 차원의 설정을 검색하거나 수정해요. 이 API를 통해 업데이트된 설정은 opensearch.yml 설정 파일에 정의된 것보다 우선해요.

클러스터 설정 API를 다음 용도로 사용해요.

• 개별 노드 구성 파일에 접근하지 않고 클러스터가 어떻게 구성됐는지 이해하기 위해 현재 클러스터 구성을 검색할 때
• 클러스터 재시작 없이 샤드 할당 설정이나 복구 속도 수정과 같은 클러스터 동작을 동적으로 조정할 때
• 클러스터의 모든 노드에서 일관되어야 하는 설정을 관리해 균일한 동작을 보장할 때
• 클러스터 재시작 후에도 유지되지 않는 transient 설정을 사용해 테스트나 문제 해결을 위해 설정을 일시적으로 변경할 때

이 API를 사용해 클러스터 차원 설정을 관리하는 것이 구성 파일을 수동으로 편집하는 것보다 선호되는데, 그 이유는 모든 노드에 걸친 일관성을 보장하고 재시작 없이 동적 업데이트를 허용하기 때문이에요.

클러스터 설정을 업데이트할 때 변경 사항이 영구적(persistent, 클러스터 재시작 후에도 유지)이어야 하는지, 일시적(transient, 재시작 후 소거)이어야 하는지 지정할 수 있어요. persistent/transient 설정, 설정 우선순위, 설정 재설정에 대한 자세한 내용은 Configuring OpenSearch를 참고하세요.

엔드포인트

GET /_cluster/settings
PUT /_cluster/settings

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터예요. 모든 쿼리 파라미터는 선택적이에요.

Parameter	Data type	Description
cluster_manager_timeout	String	cluster manager 노드의 응답을 기다리는 시간이에요. 지원되는 시간 단위에 대한 자세한 내용은 Common parameters를 참고하세요. (기본값: 30s)
flat_settings	Boolean	설정을 평평한 형태로 반환할지 여부예요. 특히 심하게 중첩된 설정에 대해 가독성이 좋아질 수 있어요. 예를 들어 "cluster": { "max_shards_per_node": 500 }의 평평한 형태는 "cluster.max_shards_per_node": "500"이에요. (기본값: false)
include_defaults	Boolean	GET 전용이에요. true면 로컬 노드의 기본 클러스터 설정을 반환해요. (기본값: false)
timeout	String	PUT 전용이에요. 지속 시간이에요. 단위는 nanos, micros, ms(밀리초), s(초), m(분), h(시간), d(일)이 될 수 있어요. 단위 없는 0과 미지정 값을 나타내는 -1도 받아요. (기본값: 30s)
master_timeout DEPRECATED	String	(2.0 이후 deprecated: 포용적인 언어를 위해 cluster_manager_timeout을 사용하세요.) 지속 시간이에요. 단위는 nanos, micros, ms(밀리초), s(초), m(분), h(시간), d(일)이 될 수 있어요. 단위 없는 0과 미지정 값을 나타내는 -1도 받아요.

요청 본문 필드

GET 연산에는 요청 본문이 없어요. 다음 표는 PUT 연산의 요청 본문 필드를 나열해요.

Field	Data type	Description
persistent	Object	전체 클러스터 재시작 후에도 유지되는 설정이에요. 이 설정들은 클러스터 상태에 기록되며 명시적으로 변경될 때까지 유지돼요.
transient	Object	다음 전체 클러스터 재시작까지만 적용되는 설정이에요. 테스트나 문제 해결 중 임시 구성 변경에 유용해요.

persistent 또는 transient 객체 안에서 업데이트하려는 설정을 키-값 쌍으로 지정해요. 예를 들어:

{
  "persistent": {
    "cluster.max_shards_per_node": 500
  }
}

모든 클러스터 설정이 클러스터 설정 API로 동적으로 업데이트될 수 있는 것은 아니에요. API를 통해 static 설정을 구성하려고 하면 "setting [cluster.some.setting], not dynamically updateable" 오류 메시지를 받게 돼요. static 설정은 opensearch.yml 파일에 구성해야 하며 노드 재시작이 필요해요.

사용 가능한 모든 클러스터 설정의 포괄적인 목록은 Configuring OpenSearch를 참고하세요.

예시: 현재 클러스터 설정 검색하기

기본값 없이 현재 클러스터 설정을 보려면 GET 요청을 보내요.

GET /_cluster/settings

예시 응답

응답은 명시적으로 구성된 persistent 및 transient 설정을 보여줘요. 빈 객체는 해당 유형의 설정이 설정되지 않았음을 나타내요.

{
  "persistent": {
    "cluster": {
      "routing": {
        "allocation": {
          "load_awareness": {
            "flat_skew": "2"
          }
        },
      },
      "max_voting_config_exclusions": "10",
      "metadata": {
        "key": "10s"
      },
      "auto_shrink_voting_configuration": "true",
      "blocks": {
        "create_index": "false",
        "create_index.auto_release": "true"
      },
      "thread_pool": {
        "generic": {
          "max": "5"
        }
      },
      "max_shards_per_node": "500",
      "remote": {
        "my_remote_cluster": {
          "seeds": [
            "127.0.0.1:9300"
          ]
        },
        "opensearch-cluster": {
          "mode": "proxy"
        },
      },
      "no_cluster_manager_block": "write"
    },
    "indices": {
      "mapping": {
        "max_in_flight_updates": "10"
      }
    },
    "plugins": {
      "ml_commons": {
        "only_run_on_ml_node": "false",
        "mcp_server_enabled": "true",
        "native_memory_threshold": "99"
      }
    },
    "search_backpressure": {
      "mode": "monitor_only"
    },
    "action": {
      "auto_create_index": "true"
    },
    "wlm": {
      "workload_group": {
        "mode": "disabled",
        "duress_streak": "10"
      }
    },
    "admission_control": {
      "cluster": {
        "admin": {
          "cpu_usage": {
            "limit": "4"
          }
        }
      }
    },
    "script": {
      "context": {
        "field": {
          "max_compilations_rate": "75/5m",
          "cache_expire": "0ms",
          "cache_max_size": "100"
        },
        "search": {
          "max_compilations_rate": "75/5m",
          "cache_expire": "0ms",
          "cache_max_size": "100"
        },
        "ingest": {
          "max_compilations_rate": "75/5m",
          "cache_expire": "0ms",
          "cache_max_size": "100"
        }
      }
    }
  },
  "transient": {
    "cluster": {
      "max_shards_per_node": "1000"
    }
  }
}

예시: 기본 설정 포함하기

기본 설정을 포함해 모든 클러스터 설정을 검색하려면 include_defaults 파라미터를 사용해요.

GET /_cluster/settings?include_defaults=true

예시 응답

응답에 모든 기본 클러스터 설정을 포함하는 defaults 객체가 포함돼요(간결함을 위해 잘렸어요). 이는 변경하기 전에 설정 이름과 기본값을 파악하는 데 유용해요.

{
  "persistent" : {
  },
  "transient" : {
  },
  "defaults" : {
    "task_resource_tracking" : {
      "enabled" : "true"
    },
    "cluster" : {
      "metadata" : {
        "perf_analyzer" : {
          "collectors" : {
            "mode" : "0"
          },
          "state" : "0",
          "config" : {
            "overrides" : ""
          },
          "pa_node_stats_setting" : "1"
        }
      },
      "no_master_block" : "metadata_write",
      "persistent_tasks" : {
        "allocation" : {
          "enable" : "all",
          "recheck_interval" : "30s"
        }
      },
      "initial_cluster_manager_nodes" : [
        "opensearch-node1"
      ]
    }
  }
}

예시: flat settings 형식 사용하기

중첩된 설정의 가독성을 높이는 평평한 형식으로 설정을 반환하려면 flat_settings 파라미터를 사용해요.

GET /_cluster/settings?flat_settings=true

예시 응답

{
  "persistent": {
    "action.auto_create_index" : "true",
    "admission_control.cluster.admin.cpu_usage.limit" : "4",
    "cluster.auto_shrink_voting_configuration" : "true",
    "cluster.blocks.create_index" : "false",
    "cluster.blocks.create_index.auto_release" : "true",
    "cluster.max_shards_per_node" : "500",
    "cluster.max_voting_config_exclusions" : "10",
    "cluster.metadata.key" : "10s",
    "cluster.no_cluster_manager_block" : "write",
    "cluster.remote.my_remote_cluster.seeds" : [
      "127.0.0.1:9300"
    ],
    "cluster.remote.opensearch-cluster.mode" : "proxy",
    "cluster.routing.allocation.load_awareness.flat_skew" : "2",
    "cluster.thread_pool.generic.max" : "5",
    "indices.mapping.max_in_flight_updates" : "10",
    "plugins.ml_commons.mcp_server_enabled" : "true",
    "plugins.ml_commons.native_memory_threshold" : "99",
    "plugins.ml_commons.only_run_on_ml_node" : "false",
    "script.context.field.cache_expire" : "0ms",
    "script.context.field.cache_max_size" : "100",
    "script.context.field.max_compilations_rate" : "75/5m",
    "script.context.ingest.cache_expire" : "0ms",
    "script.context.ingest.cache_max_size" : "100",
    "script.context.ingest.max_compilations_rate" : "75/5m",
    "script.context.search.cache_expire" : "0ms",
    "script.context.search.cache_max_size" : "100",
    "script.context.search.max_compilations_rate" : "75/5m",
    "search_backpressure.mode" : "monitor_only",
    "wlm.workload_group.duress_streak" : "10",
    "wlm.workload_group.mode" : "disabled"
  },
  "transient": {
    "cluster.max_shards_per_node" : "1000"
  }
}

예시: persistent 설정 업데이트하기

클러스터 재시작 후에도 유지되는 설정을 업데이트하려면 persistent 객체에 포함해요.

PUT /_cluster/settings
{
  "persistent": {
    "cluster.max_shards_per_node": 500
  }
}

예시 응답

acknowledged 필드는 설정이 성공적으로 업데이트됐음을 나타내요. 응답에 업데이트된 설정이 포함돼요.

{
  "acknowledged" : true,
  "persistent" : {
    "cluster" : {
      "max_shards_per_node" : "500"
    }
  },
  "transient" : {
  }
}

예시: transient 설정 업데이트하기

설정을 일시적으로(다음 전체 클러스터 재시작까지) 업데이트하려면 transient 객체에 포함해요.

PUT /_cluster/settings
{
  "transient": {
    "indices.recovery.max_bytes_per_sec": "20mb"
  }
}

예시 응답

acknowledged 필드는 설정이 성공적으로 업데이트됐음을 나타내요. 응답에 업데이트된 설정이 포함돼요.

{
  "acknowledged" : true,
  "persistent" : {
  },
  "transient" : {
    "indices" : {
      "recovery" : {
        "max_bytes_per_sec" : "20mb"
      }
    }
  }
}

예시: 설정 재설정하기

설정을 기본값으로 재설정하려면 null을 할당해요.

PUT /_cluster/settings
{
  "transient": {
    "indices.recovery.max_bytes_per_sec": null
  }
}

예시 응답

{
  "acknowledged" : true,
  "persistent" : {
  },
  "transient" : {
  }
}

예시: 와일드카드로 여러 설정 재설정하기

여러 관련 설정을 한 번에 재설정하려면 와일드카드 패턴을 사용해요.

PUT /_cluster/settings
{
  "persistent": {
    "indices.recovery.*": null
  }
}

예시 응답

설정이 재설정되면 응답에 더 이상 나타나지 않아요. 이제 설정은 우선순위 순서의 다음 값을 사용해요.

{
  "acknowledged" : true,
  "persistent" : {
  },
  "transient" : {
  }
}

응답 필드

다음 표는 응답 필드를 나열해요.

Field	Data type	Description
acknowledged	Boolean	설정 업데이트가 클러스터에 성공적으로 적용됐는지 여부를 나타내요. PUT 응답에만 존재해요.
persistent	Object	명시적으로 구성된 모든 persistent 클러스터 설정을 포함해요. 이 객체의 설정은 전체 클러스터 재시작 후에도 유지돼요.
transient	Object	명시적으로 구성된 모든 transient 클러스터 설정을 포함해요. 이 객체의 설정은 전체 클러스터 재시작 후 소거돼요.
defaults	Object	기본값과 함께 모든 기본 클러스터 설정을 포함해요. GET 요청에서 include_defaults 파라미터가 true로 설정된 경우에만 존재해요.

보안

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인해야 해요: cluster:admin/settings/update.

관련 문서

• transient 설정, persistent 설정, 설정 우선순위에 대한 자세한 내용은 Configuring OpenSearch를 참고하세요.

더 알아보기 (Learn more)

• static 설정은 재시작 없이 변경할 수 없고 opensearch.yml에서 수정해야 해요.
• flat_settings=true로 중첩 설정의 가독성을 높이고, include_defaults=true로 기본값을 함께 볼 수 있어요.