ElasticSearch Cluester API & Index API - 클러스터 설정과 인덱스 설정 변경하기

클러스터 API

설정 변경

ElasticSearch 클러스터의 설정은 클러스터 API인 `/_cluster/settings`로 변경할 수 있습니다.

클러스터 API는 클러스터 전체에 설정을 적용할 때 사용하는데, 아래 예시처럼 `persistent`, `transient` 필드를 포함해 JSON 포맷으로 요청을 보냅니다. (두 필드 중 하나만 입력할 수 있습니다.)

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.node_concurrent_recoveries": 4 # 동시에 복구할 노드 수
  },
  "transient": {
    "cluster.routing.allocation.enable": "new_primaries"  # 클러스터 내 샤드 기능 활성화
  }
}

설정 확인

GET /_cluster/settings
{
  "persistent": { }.
  "transient": { }
}

설정 조회 시 2가지 필드를 응답으로 받습니다.

persistent
- 영구적으로 저장되는 설정 항목들입니다. 클러스터가 재시작돼도 해당 설정값이 유지됩니다.
- 아무 값이 없다면 기본 값이 적용 중입니다.
- 사용 예시: 자주 변경되지 않는 설정을 할 때 사용합니다.
transient
- 클러스터의 런타임 환경에서만 적용되는 설정 항목들입니다. 클러스터가 재시작되면 값이 초기화됩니다.
- 아무 값이 없다면 기본 값이 적용 중입니다.
- 사용 예시: 자주 변경되는 설정을 할 때 사용합니다.

설정 값 적용 우선순위

두 가지 외에도 `elasticsearch.yml` 파일로 적용되는 설정 값도 있습니다. 참고로 노드 관련 설정은 클러스터 API로 설정할 수 없고 `elasticsearch.yml` 파일로만 설정할 수 있습니다.

만약 `elasticsearch.yml`, `persistent`, `transient` 각각에 동일한 설정이 있다면 ElasticSearch는 다음 우선순위에 따라 설정을 적용합니다.

1순위: `transient` 설정
2순위: `persistent` 설정
3순위: `elasticsearch.yml` 파일의 설정

explain 기능

클러스터 API 중 explain 기능은 `/_cluster/allocation/explain` API를 통해 어떤 문제가 발생했을 때 문제의 원인을 확인하는 기능을 제공합니다. 예를 들어, unassigned 샤드가 발생했을 때 발생한 원인을 `unassigned_info` 필드에 상세하게 알려줍니다.

GET /_cluster/alloation/explain

{
  "index": "user",
  "shard": 3,
  ...
  "unassigned_info": {
    "reason": "NODE_LEFT",
    "at": "2025-01-01T00:00:000Z",
    "details": "node_left [제외된 노드]"
  },
  ...
}

인덱스 API

사용 방법

인덱스 API를 통해 인덱스 관련 설정을 동적으로 변경할 수 있습니다.

특정 인덱스에 설정을 적용할 때는 `/{인덱스_이름}/settings` 패턴을 사용하고, 전체 인덱스에 설정을 적용할 때는 `/_all/settings` 패턴을 사용합니다.

와일드카드(`*`) 표현식을 지원하기 때문에 특정 인덱스들에 일괄적으로 설정 적용이 필요할 때 다음과 같이 설정할 수도 있습니다.

예를 들어, 12월 로그에만 설정을 적용할 때 `log-2024-12*` 같이 와일드카드를 이용해 `log-2024-12`로 시작하는 모든 인덱스에 설정을 적용할 수 있습니다.

다양한 인덱스 API

인덱스에 적용할 수 있는 다양한 인덱스 API가 있는데, 자주 사용되는 API로 `open/close`, `aliases`, `rollover`, `refresh`, `forcemerge`, `reindex`가 있습니다.

open/close API

인덱스를 사용할 때는 `open`, 사용하지 않을 때는 `close`를 사용해 인덱스의 상태를 변경할 수 있습니다.

OPEN → CLOSE: `POST /{인덱스_이름}/close`
- 함께 보내는 JSON

POST /myIndex/close
{
  "acknowledged": true
}

CLOSE → OPEN: `POST /{인덱스_이름}/open`
- 함께 보내는 JSON

POST /myIndex/open
{
  "acknowledged": true,
  "shards_acknowledged": true
}

aliases API

인덱스에 별칭을 설정할 때 사용합니다. `/_aliases`에 JSON으로 설정값을 전달합니다. 인덱스 이름에 와일드카드(`*`)를 사용해 여러 인덱스에 걸쳐 하나의 별칭으로 지정할 수도 있습니다.

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test*",  # test로 시작하는 인덱스에 `myIndex`라는 별칭을 지정
        "alias": "myIndex"
      }
    }
  ]
}

또한, 하나의 alias는 여러 인덱스에서 사용할 수 있습니다.

비슷한 성격의 인덱스를 그룹으로 관리해야 할 때 alias를 지정하면 해당 그룹에 일괄적으로 설정을 적용할 수 있게 됩니다.

주의할 점

단일 인덱스에 별칭 하나를 사용하면 인덱싱과 검색 모두 가능합니다.

