cephadm 환경에서 Alertmanager 설정 변경하고 재배포하기

cephadm으로 Ceph를 배포하면 Prometheus, Grafana, Alertmanager 같은 모니터링 스택도 cephadm이 함께 관리한다. 그래서 Alertmanager 컨테이너 안의 alertmanager.yml을 직접 수정하면 당장은 동작하는 것처럼 보여도, cephadm이 reconfig 시점에 자동 생성한 설정으로 다시 덮어써 버린다. 결론부터 말하면, 커스텀 alertmanager.yml을 ceph config-key에 등록하고 ceph orch reconfig로 재배포하는 것이 정답이다.

참고로 이번 구성에서 Discord webhook receiver를 추가한 이유는 단순히 사람이 알림을 받기 위해서가 아니다. 클라우드에서 발생하는 로그와 알림을 Hermes Agent 같은 개인 비서 에이전트 프레임워크로 넘겨, 자동 모니터링과 원인 분석을 거친 가공된 보고서를 자동으로 작성·배포하는 파이프라인을 만들기 위해서다.

이 글에서 다루는 내용

이번 글에서는 cephadm 환경에서 Alertmanager 설정을 바꿔야 할 때 어디에 설정을 넣고, 어떤 순서로 적용하면 되는지를 순서대로 정리한다. 특히 다음 두 가지를 중점으로 본다.

ceph config-key 기반의 커스텀 alertmanager.yml 등록·적용·검증·롤백 절차

Ceph Dashboard 연동 receiver + Discord webhook receiver를 함께 쓰는 실제 구성 예시

Alertmanager 알림을 에이전트 기반 자동 분석·보고 파이프라인으로 연결하는 활용 사례

1. cephadm이 Alertmanager 설정을 관리하는 방식

cephadm은 Alertmanager 데몬을 배포할 때 설정 파일을 직접 렌더링해서 컨테이너에 주입한다. 이때 mgr/cephadm/services/alertmanager/alertmanager.yml config-key가 등록되어 있으면 자동 생성 설정 대신 해당 값을 그대로 사용한다.

flowchart LR
    A["alertmanager.yml 작성"] --> B["ceph config-key set\nmgr/cephadm/services/alertmanager/alertmanager.yml"]
    B --> C["ceph orch reconfig alertmanager"]
    C --> D["cephadm이 config-key 값으로\n설정 파일 재생성"]
    D --> E["Alertmanager 데몬 재시작"]
    E --> F["Ceph Dashboard / Discord로 알림 라우팅"]

⚠️

컨테이너 내부나 /var/lib/ceph/<fsid>/alertmanager.<host>/etc/alertmanager/alertmanager.yml을 직접 수정하는 방식은 reconfig/재배포 시점에 초기화된다. 반드시 config-key 경로로 관리해야 한다.

2. 커스텀 alertmanager.yml 작성

아래는 실제로 사용 중인 구성 예시다. 핵심은 두 가지다.

ceph-dashboard receiver: Dashboard의 prometheus_receiver API로 알림을 전달한다. active mgr가 failover될 수 있으므로 mgr 후보 호스트를 모두 receiver로 등록해 둔다.

discord receiver: Discord webhook과 별도 내부 webhook(Grafana 연동)으로 알림을 전달한다.

global:
  resolve_timeout: 5m
  http_config:
    tls_config:
      insecure_skip_verify: true
    follow_redirects: true
    enable_http2: true
  smtp_hello: localhost
  smtp_require_tls: true
  pagerduty_url: https://events.pagerduty.com/v2/enqueue
  opsgenie_api_url: https://api.opsgenie.com/
  wechat_api_url: https://qyapi.weixin.qq.com/cgi-bin/
  victorops_api_url: https://alert.victorops.com/integrations/generic/20131114/alert/
  telegram_api_url: https://api.telegram.org
  webex_api_url: https://webexapis.com/v1/messages

