OpenSearch 운영·관리·인덱스 설계 실전 가이드 2026

┌─────────────────────────────────────────────────────────────────┐
│                      클라이언트 / Data Prepper                    │
│                        (Ingest Pipeline)                        │
└──────────────────────────┬──────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌──────────┐     ┌──────────┐     ┌──────────┐
   │ Master-1 │     │ Master-2 │     │ Master-3 │
   │ (AZ-a)   │     │ (AZ-b)   │     │ (AZ-c)   │
   │ 전용 마스터│     │ 전용 마스터│     │ 전용 마스터│
   └──────────┘     └──────────┘     └──────────┘
          │                │                │
          ▼                ▼                ▼
   ┌──────────┐     ┌──────────┐     ┌──────────┐
   │ Hot-1    │     │ Hot-2    │     │ Hot-3    │
   │ (AZ-a)   │     │ (AZ-b)   │     │ (AZ-c)   │
   │ EBS gp3  │     │ EBS gp3  │     │ EBS gp3  │
   └──────────┘     └──────────┘     └──────────┘
          │                │                │
          ▼                ▼                ▼
   ┌──────────┐     ┌──────────┐     ┌──────────┐
   │ Warm-1   │     │ Warm-2   │     │ Warm-3   │
   │ UltraWarm│     │ UltraWarm│     │ UltraWarm│
   │ (S3+캐시) │     │ (S3+캐시) │     │ (S3+캐시) │
   └──────────┘     └──────────┘     └──────────┘

필요 스토리지 = 일일 원본 데이터
              × (1 + 레플리카 수)
              × 1.1 (인덱싱 오버헤드)
              × 1.15 (OS 예약 + 내부 작업 여유)
              × 보존 기간(일)

실제 프로비저닝 = 필요 스토리지 / 0.75 = 10,120 GiB

프라이머리 샤드 수 ≈ (원본 데이터 크기 + 성장 여유) × 1.1 / 목표 샤드 크기

(66 + 198) × 1.1 / 30 ≈ 10 프라이머리 샤드

PUT _index_template/app-logs-template
{
  "index_patterns": ["app-logs-*"],
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1,
      "refresh_interval": "30s",
      "index.translog.flush_threshold_size": "1024mb",
      "index.codec": "zstd_no_dict",
      "plugins.index_state_management.rollover_alias": "app-logs-write"
    },
    "mappings": {
      "dynamic": "strict",
      "properties": {
        "@timestamp":  { "type": "date" },
        "level":       { "type": "keyword" },
        "message":     { "type": "text", "analyzer": "standard" },
        "service":     { "type": "keyword" },
        "trace_id":    { "type": "keyword" },
        "span_id":     { "type": "keyword" },
        "host":        { "type": "keyword" },
        "duration_ms": { "type": "float" },
        "http_status": { "type": "short" },
        "request_path":{ "type": "keyword" },
        "user_id":     { "type": "keyword" },
        "metadata":    {
          "type": "object",
          "enabled": false
        }
      }
    }
  },
  "composed_of": ["common-settings"],
  "priority": 200
}

// 인덱싱 전: 레플리카 비활성화
PUT my-bulk-index/_settings
{ "index.number_of_replicas": 0 }

// 인덱싱 완료 후: 레플리카 복원
PUT my-bulk-index/_settings
{ "index.number_of_replicas": 1 }

PUT _plugins/_ism/policies/app-log-lifecycle
{
  "policy": {
    "description": "앱 로그 인덱스 라이프사이클: hot → warm → cold → delete",
    "default_state": "hot",
    "states": [
      {
        "name": "hot",
        "actions": [
          {
            "rollover": {
              "min_size": "30gb",
              "min_index_age": "1d",
              "min_doc_count": 10000000
            }
          }
        ],
        "transitions": [
          { "state_name": "warm", "conditions": { "min_index_age": "3d" } }
        ]
      },
      {
        "name": "warm",
        "actions": [
          { "replica_count": { "number_of_replicas": 1 } },
          { "force_merge": { "max_num_segments": 1 } },
          { "allocation": {
              "require": { "temp": "warm" },
              "wait_for": true
            }
          }
        ],
        "transitions": [
          { "state_name": "cold", "conditions": { "min_index_age": "30d" } }
        ]
      },
      {
        "name": "cold",
        "actions": [
          { "replica_count": { "number_of_replicas": 0 } },
          { "read_only": {} }
        ],
        "transitions": [
          { "state_name": "delete", "conditions": { "min_index_age": "90d" } }
        ]
      },
      {
        "name": "delete",
        "actions": [
          {
            "notification": {
              "destination": {
                "slack": { "url": "https://hooks.slack.com/services/T.../B.../xxx" }
              },
              "message_template": {
                "source": "인덱스 {{ctx.index}}가 보존 정책(90일)에 따라 삭제됩니다."
              }
            }
          },
          { "delete": {} }
        ],
        "transitions": []
      }
    ],
    "ism_template": [
      { "index_patterns": ["app-logs-*"], "priority": 100 }
    ]
  }
}