하지만 위의 이미지처럼 하나의 alias를 여러 인덱스에 지정하면 검색은 가능하지만 어느 인덱스에 인덱싱을 해야 할지 판단할 수 없기 때문에 인덱싱은 불가능합니다.

이 점을 이용해 읽기 전용(read only) 인덱스들을 설정할 수도 있습니다.

인덱스들을 read_only 별칭으로 관리할 때 주의할 점이 또 있는데요, 위의 이미지에서 3개의 인덱스 중 하나라도 `close` 상태라면 해당 별칭을 통한 검색조차 안되기 때문에 인지하고 사용해야 합니다.

rollover API

rollover API는 인덱스의 대량의 데이터가 지속적으로 인덱싱 되는 환경에서 효율적으로 인덱스를 관리할 때 사용할 수 있습니다.

위의 `alias`와 함께 사용한다면 하나의 별칭으로 대용량의 인덱스를 쉽게 관리할 수 있습니다.

PUT `/logs-000001`
{
  "aliases": {
    "logs-write": {},
    "logs-read": {}
  }
}

POST `/logs-write/_rollover`
{
  "conditions": {
    "max_size": "50gb",
    "max_age": "30d"
  }
}

위와 같이 설정하면 대량의 쓰기 작업이 계속되면서 롤오버가 지속적으로 발생하지만, 클라이언트는 롤오버가 됐는지와 상관없이 일관적으로 `log_read` alias를 통해 접근할 수 있습니다.

롤오버 조건으로 사용할 수 있는 3가지

max_age: 생성된 날짜부터 설정한 값이 지나면 롤오버
max_docs: document 개수가 설정한 값이 됐을 때 롤오버
max_size: 인덱스의 저장 용량이 설정한 값이 됐을 때 롤오버

사용 방법

`/{인덱스_이름}/_rollover` 경로에 조건을 JSON 포맷으로 전달해 적용합니다.

롤오버 될 인덱스의 이름을 지정할 때는 `/{인덱스_이름}/_rollover/{생성될_인덱스_이름}`을 사용합니다.

POST `/myIndex/_rollover`
{
  "conditions": {
    "max_age": "7d",   # 7일이 지나면 롤오버
    "max_docs": 2,     # document 2개가 되면 롤오버
    "max_size": "5gb"  # 인덱스 용량이 5gb가 되면 롤오버
  }
}

refresh API

인덱스에 refresh를 트리거하는 API입니다. 사용 시 메모리 버퍼 캐시에 있는 문서(document)들을 세그먼트(segment)로 저장하고, 다시 메모리에 올려 즉시 검색할 수 있도록 합니다.

POST /myIndex/_refresh
{
  "_shards": {
    "total": 10,
    "successful": 10,
    "failed": 0
  }
}

forcemerge API

세그먼트 병합 - https://dev-gallery.tistory.com/62

인덱스의 샤드를 구성하는 세그먼트를 강제로 병합할 때 사용합니다. 세그먼트를 병합하면 디스크 용량이 줄어들고, 검색 성능을 높일 수 있습니다.

POST /myIndex/_forcemerge?max_num_segments=10
{
  "_shards": {
    "total": 10,
    "successful: 10,
    "failed": 0
  }
}

파라미터로 넘긴 `max_num_segments`의 값은 병합 후 남겨둘 세그먼트의 최대 수를 지정할 때 사용하며, `only_expunge_deletes=true`를 넘기면 삭제된 문서가 있는 세그먼트만 대상으로 병합합니다.

주의사항

강제 병합은 해당 인덱스에 존재하는 모든 샤드를 대상으로 일어납니다.

따라서 샤드 수가 많을수록 막대한 디스크 I/O 작업을 일으키기 때문에 사용량이 적은 시간대에 사용하는 것이 좋습니다.

그리고 인덱싱이 지속적으로 일어나는 인덱스는 자동으로 병합이 일어나기 때문에, 더 이상 인덱싱이 잘 일어나지 않는 과거의 인덱스에 적용하는 것이 좋습니다.

reindex API

인덱스를 복제할 때 사용하는 API입니다.

POST /_reindex
{
  "source": {
    "index": "myIndex1"
  },
  "dest": {
    "index": "myIndex2"
  }
}

인덱스에 적용된 analyzer를 변경하거나 클러스터 수준의 마이그레이션을 할 때 사용할 수 있습니다.

참고

기초부터 다지는 ElasticSearch 운영 노하우

'ElasticSearch' 카테고리의 다른 글

루씬(Lucene) 검색 엔진의 구조 (FST, Burst Trie, 역 인덱스) (0)	2025.01.12
ElasticSearch 역 인덱스(Inverted Index) (0)	2025.01.10
ElasticSearch 샤드 배치 방식 변경하기 (0)	2025.01.03
ElasticSearch 클러스터 설정 톺아보기 (0)	2024.12.30
ElasticSearch 기본 개념 (0)	2024.12.29

클러스터 API

설정 변경

설정 확인

설정 값 적용 우선순위

explain 기능

인덱스 API

open/close API

aliases API

rollover API

refresh API

forcemerge API

reindex API

참고

'ElasticSearch' 카테고리의 다른 글

티스토리툴바