Installing OpenSearch using Docker

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

Docker를 사용하여 OpenSearch 설치하기

Docker는 OpenSearch 클러스터를 구성하고 관리하는 과정을 크게 간소화합니다. Docker Hub 또는 Amazon Elastic Container Registry(Amazon ECR)에서 공식 이미지를 가져와서 이 가이드에 포함된 샘플 Docker Compose 파일을 사용하여 Docker Compose로 빠르게 클러스터를 배포할 수 있습니다. 숙련된 OpenSearch 사용자는 사용자 정의 Docker Compose 파일을 생성하여 배포를 추가로 사용자 지정할 수 있습니다.

Docker 컨테이너는 이식성이 뛰어나며 Docker를 지원하는 모든 호환 호스트(예: Linux, macOS, Windows)에서 실행됩니다. Docker 컨테이너의 이식성은 RPM 또는 수동 Tarball 설치와 같은 다른 설치 방법보다 유연성을 제공하며, 이러한 방법은 다운로드 및 압축 해제 후 추가 구성이 필요합니다.

이 가이드는 Linux 명령줄 인터페이스(CLI)에서 작업하는 데 익숙하다고 가정합니다. 명령 입력, 디렉터리 이동, 텍스트 파일 편집 방법을 이해하고 있어야 합니다. Docker 또는 Docker Compose에 대한 도움말은 해당 웹사이트의 공식 문서를 참조하세요. {:.note}

Docker 및 Docker Compose 설치하기

환경에 맞게 Docker를 설치하고 구성하는 방법은 Get Docker를 참조하세요. CLI를 사용하여 Docker Engine을 설치하는 경우 기본적으로 Docker는 사용 가능한 호스트 리소스에 대한 제약 조건이 없습니다. 환경에 따라 Docker에서 리소스 제한을 구성할 수 있습니다. 자세한 내용은 Runtime options with Memory, CPUs, and GPUs를 참조하세요.

Docker Desktop 사용자는 Docker Desktop을 열고 Settings → Resources를 선택하여 호스트 메모리 사용량을 최소 4GB로 설정해야 합니다. {: .tip}

Docker Compose는 사용자가 단일 명령으로 여러 컨테이너를 시작할 수 있는 유틸리티입니다. Docker Compose를 호출할 때 파일을 전달하면 Docker Compose가 해당 설정을 읽고 요청된 컨테이너를 시작합니다. Docker Compose는 Docker Desktop과 함께 자동으로 설치되지만, 명령줄 환경에서 작업하는 사용자는 Docker Compose를 수동으로 설치해야 합니다. Docker Compose 설치에 대한 정보는 공식 Docker Compose GitHub 페이지에서 확인할 수 있습니다.

Linux에서는 Docker Compose를 Docker 플러그인으로 설치할 수 있습니다. 자세한 내용은 Install the Docker Compose plugin을 참조하세요. 이 가이드의 예제는 플러그인에서 제공하는 docker compose 명령을 사용합니다. {: .tip}

중요한 호스트 설정 구성하기

Docker를 사용하여 OpenSearch를 설치하기 전에 다음 설정을 구성하세요. 이러한 설정은 서비스 성능에 영향을 줄 수 있는 가장 중요한 설정입니다. 추가 정보는 important system settings{:target='_blank'}를 참조하세요.

Linux 설정

Linux 환경에서는 다음 명령을 실행하세요:

성능을 향상시키기 위해 호스트에서 메모리 페이징 및 스와핑 성능을 비활성화합니다:
```
sudo swapoff -a
```
{% include copy.html %}
OpenSearch에서 사용할 수 있는 메모리 맵 수를 늘립니다. sysctl 구성 파일을 엽니다:
```
sudo vi /etc/sysctl.conf
```
{% include copy.html %}

다음 줄을 추가하거나 설정이 이미 존재하는 경우 값을 변경한 다음 변경 사항을 저장합니다:
```
vm.max_map_count=262144
```
{% include copy.html %}

커널 매개변수를 다시 로드합니다:
```
sudo sysctl -p
```
{% include copy.html %}

값을 확인하여 변경 사항이 적용되었는지 확인합니다:
```
cat /proc/sys/vm/max_map_count
```
{% include copy.html %}

Windows 설정

Docker Desktop을 통해 WSL을 사용하는 Windows 워크로드의 경우 Docker Desktop WSL 배포판에서 vm.max_map_count를 설정합니다. 먼저 배포판에서 셸을 엽니다:

