OpenSearch cluster configuration

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

OpenSearch 클러스터 구성

오퍼레이터는 OpenSearch 클러스터를 배포하고 관리해요. 노드 풀, TLS 인증서, 플러그인, keystore 시크릿 등 클러스터별 설정을 구성할 수 있어요.

노드 풀과 스케일링

OpenSearch 클러스터는 하나 이상의 노드 풀로 구성돼요. 각 노드 풀은 동일한 역할을 가진 노드들의 논리적 그룹이며 자체 리소스를 가질 수 있어요. 구성된 각 노드 풀에 대해 오퍼레이터는 Kubernetes StatefulSet과 Service를 생성해서 특정 노드 풀과 통신할 수 있게 해줘요:

spec:
  nodePools:
    - component: masters
      replicas: 3 # The number of replicas
      diskSize: "30Gi" # The disk size to use
      resources: # The resource requests and limits for that nodepool
        requests:
          memory: "2Gi"
          cpu: "500m"
        limits:
          memory: "2Gi"
          cpu: "500m"
      roles: # The roles the nodes should have
        - "cluster_manager"
        - "data"
    - component: nodes
      replicas: 3
      diskSize: "10Gi"
      nodeSelector:
      resources:
        requests:
          memory: "2Gi"
          cpu: "500m"
        limits:
          memory: "2Gi"
          cpu: "500m"
      roles:
        - "data"

{% include copy.html %}

스토리지, 보안 컨텍스트, 레이블, 어피니티 규칙 같은 추가 노드 풀 구성 옵션은 Kubernetes 배포 커스터마이징을 참고하세요.

opensearch.yml 구성

오퍼레이터는 여러분이 제공한 클러스터 spec의 파라미터(예: Transport Layer Security (TLS) 구성)를 기반으로 opensearch.yml 구성 파일을 자동으로 생성해요. 커스텀 설정을 추가하려면 클러스터 spec의 additionalConfig 필드를 사용하세요:

spec:
  general:
    # ...
    additionalConfig:
      some.config.option: somevalue
  # ...
nodePools:
  - component: masters
    # ...
    additionalConfig:
      some.other.config: foobar

{% include copy.html %}

spec.general.additionalConfig를 사용하면 모든 클러스터 노드에 적용되는 설정을 추가할 수 있어요. 오퍼레이터는 이 설정들을 공유 ConfigMap에 저장하고 모든 노드 풀에 마운트해요.

노드 풀별 구성에는 nodePools[].additionalConfig를 사용하세요. 오퍼레이터는 이 설정을 해당 노드 풀의 spec.general.additionalConfig와 병합하는데, 이때 노드 풀 설정이 우선해요. 노드 풀에 additionalConfig가 정의되어 있으면 병합된 구성을 담은 자체 ConfigMap을 받게 돼요.

모든 설정은 flat 형식의 문자열 맵으로 제공하세요. 문자열이 아닌 값(예: Boolean이나 숫자 값)은 "true" 또는 "1234"처럼 따옴표로 감싸세요.

오퍼레이터는 자체 생성한 설정과 여러분이 제공한 커스텀 설정을 병합해요. node.name, node.roles, cluster.name 같은 기본 설정과 네트워크 및 디스커버리 설정은 additionalConfig로 재정의할 수 없어요.

additionalConfig를 변경하면 클러스터의 롤링 재시작이 트리거돼요. 재시작을 피하려면 Cluster Settings API를 사용해서 런타임에 설정을 변경하세요. {: .note}

TLS

보안상의 이유로 OpenSearch 클러스터와의 통신과 클러스터 노드 간 통신에는 암호화가 필요해요. 암호화를 설정하지 않으면 OpenSearch는 포함된 데모 TLS 인증서를 사용하는데, 이는 실제 배포에는 적합하지 않아요.

요구 사항에 따라 오퍼레이터는 다음과 같은 TLS 인증서 관리 방법을 제공해요:

오퍼레이터 생성 인증서 (권장): 오퍼레이터가 자체 CA(Certificate Authority)를 생성하고 해당 CA로 모든 노드의 인증서에 서명해요. OpenSearch 클러스터를 Kubernetes 클러스터 외부로 직접 노출하려는 경우나 조직에 내부 통신용 자체 서명 인증서 사용에 대한 규칙이 있는 경우가 아니라면 이 옵션을 사용하세요.
자체 인증서: 여러분의 인증서를 직접 제공하세요.

오퍼레이터가 인증서를 생성할 때는 duration 필드로 인증서 유효 기간을 제어할 수 있어요(예: "720h", "17520h"). 생략하면 기본값은 1년("8760h")이에요. {: .note}

TLS 인증서는 다음 엔드포인트에 사용돼요(각각 독립적으로 구성할 수 있어요):

노드 트랜스포트
노드 HTTP REST API
OpenSearch Dashboards HTTP

노드 트랜스포트

OpenSearch 클러스터 노드는 OpenSearch 트랜스포트 프로토콜(기본 포트 9300)로 서로 통신해요. 이 엔드포인트는 외부에 노출되지 않기 때문에 거의 모든 경우 오퍼레이터 생성 인증서로 충분해요.

노드 트랜스포트 보안을 구성하려면 OpenSearchCluster 커스텀 리소스에서 다음 필드를 사용할 수 있어요:

# ...
spec:
  security:
    tls: # Everything related to TLS configuration
      transport: # Configuration of the transport endpoint
        enabled: true # Enable TLS for transport (default: true if transport config exists)
        generate: true # Have the operator generate and sign certificates
        perNode: true # Separate certificate per node
        # How long generated certificates are valid (default: 8760h = 1 year)
        duration: "8760h"
        secret:
          name: # Name of the secret that contains the provided certificate
        caSecret:
          name: # Name of the secret that contains a CA the operator should use
        nodesDn: [] # List of certificate DNs allowed to connect
# ...

{% include copy.html %}

오퍼레이터가 인증서를 생성하게 하려면 generate와 perNode를 true로 설정하세요(다른 필드는 생략할 수 있어요). 오퍼레이터는 CA 인증서를 생성하고 노드별로 인증서를 하나씩 발급한 뒤 서명해요. 인증서는 기본 유효 기간이 1년이며 duration으로 설정할 수 있어요. rotateDaysBeforeExpiry가 설정되어 있으면 만료가 임박했을 때 인증서를 재발급하는 방식으로 로테이션을 지원해요.

대신 인증서를 직접 제공할 수도 있어요(예: 조직에 내부 CA가 있는 경우). 모든 노드가 사용할 인증서 하나를 제공하거나 노드별 인증서를 제공할 수 있어요(권장). 이 모드에서는 노드별 인증서를 제공하는지에 따라 generate: false로 설정하고 perNode를 true 또는 false로 설정하세요.

인증서를 하나만 제공한다면 Kubernetes TLS 시크릿(ca.crt, tls.key, tls.crt 필드가 모두 PEM 인코딩된)에 넣고 시크릿 이름을 secret.name으로 제공하세요. CA 인증서를 분리해두려면 별도의 시크릿에 넣고 caSecret.name으로 제공하세요. 노드별 인증서를 제공한다면 모든 인증서를(ca.crt 포함) 하나의 시크릿에 넣고 노드별로 <hostname>.key와 <hostname>.crt를 두세요. 호스트명은 <cluster-name>-<nodepool-component>-<index>로 정의돼요(예: my-first-cluster-masters-0).

인증서를 직접 제공하는 경우 nodesDn에 인증서의 Distinguished Name(DN) 목록도 제공해야 해요. 와일드카드를 사용할 수 있어요(예: "CN=my-first-cluster-*,OU=my-org").

노드 HTTP REST API

각 OpenSearch 클러스터 노드는 HTTPS로 REST API를 노출해요(기본적으로 포트 9200).

