---
title: "cephadm 환경에서 Alertmanager 설정 변경하고 재배포하기"
description: "cephadm 환경에서 Alertmanager 설정을 수정하려면 커스텀 alertmanager.yml을 ceph config-key에 등록하고 ceph orch reconfig alertmanager로 재배포해야 하며, 이를 통해 Discord와 Ceph Dashboard 등 다양한 수신자를 연동하고 설정을 관리·검증·롤백할 수 있다."
date: "2026-07-06T00:00:00.000Z"
last_modified: "2026-09-21T23:26:00.000Z"
type: "Post"
tags:
  - "ceph"
  - "Monitoring"
  - "troubleshooting"
categories:
  - "🤖 Computer Science"
series:
  - "ceph"
authors:
  - "봉정근"
canonical_url: "https://pieroot.xyz/cephadm-alertmanager"
markdown_url: "https://pieroot.xyz/cephadm-alertmanager.md"
---

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

cephadm 환경에서 Alertmanager 설정을 수정하려면 커스텀 alertmanager.yml을 ceph config-key에 등록하고 ceph orch reconfig alertmanager로 재배포해야 하며, 이를 통해 Discord와 Ceph Dashboard 등 다양한 수신자를 연동하고 설정을 관리·검증·롤백할 수 있다.

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가 등록되어 있으면 **자동 생성 설정 대신 해당 값을 그대로 사용**한다.

```mermaid
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 연동)으로 알림을 전달한다.

```yaml
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 권한**으로 실행한다.

```bash
# 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. 적용 검증

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

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

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

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

```bash
# 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하면 된다.

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

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

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

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

```mermaid
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를 분석해 보고서 작성 방식을 확인하는 모습](https://pieroot.xyz/api/image-proxy?id=cee9f730-f779-42fe-ba7e-222c0d256b46&kind=s3&pageId=38330efb-55a5-420a-b743-644a14788537&source=block&blockId=5afbf848-a6d1-4cd1-9322-ff9ce6fce96a)

## 주의사항

- **전체 설정을 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)](https://docs.ceph.com/en/latest/cephadm/services/monitoring/)

- [Prometheus Alertmanager — Configuration](https://prometheus.io/docs/alerting/latest/configuration/)

- [Alertmanager webhook receiver 설정](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config)