wsl -d docker-desktop

{% include copy.html %}

그런 다음 값을 설정합니다:

sysctl -w vm.max_map_count=262144

{% include copy.html %}

Docker 컨테이너에서 OpenSearch 실행하기

공식 OpenSearch 이미지는 Docker Hub 및 Amazon ECR에서 호스팅됩니다. 이미지를 검사하려면 다음 예제와 같이 docker pull을 사용하여 개별적으로 가져올 수 있습니다.

Docker Hub:

docker pull opensearchproject/opensearch:{{ site.opensearch_version | split: "." | first }}

{% include copy.html %}

docker pull opensearchproject/opensearch-dashboards:{{ site.opensearch_version | split: "." | first }}

{% include copy.html %}

Amazon ECR:

docker pull public.ecr.aws/opensearchproject/opensearch:{{ site.opensearch_version | split: "." | first }}

{% include copy.html %}

docker pull public.ecr.aws/opensearchproject/opensearch-dashboards:{{ site.opensearch_version | split: "." | first }}

{% include copy.html %}

최신 버전이 아닌 특정 버전의 OpenSearch 또는 OpenSearch Dashboards를 다운로드하려면 참조된 위치(명령줄 또는 Docker Compose 파일)에서 이미지 태그를 수정하세요. 예를 들어 opensearchproject/opensearch:{{site.opensearch_version}}은 OpenSearch 버전 {{site.opensearch_version}}을 가져옵니다. 최신 버전을 가져오려면 opensearchproject/opensearch:latest를 사용하세요. 사용 가능한 버전은 공식 이미지 저장소를 참조하세요. {: .tip}

계속하기 전에 단일 컨테이너에 OpenSearch를 배포하여 Docker가 올바르게 작동하는지 확인해야 합니다.

Docker에서 OpenSearch를 시작합니다. OpenSearch 2.12 이상에서는 시작할 때 사용자 정의 관리자 비밀번호를 설정해야 합니다. 자세한 내용은 Setting a custom admin password를 참조하세요. 비밀번호가 충분히 강력하지 않으면 로그에 오류가 보고되고 OpenSearch가 종료됩니다:
```
docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>" opensearchproject/opensearch:latest
```
이전 버전은 시작할 때 비밀번호를 포함하지 않습니다:
```
# This command maps ports 9200 and 9600, sets the discovery type to "single-node" and requests the newest image of OpenSearch
docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:latest
```

OpenSearch가 시작될 때까지 몇 분 정도 기다린 후 포트 9200에 요청을 보냅니다. 2.12 이전 버전의 경우 기본 사용자 이름과 비밀번호는 admin입니다.

curl https://localhost:9200 -ku admin:"<custom-admin-password>"

{% include copy.html %}

다음과 같은 응답을 받아야 합니다:

{
  "name" : "a937e018cee5",
  "cluster_name" : "docker-cluster",
  "cluster_uuid" : "GLAjAG6bTeWErFUy_d-CLw",
  "version" : {
    "distribution" : "opensearch",
    "number" : <version>,
    "build_type" : <build-type>,
    "build_hash" : <build-hash>,
    "build_date" : <build-date>,
    "build_snapshot" : false,
    "lucene_version" : <lucene-version>,
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

실행 중인 컨테이너를 중지하기 전에 모든 실행 중인 컨테이너 목록을 표시하고 테스트 중인 OpenSearch 노드의 컨테이너 ID를 복사합니다. 다음 예에서 컨테이너 ID는 a937e018cee5입니다:

docker container ls

{% include copy.html %}

응답은 실행 중인 컨테이너를 나열합니다:

CONTAINER ID   IMAGE                                 COMMAND                  CREATED          STATUS          PORTS                                                                NAMES
a937e018cee5   opensearchproject/opensearch:latest   "./opensearch-docker…"   19 minutes ago   Up 19 minutes   0.0.0.0:9200->9200/tcp, 9300/tcp, 0.0.0.0:9600->9600/tcp, 9650/tcp   wonderful_boyd

컨테이너 ID를 docker stop에 전달하여 실행 중인 컨테이너를 중지합니다.
```
docker stop <containerId>
```
{% include copy.html %}

docker container ls는 중지된 컨테이너를 나열하지 않습니다. 중지된 컨테이너를 확인하려면 docker container ls -a를 사용하세요. 필요하지 않은 컨테이너는 docker container rm <containerId_1> <containerId_2> <containerId_3> [...]로 수동으로 제거하거나(중지하려는 모든 컨테이너 ID를 공백으로 구분하여 전달), 모든 중지된 컨테이너를 제거하려면 더 짧은 명령 docker container prune을 사용할 수 있습니다. {: .tip}

Docker Compose를 사용하여 OpenSearch 클러스터 배포하기

기술적으로는 한 번에 하나씩 컨테이너를 생성하여 OpenSearch 클러스터를 구축할 수 있지만, YAML 파일로 환경을 정의하고 Docker Compose가 클러스터를 관리하도록 하는 것이 훨씬 쉽습니다. 다음 섹션에는 OpenSearch 및 OpenSearch Dashboards로 미리 정의된 클러스터를 시작하는 데 사용할 수 있는 예제 YAML 파일이 포함되어 있습니다. 이러한 예제는 테스트 및 개발에 유용하지만 프로덕션 환경에는 적합하지 않습니다. Docker Compose를 사용한 경험이 없다면 예제의 사전 구조를 변경하기 전에 구문 및 형식에 대한 지침을 위해 Docker Compose specification을 검토하는 것이 좋습니다.

환경을 정의하는 YAML 파일을 Docker Compose 파일이라고 합니다. 기본적으로 docker-compose 명령은 현재 디렉터리에서 다음 이름 중 하나와 일치하는 파일을 먼저 확인합니다:

docker-compose.yml
docker-compose.yaml
compose.yml
compose.yaml

해당 파일이 현재 디렉터리에 없으면 docker-compose 명령이 실패합니다.

-f 플래그와 함께 docker-compose를 호출할 때 사용자 정의 파일 위치와 이름을 지정할 수 있습니다:

# Use a relative or absolute path to the file.
docker compose -f /path/to/your-file.yml up

Docker Compose를 사용하여 OpenSearch 클러스터를 처음 시작하는 경우 샘플 docker-compose.yml 파일을 사용하세요. 이 파일은 OpenSearch 서비스를 실행하는 두 개의 컨테이너와 OpenSearch Dashboards를 실행하는 하나의 컨테이너 등 세 개의 컨테이너로 구성된 클러스터를 생성합니다. 이러한 컨테이너는 opensearch-net이라는 브리지 네트워크를 통해 통신하며 각 OpenSearch 노드에 대해 하나씩 두 개의 볼륨을 사용합니다. 이 파일은 데모 보안 구성을 명시적으로 비활성화하지 않기 때문에 자체 서명된 TLS 인증서가 설치되고 기본 이름과 비밀번호를 가진 내부 사용자가 생성됩니다.

사용자 정의 관리자 비밀번호 설정하기

OpenSearch 2.12부터 데모 보안 구성을 설정하려면 사용자 정의 관리자 비밀번호가 필요합니다. 다음 중 하나를 수행하세요:

docker-compose.yml을 실행하기 전에 다음 명령을 사용하여 새 사용자 정의 관리자 비밀번호를 설정합니다:
```
export OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>
```
{% include copy.html %}
docker-compose.yml 파일과 같은 폴더에 OPENSEARCH_INITIAL_ADMIN_PASSWORD와 강력한 비밀번호 값을 포함하는 .env 파일을 생성합니다.

비밀번호 요구 사항

OPENSEARCH_INITIAL_ADMIN_PASSWORD에 설정한 비밀번호는 최소 길이를 충족하고 여러 문자 클래스를 포함하며 엔트로피 기반 강도 검사를 통과해야 합니다. 전체 목록은 Admin password requirements를 참조하세요.

샘플 `docker-compose.yml`

샘플 Docker Compose 파일을 호스트의 홈 디렉터리에 다운로드하세요. curl 및 wget과 같은 명령줄 유틸리티를 사용하여 파일을 다운로드하거나 웹 브라우저를 사용하여 OpenSearch Project documentation-website 저장소에서 docker-compose.yml을 수동으로 복사할 수 있습니다.

cURL을 사용하려면 다음 요청을 보내세요:

curl -O https://raw.githubusercontent.com/opensearch-project/documentation-website/{{site.opensearch_major_minor_version}}/assets/examples/docker-compose.yml

{% include copy.html %}

wget을 사용하려면 다음 요청을 보내세요:

wget https://raw.githubusercontent.com/opensearch-project/documentation-website/{{site.opensearch_major_minor_version}}/assets/examples/docker-compose.yml

{% include copy.html %}

이 파일은 opensearch-build 저장소에서 유지 관리되는 Docker Compose 파일을 기반으로 합니다.

compose 파일에서 환경 변수를 사용하여 opensearch_dashboards.yml 설정을 재정의하는 경우 모든 대문자를 사용하고 마침표를 밑줄로 바꾸세요(예: opensearch.hosts의 경우 OPENSEARCH_HOSTS 사용). 이 동작은 opensearch.yml 설정을 재정의하는 것과 일치하지 않습니다. 여기서 변환은 할당 연산자만 변경됩니다(예: opensearch.yml의 discovery.type: single-node는 docker-compose.yml에서 discovery.type=single-node로 정의됨). {: .note}

호스트의 홈 디렉터리(docker-compose.yml이 포함된)에서 분리 모드로 컨테이너를 생성하고 시작합니다:

docker compose up -d

{% include copy.html %}

서비스 컨테이너가 올바르게 시작되었는지 확인합니다:

docker compose ps

{% include copy.html %}

컨테이너가 시작되지 않은 경우 서비스 로그를 검토할 수 있습니다:

# If you don't pass a service name, docker compose will show you logs from all of the nodes
docker compose logs <serviceName>

{% include copy.html %}

일반적인 시작 오류에 대한 해결 방법은 Common issues를 참조하세요.

브라우저에서 http://localhost:5601에 연결하여 OpenSearch Dashboards에 액세스할 수 있는지 확인합니다. OpenSearch 2.12 이상에서는 구성된 사용자 이름과 비밀번호를 사용해야 합니다. 이전 버전의 경우 기본 사용자 이름과 비밀번호는 admin입니다. 배포의 보안 구성을 사용자 지정하기 전까지는 공개 인터넷에서 액세스할 수 있는 호스트에서 이 구성을 사용하지 않는 것이 좋습니다.

localhost는 원격으로 액세스할 수 없습니다. 이러한 컨테이너를 원격 호스트에 배포하는 경우 네트워크 연결을 설정하고 localhost를 호스트에 해당하는 IP 또는 DNS 레코드로 바꿔야 합니다. {: .note}

클러스터에서 실행 중인 컨테이너를 중지합니다:

docker compose down

{% include copy.html %}

docker compose down은 실행 중인 컨테이너를 중지하지만 호스트에 있는 Docker 볼륨은 제거하지 않습니다. 이러한 볼륨의 내용에 신경 쓰지 않는다면 -v 옵션을 사용하여 모든 볼륨을 삭제하세요(예: docker compose down -v). {: .tip}

OpenSearch 구성

OpenSearch의 RPM 배포판은 설치 후 많은 구성을 필요로 하는 반면, Docker로 OpenSearch 클러스터를 실행하면 컨테이너가 생성되기 전에 환경을 정의할 수 있어요. 이는 Docker나 Docker Compose를 사용할 때 모두 가능해요.

예를 들어, 다음 명령어를 살펴보세요:

docker run \
  -p 9200:9200 -p 9600:9600 \
  -e "discovery.type=single-node" \
  -v /path/to/custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml \
  opensearchproject/opensearch:latest

{% include copy.html %}

명령어의 각 부분을 검토해 보면 다음을 알 수 있어요:

포트 9200과 9600을 매핑해요 (HOST_PORT:CONTAINER_PORT).
discovery.type을 single-node로 설정해서 단일 노드 배포에서 부트스트랩 검사가 실패하지 않도록 해요.
-v 플래그를 사용해서 custom-opensearch.yml이라는 로컬 파일을 컨테이너에 전달하고, 이미지에 포함된 opensearch.yml 파일을 대체해요.
Docker Hub에서 opensearchproject/opensearch:latest 이미지를 요청해요.
컨테이너를 실행해요.

이 명령어를 샘플 docker-compose.yml 파일과 비교해 보면 포트 매핑이나 이미지 참조와 같은 몇 가지 공통 설정을 발견할 수 있어요. 하지만 이 명령어는 OpenSearch를 실행하는 단일 컨테이너만 배포하고 OpenSearch Dashboards용 컨테이너는 생성하지 않아요. 게다가 사용자 정의 TLS 인증서, 사용자, 역할을 사용하거나 추가 볼륨과 네트워크를 정의하려면 이 '한 줄' 명령어는 금방 비현실적인 크기로 커져요. 바로 여기서 Docker Compose의 유용성이 드러나요.

Docker Compose로 OpenSearch 클러스터를 구축할 때 docker-compose.yml에 모든 개별 설정을 나열하는 대신 호스트에서 컨테이너로 사용자 정의 구성 파일을 전달하는 것이 더 쉬울 수 있어요. 예제 docker run 명령어가 -v 플래그를 사용하여 호스트에서 컨테이너로 볼륨을 마운트한 것과 유사하게, compose 파일은 해당 서비스의 하위 옵션으로 마운트할 볼륨을 지정할 수 있어요. 다음의 축약된 YAML 파일은 파일이나 디렉터리를 컨테이너에 마운트하는 방법을 보여줘요. 볼륨 사용 및 구문에 대한 포괄적인 정보는 Docker 공식 문서 볼륨을 참조하세요.

services:
  opensearch-node1:
    volumes:
      - opensearch-data1:/usr/share/opensearch/data
      - ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
  opensearch-node2:
    volumes:
      - opensearch-data2:/usr/share/opensearch/data
      - ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
  opensearch-dashboards:
    volumes:
      - ./custom-opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml

{% include copy.html %}

개발용 샘플 Docker Compose 파일

예제를 바탕으로 자신만의 compose 파일을 만들고 싶다면 다음 샘플 docker-compose.yml 파일을 살펴보세요. 이 샘플 파일은 Security 플러그인이 비활성화된 상태로 두 개의 OpenSearch 노드와 하나의 OpenSearch Dashboards 노드를 생성해요. 이 샘플 파일을 시작점으로 사용하면서 기본 보안 설정 구성을 검토할 수 있어요.

services:
  opensearch-node1:
    image: opensearchproject/opensearch:latest
    container_name: opensearch-node1
    environment:
      - cluster.name=opensearch-cluster # Name the cluster
      - node.name=opensearch-node1 # Name the node that will run in this container
      - discovery.seed_hosts=opensearch-node1,opensearch-node2 # Nodes to look for when discovering the cluster
      - cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2 # Nodes eligibile to serve as cluster manager
      - bootstrap.memory_lock=true # Disable JVM heap memory swapping
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # Set min and max JVM heap sizes to at least 50% of system RAM
      - "DISABLE_INSTALL_DEMO_CONFIG=true" # Prevents execution of bundled demo script which installs demo certificates and security configurations to OpenSearch
      - "DISABLE_SECURITY_PLUGIN=true" # Disables Security plugin
    ulimits:
      memlock:
        soft: -1 # Set memlock to unlimited (no soft or hard limit)
        hard: -1
      nofile:
        soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536
        hard: 65536
    volumes:
      - opensearch-data1:/usr/share/opensearch/data # Creates volume called opensearch-data1 and mounts it to the container
    ports:
      - 9200:9200 # REST API
      - 9600:9600 # Performance Analyzer
    networks:
      - opensearch-net # All of the containers will join the same Docker bridge network
  opensearch-node2:
    image: opensearchproject/opensearch:latest
    container_name: opensearch-node2
    environment:
      - cluster.name=opensearch-cluster # Name the cluster
      - node.name=opensearch-node2 # Name the node that will run in this container
      - discovery.seed_hosts=opensearch-node1,opensearch-node2 # Nodes to look for when discovering the cluster
      - cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2 # Nodes eligibile to serve as cluster manager
      - bootstrap.memory_lock=true # Disable JVM heap memory swapping
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # Set min and max JVM heap sizes to at least 50% of system RAM
      - "DISABLE_INSTALL_DEMO_CONFIG=true" # Prevents execution of bundled demo script which installs demo certificates and security configurations to OpenSearch
      - "DISABLE_SECURITY_PLUGIN=true" # Disables Security plugin
    ulimits:
      memlock:
        soft: -1 # Set memlock to unlimited (no soft or hard limit)
        hard: -1
      nofile:
        soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536
        hard: 65536
    volumes:
      - opensearch-data2:/usr/share/opensearch/data # Creates volume called opensearch-data2 and mounts it to the container
    networks:
      - opensearch-net # All of the containers will join the same Docker bridge network
  opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:latest
    container_name: opensearch-dashboards
    ports:
      - 5601:5601 # Map host port 5601 to container port 5601
    expose:
      - "5601" # Expose port 5601 for web access to OpenSearch Dashboards
    environment:
      - 'OPENSEARCH_HOSTS=["http://opensearch-node1:9200","http://opensearch-node2:9200"]'
      - "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" # disables security dashboards plugin in OpenSearch Dashboards
    networks:
      - opensearch-net

volumes:
  opensearch-data1:
  opensearch-data2:

networks:
  opensearch-net:

{% include copy.html %}

기본 보안 설정 구성

OpenSearch 클러스터를 외부 호스트에서 사용할 수 있게 하기 전에 배포의 보안 구성을 검토하는 것이 좋아요. 첫 번째 샘플 docker-compose.yml 파일에서 DISABLE_SECURITY_PLUGIN=true로 설정하여 비활성화하지 않는 한, 번들 스크립트가 클러스터 노드에 기본 데모 보안 구성을 적용한다는 것을 기억할 거예요. 이 구성은 데모 목적으로 사용되기 때문에 기본 사용자 이름과 비밀번호가 알려져 있어요. 따라서 자체 보안 구성 파일을 만들고 volumes를 사용하여 이러한 파일을 컨테이너에 전달하는 것을 권장해요. OpenSearch 보안 설정에 대한 구체적인 지침은 보안 구성을 참조하세요.

구성에 자체 인증서를 사용하려면 필요한 모든 인증서를 compose 파일의 volumes 섹션에 추가하세요:

volumes:
  - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
  - ./admin.pem:/usr/share/opensearch/config/admin.pem
  - ./admin-key.pem:/usr/share/opensearch/config/admin-key.pem
  - ./node1.pem:/usr/share/opensearch/config/node1.pem
  - ./node1-key.pem:/usr/share/opensearch/config/node1-key.pem

{% include copy.html %}

Docker Compose 볼륨으로 OpenSearch 노드에 TLS 인증서를 추가할 때는 해당 인증서를 정의하는 사용자 정의 opensearch.yml 파일도 포함해야 해요. 예를 들어:

volumes:
  - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
  - ./admin.pem:/usr/share/opensearch/config/admin.pem
  - ./admin-key.pem:/usr/share/opensearch/config/admin-key.pem
  - ./node1.pem:/usr/share/opensearch/config/node1.pem
  - ./node1-key.pem:/usr/share/opensearch/config/node1-key.pem
  - ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml

{% include copy.html %}

compose 파일에서 지정하는 인증서는 사용자 정의 opensearch.yml 파일에 정의된 인증서와 동일해야 해요. 루트, 관리자, 노드 인증서를 자신의 것으로 교체해야 해요. 자세한 내용은 TLS 인증서 구성을 참조하세요.

plugins.security.ssl.transport.pemcert_filepath: node1.pem
plugins.security.ssl.transport.pemkey_filepath: node1-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
plugins.security.ssl.http.pemcert_filepath: node1.pem
plugins.security.ssl.http.pemkey_filepath: node1-key.pem
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
plugins.security.authcz.admin_dn:
  - CN=admin,OU=SSL,O=Test,L=Test,C=DE

{% include copy.html %}

보안 설정을 구성한 후 사용자 정의 opensearch.yml 파일은 다음 예제와 비슷할 거예요. 이 예제는 TLS 인증서와 관리자 인증서의 고유 이름(DN)을 추가하고, 몇 가지 권한을 정의하며, 상세 감사 로깅을 활성화해요.

plugins.security.ssl.transport.pemcert_filepath: node1.pem
plugins.security.ssl.transport.pemkey_filepath: node1-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
transport.ssl.enforce_hostname_verification: false
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: node1.pem
plugins.security.ssl.http.pemkey_filepath: node1-key.pem
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
plugins.security.allow_default_init_securityindex: true
plugins.security.authcz.admin_dn:
  - CN=A,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA
plugins.security.nodes_dn:
  - 'CN=N,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
plugins.security.audit.type: internal_opensearch
plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
cluster.routing.allocation.disk.threshold_enabled: false
opendistro_security.audit.config.disabled_rest_categories: NONE
opendistro_security.audit.config.disabled_transport_categories: NONE

{% include copy.html %}

전체 설정 목록은 보안을 참조하세요.

동일한 프로세스를 사용하여 /usr/share/opensearch/config/opensearch-security/config.yml에서 백엔드 구성을 지정하고, 각 YAML 파일에서 새 내부 사용자, 역할, 매핑, 작업 그룹, 테넌트를 지정할 수 있어요.

사용자 정의 구성을 포함한 전체 Docker Compose 예제

이 예제는 ${OS_VER}와 ${OSD_VER} 환경 변수를 사용하여 OpenSearch 및 OpenSearch Dashboards 버전을 지정해요. 둘 중 하나라도 설정되지 않으면 Docker Compose가 invalid reference format 오류와 함께 실패해요. 이 예제를 사용하기 전에 변수를 내보내서 버전을 설정하세요:

export OS_VER={{ site.opensearch_version }}
export OSD_VER={{ site.opensearch_dashboards_version }}

{% include copy.html %}

또는 docker-compose.yml과 같은 디렉터리에 .env 파일을 생성하세요:

OS_VER={{ site.opensearch_version }}
OSD_VER={{ site.opensearch_dashboards_version }}

{% include copy.html %}

프로덕션 배포에서는 환경 변수나 명시적 버전 태그(예: {{ site.opensearch_version }})를 사용하여 클러스터 전체에서 일관된 버전을 보장하고 예기치 않은 업데이트를 방지하는 것이 좋아요. {: .tip}

자체 인증서, internal_users.yml, roles.yml, roles_mapping.yml 및 나머지 보안 구성 파일을 생성한 후 docker-compose.yaml 파일은 다음과 유사하게 보일 거예요:

services:
  opensearch-node1:
    image: opensearchproject/opensearch:${OS_VER}
    container_name: opensearch-node1_${OS_VER}
    environment:
      - cluster.name=opensearch-cluster
      - node.name=opensearch-node1
      - discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3
      - cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3
      - bootstrap.memory_lock=true
      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml
      - ./esnode.pem:/usr/share/opensearch/config/esnode.pem
      - ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem
      - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
      - ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem
      - ./kirk.pem:/usr/share/opensearch/config/kirk.pem
      - ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml
      - ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml
      - ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml
      - ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml
      - ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml
      - ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml
      - ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml
      - ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml
      - ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml
    ports:
      - 9201:9200
      - 9600:9600
    networks:
      - opensearch-net

  opensearch-node2:
    image: opensearchproject/opensearch:${OS_VER}
    container_name: opensearch-node2_${OS_VER}
    environment:
      - cluster.name=opensearch-cluster
      - node.name=opensearch-node2
      - discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3
      - cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3
      - bootstrap.memory_lock=true
      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml
      - ./esnode.pem:/usr/share/opensearch/config/esnode.pem
      - ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem
      - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
      - ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem
      - ./kirk.pem:/usr/share/opensearch/config/kirk.pem
      - ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml
      - ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml
      - ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml
      - ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml
      - ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml
      - ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml
      - ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml
      - ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml
      - ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml
    ports:
      - 9200:9200
    networks:
      - opensearch-net

  opensearch-node3:
    image: opensearchproject/opensearch:${OS_VER}
    container_name: opensearch-node3_${OS_VER}
    environment:
      - cluster.name=opensearch-cluster
      - node.name=opensearch-node3
      - discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3
      - cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3
      - bootstrap.memory_lock=true
      - "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml
      - ./esnode.pem:/usr/share/opensearch/config/esnode.pem
      - ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem
      - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
      - ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem
      - ./kirk.pem:/usr/share/opensearch/config/kirk.pem
      - ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml
      - ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml
      - ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml
      - ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml
      - ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml
      - ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml
      - ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml
      - ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml
      - ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml
    ports:
      - 9202:9200
    networks:
      - opensearch-net

  opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:${OSD_VER}
    container_name: opensearch-dashboards_${OSD_VER}
    volumes:
      - ./opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml
      - ./opensearch_dashboards.crt:/usr/share/opensearch-dashboards/config/opensearch_dashboards.crt
      - ./opensearch_dashboards.key:/usr/share/opensearch-dashboards/config/opensearch_dashboards.key
    ports:
      - 5601:5601
    expose:
      - "5601"
    environment:
      OPENSEARCH_HOSTS: '["https://opensearch-node1:9200", "https://opensearch-node2:9200", "https://opensearch-node3:9200" ]'
    networks:
      - opensearch-net
    depends_on:
      - opensearch-node1
      - opensearch-node2
      - opensearch-node3

networks:
  opensearch-net:

{% include copy.html %}

Docker Compose를 사용하여 클러스터를 시작하세요:

docker compose up -d

{% include copy.html %}

.env 파일에 제공된 admin 사용자의 비밀번호는 internal_users.yml 파일에 제공된 비밀번호로 재정의돼요. {: .note}

플러그인 작업

사용자 정의 플러그인과 함께 OpenSearch 이미지를 사용하려면 먼저 Dockerfile을 생성해야 해요. Dockerfile 생성에 대한 정보는 Docker 공식 문서를 참조하세요.

FROM opensearchproject/opensearch:latest
RUN /usr/share/opensearch/bin/opensearch-plugin install --batch <pluginId>

그런 다음 다음 명령어를 실행하세요:

# Build an image from a Dockerfile
docker build --tag=opensearch-custom-plugin .
# Start the container from the custom image
docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>" -v /usr/share/opensearch/data opensearch-custom-plugin

또는 배포하기 전에 이미지에서 플러그인을 제거할 수도 있어요. 다음 예제 Dockerfile은 Security 플러그인을 제거해요:

FROM opensearchproject/opensearch:latest
RUN /usr/share/opensearch/bin/opensearch-plugin remove opensearch-security

{% include copy.html %}

Dockerfile을 사용하여 Security 플러그인에 사용할 자체 인증서를 전달할 수도 있어요:

FROM opensearchproject/opensearch:latest
COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-key-file.pem /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-certificate-chain.pem /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-root-cas.pem /usr/share/opensearch/config/

{% include copy.html %}

일반적인 문제

컨테이너가 시작되지 않거나 예기치 않게 종료되는 경우 다음 일반적인 문제와 제안된 해결 방법을 검토하세요.

HTTPS 엔드포인트에 대한 HTTP 요청이나 거부된 관리자 비밀번호 등 모든 설치 방법에서 발생할 수 있는 문제는 일반적인 문제를 참조하세요.

Docker 명령어에 상승된 권한이 필요함

사용자를 docker 사용자 그룹에 추가하여 sudo로 Docker 명령어를 실행할 필요를 없앨 수 있어요. 자세한 내용은 Docker의 Linux 설치 후 단계를 참조하세요.

sudo usermod -aG docker $USER

{% include copy.html %}

오류 메시지: "max virtual memory areas vm.max_map_count [65530] is too low"

호스트의 vm.max_map_count 설정이 너무 낮으면 OpenSearch가 시작되지 않아요. Linux 설정에 설명된 대로 컨테이너가 아닌 호스트 머신에서 vm.max_map_count를 설정하세요. 자세한 내용은 일반적인 문제를 참조하세요.

오류 메시지: "local node does not have quorum in voting configuration"

샘플 docker-compose.yml 파일의 데이터 볼륨은 두 노드 클러스터의 상태를 저장해요. 파일을 변경하여 discovery.type: single-node로 단일 노드를 실행하지만 기존 볼륨을 유지하면 OpenSearch가 시작되지 않고 다음과 유사한 오류를 기록해요:

cannot start with [discovery.type] set to [single-node] when local node does not have quorum in voting configuration

이 오류를 해결하려면 기존 볼륨을 제거하세요:

docker compose down -v

{% include copy.html %}

docker compose down -v 명령어는 볼륨에 저장된 모든 데이터를 삭제해요. {: .warning}

그런 다음 클러스터를 다시 시작하세요:

docker compose up -d

{% include copy.html %}

더 알아보기 (Learn more)

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

Installing OpenSearch using Docker

본문

Docker를 사용하여 OpenSearch 설치하기

Docker 및 Docker Compose 설치하기

중요한 호스트 설정 구성하기

Linux 설정

Windows 설정

Docker 컨테이너에서 OpenSearch 실행하기

Docker Compose를 사용하여 OpenSearch 클러스터 배포하기

사용자 정의 관리자 비밀번호 설정하기

비밀번호 요구 사항

샘플 docker-compose.yml

OpenSearch 구성

개발용 샘플 Docker Compose 파일

기본 보안 설정 구성

사용자 정의 구성을 포함한 전체 Docker Compose 예제

플러그인 작업

일반적인 문제

Docker 명령어에 상승된 권한이 필요함

오류 메시지: "max virtual memory areas vm.max_map_count [65530] is too low"

오류 메시지: "local node does not have quorum in voting configuration"

관련 문서

더 알아보기 (Learn more)

함께 읽는 실무 이야기

샘플 `docker-compose.yml`