[모각코] 1주차 스터디 소개

앞으로 4주간 온라인 모각코를 통해 스터디한 내용을 업로드할 예정입니다.

모각코란 모여서 각자 코딩의 준말로, CloudNet@ 가시다님과 함께 책 하나를 돌파하는 스터디입니다.

이번 모각코는 책, AI 시대에 개발자가 알아야 할 인프라 구성 배포 with 클로드 코드 를 기반으로 진행합니다.

 

스터디 책 소개

책 (AI 시대에 개발자가 알아야 할 인프라 구성 배포 with 클로드 코드) 에서는 가상의 스타트업, Notiflex 스타트업 시나리오에 맞춰 실습 내용이 구성되어 있습니다.

Notiflex는 B2B 알리 SaaS 플랫폼입니다. 고객사의 서비스에서 발생하는 이벤트를 받아 이메일, SNS 푸시 알림으로 발송합니다. 고객사는 Notiflex의 API를 호출하기만 하면 되고, 알림 발송 등의 복잡한 처리는 Notiflex가 담당합니다.

 

[Netiflex의 성장 타임 라인]

단계	내용
[2장] 창업	Notiflex를 만들었다. GKE 위에 API 서버 하나를 올린다.
[3장] 첫 고객	배포할 때마다 긴장된다. ArgoCD로 GitOps를 도입한다.
[4장] 서비스 장애	새벽에 고객이 "알림이 안 온다"고 연락했다. 뭐가 문제인지 모르겠다. 관측 가능성(observability)을 구축한다.
[5장] 성장 시작	고객이 늘면서 배포할 때마다 서비스가 끊긴다. 무중단 배포를 도입한다.
[6장] 전환기	더 많은 고객이 들어오면서 응답이 느려지고 보안에 우려가 생긴다. 캐시, 시크릿 관리, 배포 전략을 정비한다.
[7장] 대형 계약	대형 고객사가 전용 환경을 요청한다. 인프라를 확장하고 테넌트를 분리한다.
[8장] 대규모 운영	서비스 간 호출이 꼬이고, 배치가 밀린다. 이벤트 드리븐, 분산 트레이싱, 배치 자동화를 도입한다.
[9장] 돌아보기	여기까지 오는 동안 깃에 쌓인 코드, 설정, 문서를 본다. 이것이 살아있는 운영 표준, GitAIOps다.위 타임라인에서 필자는 클로드 코드와 함께 인프라를 관리할 예정입니다.

본 책의 실습은 저자님의 깃허브를 통해 공개되어 있습니다.

Embed GitHub

 

Embed GitHub

 

 

GItAIOps ?

GitAIOPs는 GitOps에 AI를 더한 개념으로 자연어를 통해 GItOps를 자동 관리하는 개념입니다.

GitOps는 인프라 관리 방식입니다. 서버 설정이나 배포 상태를 코드(YAML 파일)로 정의해서 Git 저장소에 저장해두고, Git에 푸시하면 ArgoCD 같은 도구가 그 내용을 자동으로 클러스터에 반영해주는 방식입니다.

"Git = 진실의 원천(source of truth)"이라는 철학이 핵심입니다.

문제는 이 YAML을 사람이 직접 작성해야 하고, 뭔가 문제가 생기면 사람이 로그를 뒤져서 원인을 찾아야 하고, 문서화도 따로 챙겨야 한다는 점입니다.

 

즉 "선언"과 "배포 자동화"는 되어 있지만, 그 앞뒤 작업은 여전히 사람 몫으로 큰 에포트가 생깁니다.

여기서, AI를 이용해서 AI가 YAML를 작성하고, 배포와 로그 분석, 문서화, 검증을 진행합니다.

사람은 자연어로만 지시하면 됩니다.

	GitOps	GitAIOps
상태 정의	사람이 YAML 작성	AI가 자연어로부터 YAML 생성
배포	깃 푸시 → 자동 Sync	동일
트러블슈팅	사람이 로그 분석	AI가 로그 분석 후 수정안 제시
문서화	사람이 별도 작성(또는 안 함)	AI가 작업과 동시에 문서 생성
검증	사람이 수동 확인	AI가 클러스터 상태와 문서를 비교

클로드 코드 가드레일 시스템

AI가 강력하지만, 인프라 환경에서는 정확하고 일관성이 중요합니다.

책에서는 가드레일을 소개 합니다. 가드레일은 클로드 코드가 검증된 경로를 따르도록 안내하는 기능입니다.