route:
  receiver: default
  continue: false
  routes:
  - receiver: ceph-dashboard
    group_by:
    - alertname
    continue: true
    group_wait: 10s
    group_interval: 10s
    repeat_interval: 1h
  - receiver: discord
    group_by:
    - alertname
    group_wait: 30s
    group_interval: 10m
    repeat_interval: 4h

receivers:
- name: default
- name: ceph-dashboard
  webhook_configs:
  - send_resolved: true
    http_config:
      tls_config:
        insecure_skip_verify: true
      follow_redirects: true
      enable_http2: true
    url: https://dms-storage1:8443/api/prometheus_receiver
    max_alerts: 0
  - send_resolved: true
    http_config:
      tls_config:
        insecure_skip_verify: true
      follow_redirects: true
      enable_http2: true
    url: https://172.30.2.102:8443/api/prometheus_receiver
    max_alerts: 0
  - send_resolved: true
    http_config:
      tls_config:
        insecure_skip_verify: true
      follow_redirects: true
      enable_http2: true
    url: https://172.30.2.103:8443/api/prometheus_receiver
    max_alerts: 0
- name: discord
  webhook_configs:
  - send_resolved: true
    url: 'https://discord.com/api/webhooks/<WEBHOOK_ID>/<WEBHOOK_TOKEN>'  # 환경에 맞게 수정 필요
  - send_resolved: true
    http_config:
      authorization:
        type: 'Bearer'
        credentials: '<BEARER_TOKEN>'  # 환경에 맞게 수정 필요
    url: 'http://172.31.0.50:8644/webhooks/grafana'

templates: []

🔐

<WEBHOOK_ID>/<WEBHOOK_TOKEN>, <BEARER_TOKEN>은 시크릿 값이므로 환경에 맞게 교체한다. Dashboard receiver의 호스트명/IP(dms-storage1, 172.30.2.x)도 각자의 mgr 호스트 기준으로 수정이 필요하다.

3. config-key 등록 및 적용

적용 순서는 다음과 같다. 모든 명령은 admin keyring이 있는 노드(보통 bootstrap 노드)에서 root 권한으로 실행한다.

# 1) 현재 서비스 배포 상태 확인 (변경 전 상태 기록)
ceph orch ls

# 2) 커스텀 alertmanager.yml 작성/수정
vi alertmanager.yml

# 3) config-key에 파일 내용 등록
ceph config-key set mgr/cephadm/services/alertmanager/alertmanager.yml -i alertmanager.yml

# 4) 등록된 내용 확인
ceph config-key get mgr/cephadm/services/alertmanager/alertmanager.yml

# 5) Alertmanager 데몬 재구성 (설정 재생성 + 데몬 재시작)
ceph orch reconfig alertmanager

ceph orch reconfig alertmanager가 실행되면 cephadm이 config-key의 값으로 설정 파일을 다시 렌더링하고 데몬을 재시작한다.

4. 적용 검증

먼저 데몬이 정상적으로 다시 떴는지 확인한다.

# Alertmanager 데몬 상태 확인
ceph orch ps --daemon-type alertmanager

# 호스트에 실제로 배포된 설정 파일 확인
cat /var/lib/ceph/$(ceph fsid)/alertmanager.$(hostname)/etc/alertmanager/alertmanager.yml

다음으로 Alertmanager API에서 로드된 설정을 확인한다.

# Alertmanager가 실제로 로드한 설정 확인 (포트는 기본 9093)
curl -s http://<alertmanager_host>:9093/api/v2/status | jq '.config'

여기서 커스텀 receiver(discord 등)가 보이면 정상 적용된 것이고, 기본 설정만 보이면 config-key 등록이나 reconfig가 누락됐을 가능성이 높다. 마지막으로 테스트 알림(예: OSD 하나를 잠시 down)으로 Discord 채널과 Dashboard에 알림이 도착하는지 확인하면 된다.

5. 롤백

cephadm 기본 설정으로 되돌리려면 config-key를 삭제하고 다시 reconfig하면 된다.

# 커스텀 설정 제거
ceph config-key rm mgr/cephadm/services/alertmanager/alertmanager.yml

