• 본 문서는 2025년 12월 22일 기준으로 작성되었습니다.

• Elasticsearch 9.2.0, Kibana 9.2.0 버전을 기준으로 기술하였습니다.

머리말

 클러스터를 잘 관리하고 있는지, 놓친 설정들은 없는지, 점검을 어떻게 해야하는 지는 클러스터를 운영하는 관리자라면 늘 하는 고민거리일 것입니다. 특히, 설정이나 옵션 자체를 모르면 올바르게 사용하고 있는지 알 수 가 없고, 똑같은 스펙을 사용해도 비효율적으로 사용하게 될 수 있습니다.

 이번 포스팅에서는 이러한 고민거리를 해결하고자, 클러스터 점검 시 기본적으로 사용하는 API들을 소개하고 안정적인 클러스터 운영을 위한 기본적인 서버 내 시스템 설정들과 엘라스틱서치의 옵션들, 그리고 몇 가지 장애 예방 방법을 소개하고자 합니다. 

상태 점검 API

클러스터

GET _cluster/health

 가장 기본이 되는 상태 점검 API 입니다. 클러스터의 상태(Green, Yellow, Red) 및 미할당 샤드(Unassigned shard)를 확인 가능합니다.

• status

  • green: 미할당 샤드 없음

  • yellow: 레플리카 샤드가 미할당 상태

  • red: 프라이머리 샤드가 미할당 상태

• unassigned shards: 미할당 샤드 개수. 만약 할당이 안된 샤드가 존재하면 숫자가 표시되며, 이 경우 샤드 API를 사용하여 원인 파악 진행.

• active_shards_percent_as_number: 할당된 샤드 퍼센트. 노드 재시작이나 장애 상황 복구 시, 이 샤드 퍼센트를 통해 진행률을 확인 가능

샤드

GET _cluster/allocation/explain

 클러스터 내에 미할당 샤드가 있는 원인을 알려주는 API입니다. GET _cluster/health API에서 unassigned shards가 있을 경우 사용합니다. 미할당 샤드에 대해 설명을 하는 API이기 때문에, 정상적인 경우라면 에러를 반환하고, 클러스터가 비정상적인 상태면 미할당 원인을 반환합니다. 아래는 클러스터가 정상인 상태에서 API를 사용한 경우로, 이 때는 unassigned shards가 없다며 error를 반환합니다.

GET _cat/shards?v=true&h=index,shard,prirep,state,node,ip,unassigned.reason&s=state&index={인덱스명}

 클러스터 내에 미할당 샤드가 있다면 위 API를 통해 참조를 할 수 도 있습니다.

노드

 GET _cat/nodes?v&s=name

 클러스터의 모든 노드 상태를 확인합니다. 마스터 노드 할당 상태, JVM Heap 사용률, CPU 사용률을 확인할 수 있습니다. ram.percent는 높을 수 있습니다. 엘라스틱서치가 Heap 메모리와 나머지 메모리를 사용하기 때문입니다. 단, heap.percent는 70~80%를 넘지 않는 것이 좋습니다. 경험적으로 80%를 넘어가면 클러스터가 불안정해지기 시작하며, JVM이 높아질 수 록 GC(Garbage Collection) overhead가 발생할 수 있습니다.(JVM Overhead 공식문서)

 만약 master 노드(사진 상 * 표시가 있는 노드)의 heap.percent가 80% 이상이라면, 마스터 노드의 메모리를 증설 후 jvm.options 파일에서 -Xms 및 -Xmx 값을 증가시키는 것을 권장드립니다.(JVM 값 공식문서) 기본적으로 JVM은 서버 메모리의 절반을 지정하나, 31G를 넘지 않는 것을 권장합니다. 31G를 넘으면 COOP(Compressd Ordinary Object Pointers) 이슈가 발생합니다.

 메모리 증설이 불가능하다면 클러스터 전체의 샤드 수를 줄이는 것을 권장합니다. 엘라스틱서치의 마스터노드는 샤드의 메타데이터 정보를 Heap에 올려둡니다. 이에 따라 샤드 개수가 많을 수 록 마스터노드의 JVM 부하가 커지며, 마스터노드가 작업을 할 수 있는 메모리 공간이 줄어듭니다. 7버전 기준 권장 샤드 수는 데이터 노드당 600개 이며, 8버전 기준 1000개입니다. 즉, 3개의 데이터노드를 사용 중이라면 권장 샤드 개수는 3000개입니다. 특히 클러스터내에 20G 미만의 작은 샤드들이 있는 인덱스가 많은 경우, ILM을 통해 추후에는 20~50G의 샤드 크기를 유지하도록 지정하는 것을 권장합니다.