가드레일에는 사전 조건, 단계별 절차, 트러블슈팅 가이드가 포함되어 있습니다.

가드레일을 참조하면서 작업하기 때문에, 자연어로 지시하면서 안정적인 결과를 얻을 수 있습니다. (출처 : 책)

위 가드레일은 CLAUDE.md에 정의되어 있습니다.

Embed GitHub

 

이 파일은 독자(실습자)가 자연어로 뭔가를 요청했을 때, 클로드 코드가 정해진 참조 문서를 찾아서 그대로 따라 하도록 만드는 메뉴얼입니다.

구성 내용을 정리하면 다음과 같습니다.

 

1. 입력 유형 3가지 분류

독자의 자연어 입력을 챕터별 표와 매칭해서, 질문의 성격에 따라 다른 문서를 참조하도록 구성되어 있습니다.

• 탐색: "뭘 쓰면 돼?", "어떤 방법이 있어?" → decision-guides/ 참조하여 추천 + 이유 설명
• 비교: "다른 건?", "장단점 비교해줘" → decision-guides/ 비교 섹션 참조
• 실행: "그걸로 진행해줘", "설치해줘" → prompt-guardrails/ 참조하여 실행

3-프롬프트 패턴으로 탐색 → 비교 → 실행으로 구성됩니다.

유형별 지침 내용을 확인하겠습니다.

4장, 관측 가능성 구성에 대한 프롬프트에 대해 미리 구성한 구성한 내용으로 실행됩니다.

 

탐색, 비교 참조 문서 확인

4.2 메트릭 모니터링 도구 선택 (decision-guides/ch4/4.2-metrics-monitoring.md) → 상황, 질문, 추천, 비교, 핵심 개념, 실행 연결로 구성

 

# 4.2 메트릭 모니터링 도구 선택

## 상황

ArgoCD로 GitOps를 구축했고, CI/CD 파이프라인도 동작한다. 하지만 클러스터에서 "무슨 일이 일어나고 있는지" 모른다. CPU는 괜찮은지, Pod이 재시작되고 있는지, 요청은 몇 개나 들어오는지 — 메트릭이 없다.

## 독자가 물어볼 수 있는 질문

- "클러스터 모니터링 어떻게 해?"
- "CPU, 메모리 사용량을 보고 싶은데 뭘 써야 해?"
- "Prometheus가 뭐야?"
- "모니터링 도구 추천해줘"

## 추천: Prometheus + Grafana (kube-prometheus-stack)

Prometheus가 메트릭을 수집하고, Grafana가 시각화한다. kube-prometheus-stack Helm 차트는 Prometheus, Grafana, Alertmanager, node-exporter, kube-state-metrics를 한 번에 설치한다.

이 프로젝트에 적합한 이유:
- **오픈소스 표준**: Kubernetes 모니터링의 사실상 표준 (CNCF Graduated)
- **비용 없음**: SaaS 구독료 없이 자체 호스팅
- **Helm 번들**: 6개 컴포넌트를 검증된 버전 조합으로 한 번에 설치
- **Grafana**: 대시보드로 시각적 모니터링, 4장 후반에서 Loki/Tempo와 연결

## 비교 

| 도구 | 특징 | 장점 | 단점 | Notiflex 적합도 |
|------|------|------|------|----------------|
| **Prometheus + Grafana** | 오픈소스, Pull 기반, PromQL | 무료, K8s 표준, 생태계 거대 | 자체 운영 필요, 장기 저장 제한 | ★★★ |
| **Datadog** | SaaS, 에이전트 기반 | 설정 간편, 통합 대시보드, APM | 유료(호스트당 $15+/월), 비용 예측 어려움 | ★★ |
| **CloudWatch** | AWS 네이티브 | AWS 통합, 관리 불필요 | GKE에서 사용 불편, 커스텀 메트릭 비쌈 | ★ |
| **Google Cloud Monitoring** | GCP 네이티브 | GKE 통합, 무료 티어 | 커스텀 대시보드 제한, 학습 목적에 부족 | ★★ |

> **Notiflex 맥락**: 학습 환경에서 SaaS 비용을 쓸 이유가 없다. Prometheus는 e2-medium에서 CPU 100m, Memory 256Mi로 구동 가능하다. 이후 Loki(로그), Tempo(트레이스)와 Grafana 하나로 통합되므로 도구 파편화가 없다.

## 핵심 개념