# 정책 실행 상태 확인 (특정 인덱스)
GET _plugins/_ism/explain/app-logs-000001

# 기존 인덱스에 정책 부착
POST _plugins/_ism/add/old-logs-2025-*
{ "policy_id": "app-log-lifecycle" }

# 정책 버전 업데이트 (관리 중인 인덱스에 새 정책 적용)
POST _plugins/_ism/change_policy/app-logs-*
{
  "policy_id": "app-log-lifecycle-v2",
  "state": "warm"
}

# 실패한 ISM 작업 재시도
POST _plugins/_ism/retry/app-logs-000003

# 특정 인덱스에서 ISM 정책 제거
POST _plugins/_ism/remove/app-logs-000005

// 1단계: 초기 인덱스 생성 + alias 설정
PUT app-logs-000001
{
  "aliases": {
    "app-logs-write": { "is_write_index": true },
    "app-logs-read": {}
  }
}

// 2단계: ISM 정책의 rollover 액션이 자동으로 처리
//   → app-logs-000002 생성
//   → app-logs-write alias를 000002로 이동
//   → 000001의 is_write_index를 false로 변경

// 읽기는 항상 read alias로 (모든 히스토리 대상)
GET app-logs-read/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "level": "ERROR" } },
        { "range": { "@timestamp": { "gte": "now-1h" } } }
      ]
    }
  },
  "sort": [{ "@timestamp": "desc" }],
  "size": 100
}

// 쓰기는 항상 write alias로
POST app-logs-write/_doc
{
  "@timestamp": "2026-03-04T10:00:00Z",
  "level": "ERROR",
  "service": "payment-api",
  "message": "결제 게이트웨이 타임아웃 발생",
  "trace_id": "abc123",
  "duration_ms": 30500,
  "http_status": 504
}

# 현재 write index 확인
GET _alias/app-logs-write

# 전체 alias 구조 확인
GET _cat/aliases/app-logs-*?v&h=alias,index,is_write_index

# 클러스터 전체 상태 (green/yellow/red)
GET _cluster/health

# 인덱스별 상태 확인
GET _cluster/health?level=indices

# 노드별 JVM, CPU, 디스크 상세
GET _nodes/stats/jvm,os,fs

# 핫 스레드 확인 (높은 CPU 원인 분석)
GET _nodes/hot_threads

# 스레드풀 상태 (대기, 거절 수 확인)
GET _cat/thread_pool?v&h=node_name,name,active,queue,rejected

# 샤드 배치 현황
GET _cat/shards?v&h=index,shard,prirep,state,docs,store,node&s=state

# 미할당 샤드 원인 분석
GET _cluster/allocation/explain
{
  "index": "app-logs-000003",
  "shard": 0,
  "primary": true
}

# 인덱스별 크기 및 문서 수
GET _cat/indices?v&h=index,health,pri,rep,docs.count,store.size&s=store.size:desc

# 노드별 디스크 사용량
GET _cat/allocation?v&h=node,shards,disk.used,disk.avail,disk.percent

# 대기 중인 태스크 확인
GET _cat/pending_tasks?v

PUT app-logs-*/_settings
{
  "index.search.slowlog.threshold.query.warn": "10s",
  "index.search.slowlog.threshold.query.info": "5s",
  "index.search.slowlog.threshold.fetch.warn": "5s",
  "index.indexing.slowlog.threshold.index.warn": "10s",
  "index.indexing.slowlog.threshold.index.info": "5s"
}

