Elasticsearch & Kibana 설치 가이드

1. 개요

본 문서는 gitops 저장소의 /eck/ek 디렉터리 구조를 기반으로 Elasticsearch와 Kibana를 Kubernetes 클러스터에 설치하는 전체 과정을 안내합니다. ECK (Elastic Cloud on Kubernetes)를 사용하여 Elasticsearch 클러스터와 Kibana를 배포하며, Kustomize를 활용한 배포 자동화, 환경별 설정, 주요 커스텀 옵션, 운영 팁을 포함합니다.

2. 사전 요구사항

  • Kubernetes 클러스터: v1.24 이상
  • 로컬 도구: kubectl, kustomize 설치 완료
  • ECK Operator: ECK Operator가 클러스터에 설치되어 있어야 함 (/eck/operator 참조)
  • 스토리지: PersistentVolume 지원 (Elasticsearch 데이터 저장용)
  • DNS 등록
    • elasticsearch.cnapcloud.com
    • kibana.cnapcloud.com

3. 디렉터리 구조 및 역할

eck/ek/
├── Makefile                           # 배포 자동화 스크립트
├── kustomize/
│   ├── base/                          # 공통 리소스
│   │   ├── kustomization.yaml         # 기본 Kustomize 구성
│   │   └── resources/                 # Elasticsearch, Kibana, Ingress 리소스
│   └── overlays/
│       └── dev/                       # dev 환경 설정
│           └── kustomization.yaml     # 환경별 Kustomize 구성

4. Elasticsearch 클러스터 설정

4.1. 클러스터 노드 역할 설정

Elasticsearch 클러스터의 각 노드는 특정 역할을 수행하도록 구성됩니다. /eck/ek/kustomize/base/resources/elasticsearch.yaml 파일의 nodeSets[].config에서 노드 역할을 설정합니다.

역할 설명:

  • node.master: true: 클러스터 상태 관리, 인덱스 생성/삭제 등 마스터 노드 역할
  • node.data: true: 데이터 저장 및 검색 처리
  • node.ingest: true: 데이터 인덱싱 전 전처리 (파이프라인 실행)
  • node.ml: false: 머신러닝 기능 (현재 비활성화)

설정 예시:

nodeSets:
- name: default
  count: 3
  config:
    node.master: true
    node.data: true
    node.ingest: true
    node.ml: false

이 구성은 3개의 노드가 모든 역할을 수행하는 통합 설정으로, 소규모 클러스터에 적합합니다. 대규모 배포 시 역할별 노드 분리를 고려할 수 있습니다.

4.2. 전용 노드 구성

Elasticsearch는 메모리와 CPU를 많이 사용하는 워크로드이므로, 다른 애플리케이션과 리소스 경쟁을 피하기 위해 전용 노드에 배포하는 것이 좋습니다. 또한, Kubernetes 클러스터에서 노드를 자동으로 drain하거나 유지보수할 때 Elasticsearch 파드가 다른 노드로 이동하면서 데이터 일관성 문제가 발생할 수 있으므로, 전용 노드를 통해 이를 방지합니다.

Elasticsearch 파드를 전용 노드에 배포하기 위해 노드 어피니티(nodeAffinity)를 설정합니다. /eck/ek/kustomize/base/resources/elasticsearch.yaml 파일에서 preferredDuringSchedulingIgnoredDuringExecution을 통해 workload: elasticsearch 라벨이 있는 노드를 선호하도록 구성됩니다.

설정 예시:

affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      preference:
        matchExpressions:
        - key: workload
          operator: In
          values:
          - elasticsearch

이 설정은 설치 단계에서 자동으로 적용되며, 전용 노드가 준비되어 있지 않은 경우 일반 노드에 배포될 수 있습니다.

5. 설치 단계

5.1. Namespace 생성

make namespace DEPLOY_ENV=dev

5.2. 배포 미리보기

make preview DEPLOY_ENV=dev

5.3. 배포 실행

make apply DEPLOY_ENV=dev

5.4. 배포 상태 확인

kubectl get pods -n database -w

6. 설치 후 검증

6.1. 리소스 상태 확인

kubectl get elasticsearch,kibana,ingress -n database

확인 사항:

  • Elasticsearch 클러스터: eck-ek (Green 상태)
  • Kibana: eck-ek-kibana (Green 상태)
  • Ingress 생성 확인 (elasticsearch.cnapcloud.com, kibana.cnapcloud.com)

6.2. Elasticsearch 접근 확인

Elasticsearch에 접근 가능한지 확인합니다.