HTTP API 보안을 구성하려면 OpenSearchCluster 커스텀 리소스에서 다음 필드를 사용할 수 있어요:

# ...
spec:
  security:
    tls: # Everything related to TLS configuration
      http: # Configuration of the HTTP endpoint
        enabled: true # Enable TLS for HTTP (default: true if http config exists, false to disable)
        generate: true # Have the operator generate and sign certificates
        customFQDN: "opensearch.example.com" # Optional: Custom FQDN for the certificate
        # How long generated certificates are valid (default: 8760h = 1 year)
        duration: "8760h"
        secret:
          name: # Name of the secret that contains the provided certificate
        caSecret:
          name: # Name of the secret that contains a CA the operator should use
# ...

{% include copy.html %}

오퍼레이터가 인증서를 생성하고 서명하게 하거나 직접 제공할 수 있어요. 노드 트랜스포트 인증서와 노드 HTTP REST API 인증서의 유일한 차이점은 HTTP REST API에서는 노드별 인증서를 지원하지 않는다는 거예요. 그 외에는 두 방식이 같게 동작해요.

enabled 필드는 HTTP 엔드포인트에 TLS가 활성화되어 있는지 여부를 제어해요. enabled가 false로 설정되면 클러스터는 HTTPS 대신 HTTP를 사용해요. enabled가 nil(설정되지 않음)이면 HTTP 구성이 존재할 때 기본적으로 TLS가 활성화돼요. TLS를 명시적으로 비활성화하려면 enabled: false로 설정하세요. {: .note}

생성된 인증서를 사용할 때는 customFQDN 필드를 선택적으로 지정해서 기본 클러스터 DNS 이름과 함께 인증서의 Subject Alternative Names(SAN)에 커스텀 도메인을 포함시킬 수 있어요.

자체 인증서를 제공한다면 다음 이름을 SAN으로 추가하세요: <cluster-name>, <cluster-name>.<namespace>, <cluster-name>.<namespace>.svc, <cluster-name>.<namespace>.svc.cluster.local.