GET _cat/allocation?v&h=node,ip,disk.percent,disk.total,disk.used,disk.avail,shards&s=node

 노드별 디스크 사용률과 샤드 할당 개수를 확인합니다. 만약 미할당된 샤드가 있으면 가장 위에 UNASSIGNED 라고 표기가 나옵니다. elasticsearch.yml 상에 명시된 path.data 기반으로 현재 사용 가능한 디스크 양을 출력합니다. 만약 path.data 명시되지 않았다면 elasticsearch 홈 디렉토리 아래의 data 디렉토리입니다. 디스크 사용률을 확인하고 만약 사용가능한 디스크 공간이 부족하다면 디스크 증설, 필요없는 인덱스 삭제, ILM 주기 조정 등으로 디스크 여유 공간을 늘립니다. 디스크 사용량이 85%가 넘어가면 disk watermark가 발생합니다.(Disk Watermark 에러 공식문서)

프로즌 노드의 경우 예외적으로 90% 이상을 사용하는 것이 정상입니다. 프로즌 노드는 기본적으로 사용가능한 디스크의 90%를 Searchable Snapshot의 캐시로서 사용합니다. 그 외 노드는 disk watermark인 85% 아래로 유지하는 것을 권장드립니다. disk watermark 수치는 따로 조정이 가능하며 필요에 따라 증감 할 수 있습니다.(Disk Watermark 설정 공식문서)

GET _cat/indices?v&h=health,index,pri,rep,doc.count,store.size,pri.store.size&s=pri.store.size:desc

 만약 디스크 사용률이 높고, 인덱스를 삭제해야한다면 위 cat indices API를 통해 용량이 큰 인덱스 순으로 정렬하여 현재 클러스터에서 용량을 많이 차지하는 인덱스들을 확인할 수 있습니다. 이를 기반으로 필요없는 인덱스들은 삭제하거나 ILM을 통해 보관 주기를 조정하여. 클러스터 용량을 확보해나가면 되겠습니다.

태스크

GET _cat/pending_tasks?v

 지연중인 태스크 목록을 확인합니다. 만약 지연중인 태스크가 없다면 header 외 아무것도 나오지 않습니다. 지연중인 항목이 있다면 클러스터가 바쁜 상태로, 태스크에 따라 search 또는 index 작업에 대한 조정이 필요합니다.

주요 시스템 설정 점검

 엘라스틱서치에는 몇 가지 중요한 권장 시스템 설정이 있습니다. (주요 시스템 설정 공식 문서) 보통 리눅스 환경에 엘라스틱서치를 설치하게 될텐데요, 이 리눅스 서버들에 TCP Transmission, JVM, Swap, Memory Lock, Max File Open 등 여러가지 주요 설정들이 되어있어야 엘라스틱서치가 정상 작동합니다. 공식문서에서 소개하는 중요 옵션들을 기술하며, 여기에 없지만 운영에 있어 중요한 설정들도 기술하고자 합니다.

시스템 자원 제한 설정

/etc/security/limits.conf

 주요 시스템 리소스 제한을 상향하여, 엘라스틱서치가 사용 가능한 서버 리소스 양을 증가시킵니다. 유저명을 명시하고 제한할 옵션과 수치를 작성합니다.

• nofile: 열 수 있는 최대 파일 개수, 최소 권장 수치 65535

• nproc : 실행 가능한 최대 프로세스 개수, 최소 권장 수치 4096

• fsize : 최대 파일 크기

• memlock : 최대 고정 메모리 공간 크기

• soft : 기본값

• hard: 최대값

서비스 파일

 엘라스틱서치를 서비스 파일로 실행중이라면 서비스파일에도 주요 시스템 자원 설정을 동일하게 해줍니다. 일반적으로  서비스파일은 /usr/lib/systemd/system/elasticsearch.service 경로에 있습니다.

메모리 매핑 설정

/etc/sysctl.conf

• vm.max_map_count=262144

 엘라스틱서치가 메모리에 매핑할 수 있는 파일 수를 증가시키며, 대량의 샤드를 쿼리하는 경우 등에 사용됩니다. 이 파일에 설정 값을 쓰고, sysctl -p 명령어로 적용해야 최종적으로 적용됩니다. 262144는 권장 설정이며, 경우에 따라 더 늘리는 것은 괜찮습니다. 이 값을 적게 설정하는 경우에는 아래와 같은 에러가 발생할 수 있습니다.

• Bootstrap Check Fail

  • bootstrap checks failed – max virtual memory areas vm.max_map_count [65535] is too low, increase to at least [262144]

  • 최대 가상 메모리 공간이 부족함

• MMAP Failed

  • mmap failed, Too many open files in system 

  • 프로세스가 메모리에 매핑할 수 있는 파일 개수 초과

스왑 메모리 설정