kubectl -n database exec -it elasticsearch-es-default-0 -- bash
curl -u elastic:<password>  http://elasticsearch-es-default:9200/_cluster/health?pretty

확인 사항:

  • status: “green”
  • 클러스터 건강 상태 양호

6.3. Kibana 접근 확인

Kibana에 접근 가능한지 확인합니다.

curl -k https://kibana.cnapcloud.com

확인 사항:

  • Kibana UI 로드 확인
  • Elasticsearch 연결 상태 확인

6.4. 데이터 수집 테스트

Elasticsearch에 테스트용 인덱스를 생성하고 샘플 데이터를 인덱싱합니다.

인덱스 생성:

curl -u elastic:password -k -X PUT "http://elasticsearch-es-default:9200/test-index" \
  -H 'Content-Type: application/json' \
  -d '{
        "settings": {
          "number_of_shards": 1,
          "number_of_replicas": 0
        },
        "mappings": {
          "properties": {
            "message": { "type": "text" },
            "timestamp": { "type": "date" }
          }
        }
      }'

데이터 인덱싱:

TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%S%z)
curl -u elastic:<password> -k -X POST "http://elasticsearch-es-default:9200/test-index/_doc" \
  -H 'Content-Type: application/json' \
  -d "{\"message\": \"ECK test data\", \"timestamp\": \"$TIMESTAMP\"}"

확인 사항:

  • 인덱스 생성 성공
  • 데이터 인덱싱 성공
  • Kibana에서 데이터 확인 가능

7. 운영 및 Troubleshooting

7.1. 일반적인 Pod 문제

kubectl get pods -n database
kubectl describe pod <pod명> -n database
kubectl logs <pod명> -n database

주요 원인:

  • 스토리지 부족 → PVC 상태 확인
  • 리소스 부족 → 노드 리소스 확인
  • 네트워크 문제 → Service/Ingress 확인

7.2. Elasticsearch 클러스터 문제

kubectl get elasticsearch -n database
kubectl describe elasticsearch eck-ek -n database

클러스터 상태 확인:

kubectl -n database exec -it elasticsearch-es-default-0 -- bash
curl -u elastic:<password> http://elasticsearch-es-default:9200/_cluster/health?pretty

할당 문제 진단:

curl -u elastic:<password> -X GET "http://elasticsearch-es-default:9200/_cluster/allocation/explain?pretty"

주요 원인:

  • 디스크 공간 부족 (disk_threshold)
  • 노드 수 부족
  • 할당 정책 위반

7.3. Kibana 연결 문제

kubectl get kibana -n database
kubectl describe kibana eck-ek-kibana -n database
kubectl logs deployment/eck-ek-kibana -n database

Elasticsearch 연결 확인:

kubectl get svc -n database

주요 원인:

  • Elasticsearch 서비스 연결 실패
  • 인증 정보 불일치
  • 네트워크 정책 차단

7.4. 성능 모니터링

ECK 메트릭을 Prometheus로 수집하도록 설정합니다.

8. 보안 및 운영 권장사항

8.1. TLS 설정

Elasticsearch와 Kibana에 TLS를 적용하여 보안을 강화합니다.

8.2. 인증 설정

Elasticsearch의 보안 기능을 활성화하여 사용자 인증을 설정합니다.

8.3. 백업 설정

Elasticsearch 데이터를 정기적으로 백업합니다.

9. 배포 제거

9.1. ECK EK 삭제

make delete DEPLOY_ENV=dev-arm64

9.2. Namespace 삭제 (선택사항)

kubectl delete namespace database

주의: Namespace를 삭제하면 PVC를 포함한 모든 데이터가 영구 삭제됩니다.

10. 부록: 최종 체크리스트

설치 전:

  • Kubernetes 클러스터 준비 (v1.24+)
  • kubectl, kustomize 설치
  • ECK Operator 설치 완료
  • 스토리지 클래스 준비
  • 네임스페이스(database) 생성
  • DNS 등록 완료

설치:

  • make namespace 실행
  • make preview 실행 및 확인
  • make apply 실행

검증:

  • Elasticsearch 클러스터 Green 상태
  • Kibana Green 상태
  • Ingress 생성 확인
  • Elasticsearch 접근 확인
  • Kibana 접근 확인
  • 데이터 수집 테스트

운영:

  • TLS 설정 적용
  • 인증 설정 적용
  • 백업 설정 적용
  • 모니터링 설정 /home/ubuntu/devel/github/gitops/eck/ek/install_guide.md
💬 무료 컨설팅 신청