노드 HTTP 포트를 Kubernetes 클러스터 외부로 직접 노출하는 건 권장되지 않아요. 대신 ingress를 구성하세요. 그러면 ingress가 공인 CA(예: Let's Encrypt)의 인증서를 제시하고 내부에서 사용되는 자체 서명 인증서를 숨길 수 있어요. 이 구성에서는 노드에 내부적으로 제대로 서명된 인증서를 제공하세요.

자체 노드 인증서를 제공한다면 오퍼레이터가 클러스터 관리에 사용할 admin 인증서도 제공해야 해요:

spec:
  security:
    config:
      adminSecret:
        name: my-first-cluster-admin-cert # The secret must have keys tls.crt and tls.key

{% include copy.html %}

인증서의 DN이 adminDn 필드에 설정되어 있는지 확인하세요.

플러그인 추가

플러그인을 사용해서 OpenSearch 기능을 확장할 수 있어요. 많이 사용되는 것은 외부 백업용(예: Amazon S3나 Microsoft Azure Blob Storage) 스냅샷 리포지토리 플러그인이에요. 오퍼레이터는 설정 중에 플러그인 자동 설치를 지원해요.

OpenSearch에 플러그인을 설치하려면 general.pluginsList에 추가하세요:

general:
  version: 3.0.0
  httpPort: 9200
  vendor: opensearch
  serviceName: my-cluster
  pluginsList:
    [
      "repository-s3",
      "https://github.com/opensearch-project/opensearch-prometheus-exporter/releases/download/3.0.0.0/prometheus-exporter-3.0.0.0.zip",
    ]

{% include copy.html %}

OpenSearch Dashboards에 플러그인을 설치하려면 dashboards.pluginsList에 추가하세요:

dashboards:
  enable: true
  version: 3.0.0
  pluginsList:
    - sample-plugin-name

{% include copy.html %}

bootstrap pod에 플러그인을 설치하려면 bootstrap.pluginsList에 추가하세요:

bootstrap:
  pluginsList: ["repository-s3"]

{% include copy.html %}

다음 사항에 유의하세요:

번들 플러그인은 자동으로 설치되므로 목록에 추가할 필요가 없어요.
플러그인 이름이나 플러그인 ZIP 파일의 전체 URL을 제공할 수 있어요. 제공한 항목은 bin/opensearch-plugin install <plugin-name> 명령에 전달돼요.
이미 설치된 클러스터의 플러그인 목록을 업데이트하면 모든 OpenSearch 노드의 롤링 재시작이 트리거돼요.
플러그인에 추가 구성이 필요하다면 additionalConfig(opensearch.yml 구성 참고)나 OpenSearch keystore의 시크릿(keystore에 시크릿 추가 참고)으로 제공하세요.

keystore에 시크릿 추가

일부 OpenSearch 기능(예: 스냅샷 리포지토리 플러그인)은 민감한 구성이 필요해요. OpenSearch는 OpenSearch keystore를 사용해서 이를 처리해요. Kubernetes 시크릿으로 이 keystore를 채울 수 있어요.

general.keystore 섹션 아래에 시크릿을 추가하세요:

general:
  # ...
  keystore:
    - secret:
        name: credentials
    - secret:
        name: some-other-secret

{% include copy.html %}

이 구성에서는 시크릿의 모든 키가 keystore의 키가 돼요.

시크릿에서 일부 키만 로드하거나 기존 키의 이름을 바꾸고 싶다면 키 매핑을 맵으로 추가할 수 있어요:

general:
  # ...
  keystore:
    - secret:
        name: many-secret-values
      keyMappings:
        # Only read "sensitive-value" from the secret, keep its name.
        sensitive-value: sensitive-value
    - secret:
        name: credentials
      keyMappings:
        # Renames key accessKey in secret to s3.client.default.access_key in keystore
        accessKey: s3.client.default.access_key
        password: s3.client.default.secret_key

{% include copy.html %}

제공된 키만 시크릿에서 로드돼요. 지정되지 않은 키는 무시돼요. {: .note}

bootstrap pod의 keystore를 채우려면 bootstrap.keystore 섹션 아래에 시크릿을 추가하세요:

bootstrap:
  # ...
  keystore:
    - secret:
        name: credentials
    - secret:
        name: some-other-secret

{% include copy.html %}

SmartScaler

SmartScaler는 오퍼레이터에 내장된 메커니즘으로, 노드를 클러스터에서 안전하게 제거할 수 있게 해줘요. 노드가 클러스터에서 제거될 때 safe drain 프로세스는 노드가 오프라인이 되기 전에 해당 노드의 모든 데이터가 클러스터의 다른 노드로 전송되는 것을 보장해요. 이를 통해 다른 노드로 데이터를 먼저 전송하지 않은 채 노드가 종료되거나 연결이 끊겼을 때 발생할 수 있는 데이터 손실이나 손상을 방지할 수 있어요.

safe drain 프로세스 동안 제거 중인 노드는 "draining"으로 표시되는데, 이는 더 이상 새 요청을 받지 않는다는 뜻이에요. 대신 워크로드가 완료될 때까지 처리 대기 중인 요청만 처리해요. 모든 요청이 처리되면 노드는 클러스터의 다른 노드로 데이터 전송을 시작해요. safe drain 프로세스는 모든 데이터가 전송되고 노드가 더 이상 클러스터의 일부가 아닐 때까지 계속돼요. 그 후에야 오퍼레이터가 노드를 종료해요.

Java 힙 크기 설정

OpenSearch 노드에 할당되는 메모리 양을 구성하려면 jvm 필드로 힙 크기를 설정하세요. 이 작업은 다운타임이 없으며 클러스터는 계속 운영 상태를 유지해요.

힙 크기는 메모리 요청량의 절반으로 설정하세요. {: .note}

spec:
  nodePools:
    - component: nodes
      replicas: 3
      diskSize: "10Gi"
      jvm: -Xmx1024M -Xms1024M
      resources:
        requests:
          memory: "2Gi"
          cpu: "500m"
        limits:
          memory: "2Gi"
          cpu: "500m"
      roles:
        - "data"

{% include copy.html %}

jvm이 제공되지 않으면 Java 힙 크기는 resources.requests.memory의 절반으로 설정돼요. 이는 데이터 노드에 권장되는 값이에요.

jvm이 제공되지 않고 resources.requests.memory도 존재하지 않으면 값은 -Xmx512M -Xms512M이에요.

`vm.max_map_count` 구성

OpenSearch는 Linux 커널 vm.max_map_count 옵션이 최소 262144로 설정되어야 해요. 오퍼레이터는 각 OpenSearch pod의 init 컨테이너를 사용해서 이 옵션을 기본적으로 262144로 설정해요. sysctl로 Kubernetes 호스트에 이 옵션을 이미 설정했고 오퍼레이터가 이를 변경하게 하고 싶지 않다면 클러스터 spec에 다음 옵션을 추가해서 비활성화하세요:

spec:
  general:
    setVMMaxMapCount: false

{% include copy.html %}

기본적으로 init 컨테이너는 busybox 이미지를 사용해요. 이를 변경하려면(예: 프라이빗 레지스트리의 이미지를 사용하려면) 커스텀 init 헬퍼를 참고하세요.

스냅샷 리포지토리 구성하기

오퍼레이터를 사용하면 OpenSearch 클러스터의 스냅샷 리포지토리를 구성할 수 있어요. general.snapshotRepositories 필드는 여러 개의 스냅샷 리포지토리를 지원해요. 스냅샷 리포지토리를 구성하고 나면, 사용자가 OpenSearch Dashboards에서 커스텀 ISM 정책을 만들어 인덱스를 백업할 수 있어요.

spec:
  general:
    snapshotRepositories:
      - name: my_s3_repository_1
        type: s3
        settings:
          bucket: opensearch-s3-snapshot
          region: us-east-1
          base_path: os-snapshot
      - name: my_s3_repository_3
        type: s3
        settings:
          bucket: opensearch-s3-snapshot
          region: us-east-1
          base_path: os-snapshot_1

{% include copy.html %}

스냅샷 리포지토리 구성을 위한 사전 요구 사항

클러스터에 snapshotRepositories를 구성하기 전에 다음 사전 요구 사항이 충족되었는지 확인하세요:

적절한 클라우드 프로바이더 네이티브 플러그인이 설치되어 있어야 해요. 예를 들면:
```
spec:
  general:
    pluginsList: ["repository-s3"]
```
{% include copy.html %}

백엔드 클라우드에 필요한 역할/권한이 미리 생성되어 있어야 해요. 다음 예시는 스냅샷을 opensearch-s3-snapshot S3 버킷에 게시할 수 있도록 Kubernetes 노드에 추가된 Amazon Web Services (AWS) Identity and Access Management (IAM) 역할을 보여줘요:

{
  "Statement": [
    {
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:ListBucketMultipartUploads",
        "s3:ListBucketVersions"
      ],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::opensearch-s3-snapshot"]
    },
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::opensearch-s3-snapshot/*"]
    }
  ],
  "Version": "2012-10-17"
}

{% include copy.html %}

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/install-and-configure/install-opensearch/operator/operator-opensearch-config/

OpenSearch cluster configuration

본문

OpenSearch 클러스터 구성

노드 풀과 스케일링

opensearch.yml 구성

TLS

노드 트랜스포트

노드 HTTP REST API

플러그인 추가

keystore에 시크릿 추가

SmartScaler

Java 힙 크기 설정

vm.max_map_count 구성

스냅샷 리포지토리 구성하기

스냅샷 리포지토리 구성을 위한 사전 요구 사항

더 알아보기 (Learn more)

함께 읽는 실무 이야기

`vm.max_map_count` 구성