Installing OpenSearch
출처: 문서
본문
OpenSearch 설치
OpenSearch는 Docker, Helm, OpenSearch Kubernetes Operator, tarball, RPM, Debian 패키지, Ansible, 또는 Windows에 설치할 수 있어요. 각 방법은 열어 둬야 하는 특정 포트와 호스트에 구성해야 하는 중요한 설정이 필요해요.
컴퓨터에서 OpenSearch를 직접 사용해 보려면 설치 퀵스타트를 참고하세요.
운영 체제 호환성에 대한 내용은 호환 운영 체제를 참고하세요.
설치 단계
설치 단계는 배포 방법에 따라 달라져요. 사용하는 배포 방법에 맞는 단계는 다음 설치 가이드를 참고하세요:
프로덕션용 클러스터 준비하기
설치 퀵스타트와 대부분의 가이드에 나오는 기본 설치 방법은 데모 보안 구성을 사용하는 클러스터를 만들어요. 데모 구성은 자체 서명된 데모 인증서와 알려진 내부 사용자 비밀번호를 사용하므로 테스트 용도로만 사용하도록 만들어졌어요. 클러스터를 프로덕션에서 사용하기 전에 다음 작업을 완료하세요:
- 데모 인증서를 자체 인증 기관(CA)에서 발급한 인증서로 교체하세요. 자세한 내용은 TLS 인증서 구성을 참고하세요.
- 사용자 인증 방식을 구성하세요. Security 플러그인의 내부 사용자 데이터베이스를 사용하거나, 싱글 사인온을 위해 SAML, OpenID Connect, LDAP 같은 외부 아이덴티티 프로바이더를 연결할 수 있어요. 자세한 내용은 보안 백엔드 구성을 참고하세요.
- 사용자 또는 아이덴티티 프로바이더가 제공하는 백엔드 역할을, 클러스터 접근 권한을 부여하는 역할에 매핑하세요. 자세한 내용은 사용자 및 역할 정의를 참고하세요.
- 데모 내부 사용자의 기본 비밀번호를 교체하거나, 필요 없는 사용자는 제거하세요. 자세한 내용은 데모 구성 비밀번호를 참고하세요.
- 모든 호스트에 중요한 설정을 구성하세요.
- 전용 클러스터 매니저 노드를 포함해 여러 노드를 실행하세요. 그러면 노드 하나에 장애가 발생해도 클러스터를 계속 사용할 수 있어요. 자세한 내용은 클러스터 생성을 참고하세요.
- 스냅샷을 사용해 데이터를 백업하세요. 자세한 내용은 스냅샷을 참고하세요.
보안 관련 추가 권장 사항은 OpenSearch 보안 모범 사례를 참고하세요.
파일 시스템 권장 사항
프로덕션 워크플로에서는 노드 스토리지로 네트워크 파일 시스템을 사용하지 마세요. 노드 스토리지에 네트워크 파일 시스템을 사용하면 네트워크 상태(지연 시간이나 제한된 처리량 등)나 읽기/쓰기 속도 같은 요인 때문에 클러스터에 성능 문제가 생길 수 있어요. 가능하면 호스트에 장착된 솔리드 스테이트 드라이브(SSD)를 노드 스토리지로 사용하세요.
Java 호환성
Linux용 OpenSearch 배포판은 jdk 디렉터리에 호환되는 Adoptium JDK 버전의 Java를 포함하고 있어요. JDK 버전을 확인하려면 ./jdk/bin/java -version을 실행하세요. 예를 들어 OpenSearch 1.0.0 tarball에는 Java 15.0.1+9(non-LTS)가, OpenSearch 1.3.0에는 Java 11.0.14.1+1(LTS)이, OpenSearch 2.0.0에는 Java 17.0.2+8(LTS)이 포함되어 있어요. OpenSearch는 호환되는 모든 Java 버전으로 테스트를 거쳤어요.
| OpenSearch 버전 | 호환 Java 버전 | 포함된 Java 버전 |
|---|---|---|
| 1.0--1.2.x | 11, 15 | 15.0.1+9 |
| 1.3.x | 8, 11, 14 | 11.0.25+9 |
| 2.0.0--2.11.x | 11, 17 | 17.0.2+8 |
| 2.12.0+ | 11, 17, 21 | 21.0.11+10 |
| 3.2.0+ | 21, 24 | 24.0.2+12 |
| 3.5.0+ | 21, 25 | 25.0.2+10 |
| 3.6.1+ | 21, 25, 26 | 25.0.4.1+1 |
다른 Java 설치본을 사용하려면 OPENSEARCH_JAVA_HOME 또는 JAVA_HOME 환경 변수를 Java가 설치된 위치로 설정하세요. 예를 들어:
export OPENSEARCH_JAVA_HOME=/path/to/opensearch-{{site.opensearch_version}}/jdk
{% include copy.html %}
네트워크 요구 사항
OpenSearch 컴포넌트를 위해서는 다음 TCP 포트가 열려 있어야 해요.
| 포트 번호 | OpenSearch 컴포넌트 |
|---|---|
| 443 | 전송 중 암호화(TLS)가 활성화된 AWS OpenSearch Service의 OpenSearch Dashboards |
| 5601 | OpenSearch Dashboards |
| 9200 | OpenSearch REST API |
| 9300 | 노드 통신 및 전송(내부), 크로스 클러스터 검색 |
| 9600 | Performance Analyzer |
UDP 포트는 사용하지 않아요. {: .note}
중요한 설정
Linux에서 실행되는 프로덕션 워크로드라면 Linux 설정인 vm.max_map_count가 최소 262144로 설정되어 있는지 확인하세요.
Docker 이미지를 사용하더라도 이 값은 호스트 머신에 설정해야 해요. 현재 값을 확인하려면 다음 명령어를 실행하세요:
cat /proc/sys/vm/max_map_count
{% include copy.html %}
값을 늘리려면 /etc/sysctl.conf에 다음 줄을 추가하세요:
vm.max_map_count=262144
{% include copy.html %}
그다음 설정을 다시 로드하세요:
sudo sysctl -p
{% include copy.html %}
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-compose.yml 파일에도 몇 가지 핵심 설정이 들어 있어요:
-
bootstrap.memory_lock=true스왑을 비활성화해요(
memlock과 함께). 스왑은 성능과 안정성을 크게 떨어뜨릴 수 있으므로 프로
일반적인 문제
다음 문제는 어떤 설치 방법을 사용하더라도 발생할 수 있어요.
오류 메시지: "max virtual memory areas vm.max_map_count [65530] is too low"
호스트의 vm.max_map_count 설정이 너무 낮으면 Linux에서 OpenSearch가 시작되지 않아요. 이때 OpenSearch 로그에는 다음과 같은 오류가 기록돼요:
ERROR: [1] bootstrap checks failed
[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
이 오류를 해결하려면 중요 설정에서 설명하는 것처럼 vm.max_map_count를 최소 262144로 설정하세요. Docker를 사용한다면 컨테이너가 아니라 호스트 머신에서 이 값을 설정해야 해요.
오류 메시지: "NotSslRecordException: not an SSL/TLS record"
데모 보안 설정은 REST API를 HTTPS로 제공해요. 클라이언트가 HTTP로 요청을 보내면 빈 응답을 받게 되고, OpenSearch는 요청마다 다음과 같은 오류를 기록해요:
io.netty.handler.ssl.NotSslRecordException: not an SSL/TLS record: 474554202f20485454502f312e310d0a...
이 오류를 해결하려면 http://localhost:9200 대신 https://localhost:9200으로 요청을 보내세요. OpenSearch에 연결하는 모든 클라이언트를 점검해 보세요. 여기에는 주기적으로 요청을 보내는 모니터링 도구와 호스트에서 실행 중인 다른 서비스도 포함돼요.
오류 메시지: "Password failed validation"
OPENSEARCH_INITIAL_ADMIN_PASSWORD 값이 강력한 비밀번호가 아니면 OpenSearch가 시작되지 않아요. 이때 OpenSearch 로그에는 다음과 비슷한 오류가 기록돼요:
Password admin failed validation: "Password is too short". Please re-try with a minimum 8 character password and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong.
이 오류를 해결하려면 관리자 비밀번호 요구 사항을 만족하는 비밀번호를 선택하세요.
오류 메시지: "the default discovery settings are unsuitable for production use"
OpenSearch가 localhost가 아닌 주소에 바인딩되면, 예를 들어 다른 호스트에서 접근할 수 있도록 network.host를 0.0.0.0으로 설정한 후에는 부트스트랩 검사(bootstrap checks)가 강제로 수행돼요. 노드에 디스커버리 설정이 없으면 OpenSearch가 시작되지 않고 다음과 같은 오류를 기록해요:
bound or publishing to a non-loopback address, enforcing bootstrap checks
ERROR: [1] bootstrap checks failed
[1]: the default discovery settings are unsuitable for production use; at least one of [discovery.seed_hosts, discovery.seed_providers, cluster.initial_cluster_manager_nodes / cluster.initial_master_nodes] must be configured
이 오류를 해결하려면 opensearch.yml에서 디스커버리를 설정하세요:
- 단일 노드 클러스터라면
discovery.type: single-node를 설정해요. - 멀티 노드 클러스터라면
discovery.seed_hosts와cluster.initial_cluster_manager_nodes를 설정해요. 자세한 내용은 클러스터 생성을 참고하세요.