# 쿠버네티스 알림을 휴대폰에서 받아보세요.

> Kubernetes 알림을 휴대폰으로 받아보세요. Alertmanager webhook_config를 Pocket Alert로 연결하면 CrashLoopBackOff나 OOMKilled가 1초 이내에 푸시 알림으로 도착해요.

<!-- source: https://pocketalert.app/ko/use-cases/kubernetes-alerts -->

마지막 업데이트: 2026-08-11

CrashLoopBackOff 파드, OOMKilled 컨테이너, 실패한 롤아웃, NotReady 노드가 휴대폰 푸시로 바뀌어, 네임스페이스와 파드 이름이 화면에 바로 보입니다. kubectl에 매달리지 않고도 클러스터 문제를 놓치지 마세요.

## Alertmanager에서 휴대폰까지 세 단계

1. **수신 URL 받기** — GJSON 메시지 템플릿이 있는 Pocket Alert 웹훅을 만들고 수신 URL을 복사하세요.
2. **Alertmanager 연결하기** — Alertmanager에 webhook_configs 리시버를 추가하고 중요 알림을 여기로 라우팅하세요.
3. **배포하기** — 다음에 발생하는 알림이 1초 안에 휴대폰으로 푸시됩니다. 라우트를 다듬으면서 GJSON 템플릿도 조정하세요.

## 발생한 알림부터 휴대폰까지

지금 운영 중인 Alertmanager를 그대로 쓰세요. Pocket Alert가 웹훅 출력을 휴대폰 푸시로 바꿔 드립니다.

- **기본 webhook_config 지원** — Alertmanager에는 기본 webhook_config 리시버가 있습니다. 애플리케이션 URL만 지정하면 설정이 끝납니다.
- **GJSON 필드 매핑** — GJSON이 JSON에서 alertname, namespace, pod, severity를 추출해 읽기 쉬운 제목과 메시지로 만듭니다.
- **상태와 심각도 인라인 표시** — status와 severity를 메시지 안에 표시해서 발생한 critical 알림과 해결 알림을 한눈에 구분할 수 있습니다.
- **파드 및 노드 이벤트** — CrashLoopBackOff, OOMKilled, 실패한 롤아웃, NotReady 노드, PVC 용량 초과 이벤트를 잡아냅니다.
- **클러스터별 채널** — 애플리케이션을 나누면 prod와 staging이 각자의 웹훅 URL을 가진 별도 채널을 사용합니다.
- **1초 미만 전달** — Alertmanager가 알림을 발생시키면 1초 안에 푸시가 도착합니다. 클러스터 안에 별도 에이전트가 필요 없습니다.

## 쿠버네티스 알림을 휴대폰으로 받기

### 1. Pocket Alert 웹훅 만들기

[웹훅](https://pocketalert.app/ko/webhooks) 페이지에서 웹훅을 만드세요. GJSON `message` 템플릿으로 Alertmanager 페이로드(최상위 `status`와 `commonLabels`, 그리고 `alerts` 배열)를 읽도록 설정합니다:

```
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
  -H "Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"K8s Alertmanager","message":"[%status%] %commonLabels.alertname% (%commonLabels.severity%)\n%alerts.0.labels.namespace%/%alerts.0.labels.pod%\n%alerts.0.annotations.summary%","application_id":"qm47b9pzxzxg"}'
```

`https://p4a.me/wh/1234abcd` 같은 수신 URL이 발급됩니다. prod와 staging을 분리하려면 클러스터마다 웹훅을 하나씩 사용하세요.

### 2. Alertmanager에서 웹훅 연결하기

`webhook_configs` 리시버를 추가하고 중요 알림을 이 리시버로 라우팅하세요([Alertmanager 문서](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config)):

```
receivers:
  - name: 'pocketalert'
    webhook_configs:
      - url: 'https://p4a.me/wh/1234abcd'

route:
  receiver: 'pocketalert'
  group_by: ['alertname', 'namespace']
```

Alertmanager는 표준 JSON을 POST로 보내며, 위의 GJSON 경로가 status, alertname, severity, namespace, pod을 푸시 메시지로 가져옵니다. 알림이 해제되면 `status`가 `resolved`로 바뀝니다.

### 3. 컨트롤러나 kubectl에서 POST 보내기

컨트롤러나 일회성 스크립트에서 Token 헤더와 함께 메시지 API를 직접 호출할 수 있습니다:

```
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"CrashLoopBackOff","level":"critical","message":"api-7c9 in prod, 12 restarts","application_id":"qm47b9pzxzxg"}'
```

모든 GJSON 경로와 웹훅 옵션은 [웹훅 설정 문서](https://info.pocketalert.app/api/webhooks/settings.html)에서 확인할 수 있습니다.

## 자주 묻는 질문

### 쿠버네티스 알림을 Pocket Alert로 보내려면 어떻게 하나요?

Alertmanager에 webhook_configs 리시버를 추가하고 Pocket Alert 수신 URL인 https://p4a.me/wh/1234abcd를 지정하세요. 발생한 CrashLoopBackOff 또는 OOMKilled 알림이 푸시로 전달됩니다.

### Pocket Alert는 Alertmanager 페이로드를 어떻게 읽나요?

GJSON 필드 매핑이 Alertmanager JSON을 읽습니다. commonLabels.alertname은 제목으로, alerts.0.labels.namespace와 alerts.0.labels.pod은 본문으로 가져와서 원본 페이로드 대신 네임스페이스와 파드 이름이 화면에 표시되도록 합니다.

### 발생 알림과 해결 알림을 구분할 수 있나요?

페이로드에는 status(firing 또는 resolved)와 commonLabels.severity가 들어 있습니다. 두 값을 GJSON 메시지 템플릿에서 참조하면 발생한 critical 알림과 해결 알림을 서로 다르게 표시할 수 있습니다.

### prod와 staging 클러스터를 어떻게 나누나요?

prod와 staging에 각각 별도의 Pocket Alert 애플리케이션을 만들고 웹훅 URL도 따로 설정하세요. Alertmanager 라우트를 각 클러스터에 하나씩 연결하면 staging의 NotReady 노드 알림이 prod 알림과 섞이지 않습니다.

### 클러스터 안에 에이전트를 실행해야 하나요?

아니요. 이미 Alertmanager를 운영 중이라면 클러스터 안에 추가로 설치할 것이 없습니다. 컨트롤러나 스크립트가 Token 헤더와 함께 https://api.pocketalert.app/v1/messages로 직접 POST 요청을 보내도 됩니다.

### 알림 심각도를 알림 우선순위에 매핑할 수 있나요?

네. 모든 메시지에는 silent, low, default, high, critical 중 하나의 level을 지정할 수 있습니다. 웹훅 페이로드에 "level" 필드를 넣거나 웹훅 자체에 default_level을 설정하세요. 페이로드에 명시한 level이 항상 우선합니다. 일반적인 구성은 firing=critical, resolved=silent입니다. 이렇게 하면 발생 알림은 Android에서 방해 금지 모드를 뚫고, iPhone에서는 시간 민감 알림으로 도착하며, 복구 알림은 기록에 조용히 남습니다. 잘못된 값은 거부되지 않고 default로 대체됩니다.