# 기본 설정으로 재생성
ceph orch reconfig alertmanager

6. 활용: 에이전트 기반 자동 모니터링·보고 파이프라인

이번 구성에서 discord receiver는 사람이 raw alert를 직접 읽는 채널이라기보다, 개인 비서 에이전트 프레임워크(Hermes Agent)의 입력 소스 역할을 한다. 전체 흐름은 다음과 같다.

flowchart LR
    A["Ceph / 클라우드 로그·이벤트"] --> B["Prometheus<br>메트릭 수집·룰 평가"]
    B --> C["Alertmanager<br>라우팅·그룹핑"]
    C --> D["Discord webhook"]
    D --> E["Hermes Agent<br>개인 비서 에이전트"]
    E --> F["자동 모니터링·원인 분석"]
    F --> G["가공된 보고서 작성"]
    G --> H["Discord 채널로 배포"]

Alertmanager는 alert를 그룹핑해 Discord webhook으로 전달한다.

Hermes Agent는 webhook으로 들어온 alert payload(상태, 심각도, 발생 시각, 요약 등)를 파싱해 원인 분석을 수행하고, 사용자가 읽기 좋은 보고서 형태로 가공한다.

가공된 보고서는 다시 Discord 채널로 배포되므로, 사용자는 raw alert 대신 정리된 보고서를 받는다.

실제로 Grafana TestAlert를 발생시켜 확인해 보면, 에이전트가 알림을 정상 수신한 뒤 보고서 톤(테스트 수신 확인 중심 / 경고성 알람 형식 / 상태만 최소 표기)까지 확인하고 보고서를 작성하는 것을 볼 수 있다. 현재 이 파이프라인은 정상 작동 중이다.

Hermes Agent가 Discord webhook으로 수신한 TestAlert를 분석해 보고서 작성 방식을 확인하는 모습

주의사항

전체 설정을 override하면 cephadm의 자동 관리도 꺼진다. 특히 Dashboard receiver URL은 cephadm이 더 이상 자동 갱신하지 않으므로, mgr 호스트가 추가/변경되면 alertmanager.yml의 receiver 목록을 직접 갱신해야 한다.

config-key에는 시크릿이 그대로 저장된다. Discord webhook URL, Bearer token 등이 mon KV store에 평문으로 들어가므로, ceph config-key get 권한 관리에 주의한다.

reconfig는 데몬 재시작을 동반한다. 재시작 동안 짧은 알림 공백이 생길 수 있으므로, 운영 환경에서는 점검 시간대에 적용하는 것이 안전하다.

YAML 문법 오류가 있으면 Alertmanager가 기동에 실패한다. 적용 전에 amtool check-config alertmanager.yml(또는 컨테이너 내 amtool)로 문법 검증을 해두면 시간을 아낄 수 있다.

핵심 정리

정리하면 다음 3가지만 기억하면 된다.

설정 파일 직접 수정은 덮어써진다 → config-key mgr/cephadm/services/alertmanager/alertmanager.yml로 관리한다.

적용은 ceph config-key set -i → ceph orch reconfig alertmanager 두 단계로 끝난다.

override 이후에는 Dashboard receiver를 포함해 설정 전체를 직접 관리해야 한다.

재발 방지 체크리스트

alertmanager.yml 원본을 Git 등 별도 저장소에 버전 관리하고 있는가?

적용 전 amtool check-config로 문법 검증을 했는가?

ceph config-key get으로 등록된 내용이 의도한 파일과 일치하는지 확인했는가?

reconfig 후 ceph orch ps --daemon-type alertmanager에서 데몬이 running 상태인가?

mgr 호스트 변경 시 ceph-dashboard receiver URL 갱신 절차가 운영 문서에 반영되어 있는가?

Discord webhook / Bearer token 등 시크릿 교체 시 config-key 재등록 절차를 알고 있는가?

참고 자료

Ceph 공식 문서 — Monitoring Services (cephadm)

Prometheus Alertmanager — Configuration

Alertmanager webhook receiver 설정