- **Pull 기반 수집**: Prometheus가 각 Pod의 `/metrics` 엔드포인트를 30초마다 조회(scrape)한다. Push 방식과 달리 모니터링 대상이 Prometheus에 데이터를 보낼 필요가 없다.
- **PromQL**: Prometheus의 쿼리 언어. `rate(http_requests_total[5m])`처럼 시계열 데이터를 집계/필터한다.
- **ServiceMonitor**: Prometheus Operator의 CRD. 어떤 Service를 scrape할지 선언적으로 정의한다.
- **kube-state-metrics**: K8s API에서 오브젝트 상태(Pod 수, Deployment replica 등)를 메트릭으로 변환한다.

## 실행 연결

독자가 Prometheus+Grafana를 선택하면 → `prompt-guardrails/ch4/4.2-prometheus-grafana.md`

 

실행 참조 문서 확인

4.2 메트릭: Prometheus + Grafana 설치

# 4.2 메트릭: Prometheus + Grafana

## 사전 조건
- ArgoCD 설치 완료 (ch3.2)
- `shared/resource-budget.md` 확인: kube-prometheus-stack은 **Prometheus 100m + Grafana 50m + Alertmanager 25m + operator 25m + kube-state-metrics 10m = ~210m** CPU를 추가한다.

> ⚠️ **ch6 대비 리소스 주의**: 여기서 설치하는 관측 가능성 스택은 ch6에서 CSI DaemonSet(240m)이 추가될 때 CPU 부족의 원인이 된다. ch6 진입 전에 Prometheus/Grafana/Alertmanager의 CPU requests를 5m으로 축소해야 하므로, 여기서 설정하는 값은 임시적이라는 점을 인지한다.

## 실행 지침

### 단계 1: kube-prometheus-stack 설치

`kube-prometheus-stack`은 Prometheus + Grafana + Alertmanager + Prometheus Operator + kube-state-metrics + node-exporter를 한 번에 묶어 설치하는 Helm 차트다. 50개가 넘는 리소스(Deployment, StatefulSet, Service, ConfigMap, CRD)를 직접 작성하지 않아도 되고, 차트 인자(`-f helm-values/...`)만으로 일관된 튜닝이 가능하다. 컴포넌트 간 ServiceMonitor·PrometheusRule 연결도 차트가 알아서 묶는다.

```bash
kubectl create namespace monitoring
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install kube-prometheus prometheus-community/kube-prometheus-stack \
  -n monitoring -f helm-values/kube-prometheus.yaml
```

`helm-values/kube-prometheus.yaml` 파일을 생성한다. e2-small 노드에 맞게 리소스를 조정:
- Prometheus: requests 100m/256Mi
- Grafana: requests 50m/128Mi
- Alertmanager: requests 25m/64Mi

### 단계 2: Grafana UI 접속

```bash
kubectl port-forward svc/kube-prometheus-grafana -n monitoring 3000:80
```

브라우저에서 `http://localhost:3000` 접속 (ID: admin, PW: `kubectl get secret`으로 확인).

### 단계 3: Notiflex 대시보드 생성

Grafana에 Notiflex 전용 대시보드를 ConfigMap으로 생성한다:
- Pod CPU/Memory 사용량
- HTTP 요청 수
- Pod 재시작 횟수

## 트러블슈팅

### Pod Pending (CPU 부족)
kube-prometheus-stack은 5개 이상의 컴포넌트를 배포한다. e2-medium 2노드에서 ArgoCD(~500m)와 함께 설치하면 CPU requests가 빠듯해진다.
→ `helm-values/kube-prometheus.yaml`에서 requests를 축소한다.
→ 그래도 Pending이면 `kubectl describe pod <pending-pod> -n monitoring`으로 원인 확인.

### Prometheus StatefulSet 리소스 변경이 반영 안 됨
Prometheus CR의 `spec.resources`를 변경해도 기존 StatefulSet이 자동으로 업데이트되지 않을 수 있다.
→ StatefulSet을 삭제하면 Prometheus Operator가 새 스펙으로 재생성한다:
```bash
kubectl delete statefulset prometheus-kube-prometheus-prometheus -n monitoring
```