POST _plugins/_alerting/monitors
{
  "type": "monitor",
  "name": "Cluster Red Status Alert",
  "monitor_type": "query_level_monitor",
  "enabled": true,
  "schedule": {
    "period": { "interval": 1, "unit": "MINUTES" }
  },
  "inputs": [
    {
      "search": {
        "indices": [".opensearch-sap-log-types-config"],
        "query": {
          "size": 0,
          "query": {
            "match_all": {}
          }
        }
      }
    }
  ],
  "triggers": [
    {
      "query_level_trigger": {
        "name": "Cluster Status Red",
        "severity": "1",
        "condition": {
          "script": {
            "source": "ctx.results[0].hits.total.value >= 0",
            "lang": "painless"
          }
        },
        "actions": [
          {
            "name": "Notify Slack",
            "destination_id": "slack-destination-id",
            "message_template": {
              "source": "클러스터 상태가 RED입니다.\n클러스터: {{ctx.monitor.name}}\n시각: {{ctx.periodEnd}}\n즉시 확인이 필요합니다."
            },
            "throttle_enabled": true,
            "throttle": { "value": 10, "unit": "MINUTES" }
          }
        ]
      }
    }
  ]
}

# 1. 가장 큰 인덱스 확인
GET _cat/indices?v&h=index,store.size&s=store.size:desc&format=json

# 2. 오래된 불필요 인덱스 삭제
DELETE old-logs-2024-*

# 3. read-only 차단 해제 (모든 인덱스)
PUT _all/_settings
{
  "index.blocks.read_only_allow_delete": null
}

# 4. 클러스터 레벨 차단 해제
PUT _cluster/settings
{
  "persistent": {
    "cluster.blocks.read_only": false
  }
}

# 5. 클러스터 상태 확인
GET _cluster/health

// S3 리포지토리 등록
PUT _snapshot/s3-backup
{
  "type": "s3",
  "settings": {
    "bucket": "my-opensearch-snapshots",
    "base_path": "daily",
    "region": "ap-northeast-2",
    "server_side_encryption": true,
    "role_arn": "arn:aws:iam::123456789012:role/OpenSearchSnapshotRole"
  }
}

// 수동 스냅샷 생성
PUT _snapshot/s3-backup/snapshot-2026-03-04
{
  "indices": "app-logs-*",
  "ignore_unavailable": true,
  "include_global_state": false
}

// 스냅샷 상태 확인
GET _snapshot/s3-backup/snapshot-2026-03-04/_status

// 특정 인덱스만 복원 (이름 변경하여 기존 인덱스와 충돌 방지)
POST _snapshot/s3-backup/snapshot-2026-03-04/_restore
{
  "indices": "app-logs-000001,app-logs-000002",
  "ignore_unavailable": true,
  "include_global_state": false,
  "rename_pattern": "(.+)",
  "rename_replacement": "$1_restored",
  "index_settings": {
    "index.number_of_replicas": 0
  }
}

// 복원 완료 후 레플리카 복원
PUT app-logs-000001_restored/_settings
{ "index.number_of_replicas": 1 }

POST _reindex
{
  "source": {
    "remote": {
      "host": "https://old-es-cluster:9200",
      "username": "admin",
      "password": "********",
      "socket_timeout": "60m",
      "connect_timeout": "30s"
    },
    "index": "app-logs-2025-*",
    "size": 5000,
    "query": {
      "range": {
        "@timestamp": {
          "gte": "2025-01-01",
          "lt": "2026-01-01"
        }
      }
    }
  },
  "dest": {
    "index": "app-logs-migrated"
  },
  "conflicts": "proceed"
}

from opensearchpy import OpenSearch, helpers

client = OpenSearch(
    hosts=[{"host": "opensearch-node", "port": 9200}],
    http_auth=("admin", "admin"),
    use_ssl=True,
    verify_certs=False,
)

def generate_actions(file_path):
    """로그 파일을 읽어 _bulk 액션으로 변환"""
    import json
    with open(file_path) as f:
        for line in f:
            doc = json.loads(line)
            yield {
                "_index": "app-logs-write",
                "_source": doc,
            }

success, errors = helpers.bulk(
    client,
    generate_actions("/var/log/app/events.jsonl"),
    chunk_size=5000,
    max_retries=3,
    request_timeout=60,
)
print(f"Indexed: {success}, Errors: {len(errors)}")