/etc/fstab

 swap이 들어간 줄을 주석처리합니다. 서버가 스왑메모리를 사용하지 않도록 하며, 디스크를 메모리로 사용하지 않고 실제 메모리에서만 작업이 이루어지므로 속도가 더 빠릅니다. 임시 방편으로는 swapoff -a를 사용할 수 있지만, 재시작시 초기화 되므로 fstab에서 지우는 것이 명확합니다. 엘라스틱서치는 자체적으로 힙 메모리를 정리하기 때문에, 오히려 스왑메모리를 사용하는 것이 GC를 수 분까지 느리게 만들기도 합니다.

/etc/sysctl.conf

• vm.swappiness=1

 스왑 메모리 사용을 차단하는 옵션입니다. 1로 설정하면 스왑 미사용, 0일 경우 사용입니다.

네트워크 설정

/etc/sysctl.conf

• net.ipv4.tcp_retries2=5

 TCP 통신 에러시 재시도 횟수를 감소시킵니다. TCP 통신 에러 재시도 횟수 기본값은 15이고, 15번 재시도 하는데에는 900초가 걸립니다. 재시도 횟수가 늘 수 록 간격이 길어지기 때문에 5로 감소시키면 5번의 재시도에는 15초만 소요됩니다. 값을 변경하지 않으면 노드 간 TCP 통신 재시도 소요시간이 길어지고, 만약 노드의 장애 상황이 발생했을 때에는 장애를 감지하기 까지의 시간이 길어지게 됩니다.

• net.core.rmem_default: 기본 수신 버퍼 크기, 16777216 (16MB)

• net.core.rmem_max: 최대 수신 버퍼 크기, 16777216 (16MB)

• net.core.wmem_default: 기본 송신 버퍼 크기, 16777216 (16MB)

• net.core.wmem_max: 최대 송신 버퍼 크기, 16777216 (16MB)

• net.ipv4.udp_rmem_min: UDP 소켓 수신 버퍼의 최소 크기, 16384 (16KB)

 위 설정은 UDP로 수신할 일이 많은 Fleet Server, Elastic Agent에 설정해주면 좋습니다. UDP 네트워크 버퍼는 UDP 통신에 사용되는 메모리 공간이며, 이 값이 너무 낮으면 UDP 통신에서 데이터양이 많을 때 수신되는 데이터를 놓칠 수 있습니다. net.ipv4.udp_rmem_min을 설정하면, 최소 수신 버퍼를 보장해 커널이 네트워크가 혼잡할 때 UDP 수신 버퍼를 줄이는 것을 방지할 수 있습니다.

시스템 인덱스 레플리카 설정

 만약 시스템 인덱스가 담겨있는 노드가 다운되면, 노드가 다시 올라올 때 까지 인증을 못하며, 키바나 로그인도 못합니다. 시스템 인덱스의 레플리카 설정을 통해 장애가 발생해도 시스템 인덱스는 다른 노드에서 복구가 가능해집니다. 따라서 인증과 보안을 담당하는 .security-7 인덱스, 사용자 프로필과 즐겨찾기 및 테마 등을 관리하는 .security-profile 인덱스의 레플리카 샤드는 데이터 노드의 개수만큼 늘리는게 좋습니다.

PUT /_security/settings
{
    "security": {
        "index.auto_expand_replicas": "0-all"
    },
    "security-tokens": {
        "index.auto_expand_replicas": "0-all"
    },
    "security-profile": {
        "index.auto_expand_replicas": "0-all"
    }
}

 .security-tokens는 인덱스가 없는 경우도 있습니다. 버전에 따라 .security-7 인덱스로 통합된 경우가 있기 때문입니다. 그럴 때는 .security-tokens를 빼고 실행하면 되겠습니다.

• "index.auto_expand_replicas": "0-all"

 인덱스의 Replica 샤드 개수를 노드 개수에 따라 유동적으로 설정해주는 방법입니다. 0-all로 설정할 경우, 인덱스는 항상 (클러스터의 데이터노드 개수-1개) 만큼의 레플리카 샤드를 갖게 됩니다. 정확히는 data_content 역할을 하는 노드의 개수만큼 늘리면 되는데, 이를 신경쓰지 않고 자동으로 할당가능한 만큼 설정해주는 옵션입니다.

마치며

 이번 포스팅에서는 클러스터 운영, 관리함에 있어 필요한 상태 점검 API와 장애 예방 방법들을 알아보았습니다. 그리고 엘라스틱서치가 설치된 서버에 필요한 주요 시스템 설정과, 노드 장애 시 인증이 안되는 상황을 방지하는 시스템 인덱스 설정을 알아보았습니다. 앞으로도 추가적인 상태 점검 방법이 있다면 포스팅에 추가할 예정이며, 이를 통해 현재 클러스터를 점검하고 개선하는데 도움이 되었으면 합니다.