### ch6 진입 전 CPU 축소 방법
ch6에서 CSI DaemonSet이 240m CPU를 차지한다. 사전에 관측 가능성 스택을 축소한다:
```bash
# Prometheus CR 직접 패치
kubectl patch prometheus kube-prometheus-prometheus -n monitoring \
  --type merge -p '{"spec":{"resources":{"requests":{"cpu":"5m"}}}}'
# 반영 안 되면 StatefulSet 삭제 → operator가 재생성
kubectl delete statefulset prometheus-kube-prometheus-prometheus -n monitoring

# Grafana — JSON patch 사용 (multi-container이므로 인덱스로 지정)
# 컨테이너 순서 확인: kubectl get deploy kube-prometheus-grafana -n monitoring -o jsonpath='{.spec.template.spec.containers[*].name}'
# 보통 0: grafana-sc-dashboard, 1: grafana-sc-datasources, 2: grafana
kubectl patch deployment kube-prometheus-grafana -n monitoring \
  --type=json -p='[{"op":"replace","path":"/spec/template/spec/containers/2/resources/requests/cpu","value":"5m"}]'

# Operator — resources 섹션이 없을 수 있으므로 add op 사용
kubectl patch deployment kube-prometheus-kube-prom-operator -n monitoring \
  --type=json -p='[{"op":"add","path":"/spec/template/spec/containers/0/resources","value":{"requests":{"cpu":"5m"}}}]'

# Alertmanager
kubectl patch alertmanager kube-prometheus-alertmanager -n monitoring \
  --type merge -p '{"spec":{"resources":{"requests":{"cpu":"5m"}}}}'
```

> ⚠️ **`--type merge` 실패**: Grafana Deployment처럼 multi-container Pod에 strategic merge patch를 쓰면 `"spec.template.spec.containers[0].image: Required value"` 에러가 발생한다. 컨테이너를 특정하려면 image 필드도 포함해야 하기 때문. **`--type=json`으로 컨테이너 인덱스를 직접 지정**하면 이 문제를 피할 수 있다.

> ⚠️ **resources 섹션 미존재**: operator 등 일부 Deployment는 resources 섹션 자체가 없다. 이 경우 `"op":"replace"`는 실패하고 `"op":"add"`로 경로를 생성해야 한다.

## 💬 질문해보기

> "Prometheus 말고 메트릭 수집 도구는 뭐가 있어? Datadog, New Relic 같은 SaaS와 비교하면?"

 

2. 안전장치: kubectl 컨텍스트 강제

이 책은 claude --dangerously-skip-permissions (승인 절차 없이 명령을 실행하는 모드)로 진행하는 걸 전제로 합니다. 잘못된 클러스터 대상으로 동작하지 않도록 모든 kubectl 명령에 반드시 클러스터 컨텍스트를 명시하도록 강제하고 있습니다.

 

3. 작업 후 검증 절차

작업 검증을 위해 각 장의 작업이 완료되면 result-templates 를 실행하여 실제 결과와 비교하여 보여줍니다.또한, 각 장의 마지막에는 /update-docs라는 커스텀 명령으로 문서를 자동 갱신하도록 안내합니다.

4.2 메트릭: Prometheus + Grafana — 예상 결과(result-templates/ch4/4.2-prometheus-grafana.md) → 상태 확인, 체크리스트, 아키텍처 추천

 

# 4.2 메트릭: Prometheus + Grafana — 예상 결과

## 상태 확인

```
$ kubectl get pods -n monitoring
NAME                                                     READY   STATUS    RESTARTS   AGE
kube-prometheus-grafana-xxxxxxxxxx-xxxxx                  3/3     Running   0          3m
prometheus-kube-prometheus-prometheus-0                    2/2     Running   0          3m
kube-prometheus-kube-prome-operator-xxxxxxxxxx-xxxxx      1/1     Running   0          3m
alertmanager-kube-prometheus-alertmanager-0                2/2     Running   0          3m
```

## 체크리스트

- [ ] kube-prometheus-stack 설치됨
- [ ] Grafana UI 접속 가능 (http://localhost:3000)
- [ ] Prometheus가 메트릭 수집 중
- [ ] Notiflex 전용 대시보드 생성됨

## 이 단계 이후 아키텍처

```
GKE: notiflex-cluster
├── monitoring namespace
│   ├── Prometheus (메트릭 수집)
│   ├── Grafana (시각화)
│   └── Alertmanager (알림)
├── argocd namespace
│   └── ArgoCD
└── notiflex namespace
    └── notiflex-api (v0.1.x)
```

 

4. JOURNEY.md

독자의 notiflex-platform/JOURNEY.md는 독자가 실제로 진행한 내용의 기록이다.

prompt-guardrails/shared/journey-template.md 를 참고하여 독자의 진행 사항을 기록한다.

 

참고

AI 시대에 개발자가 알아야 할 인프라 구성 배포 with 클로드 코드