[Claude] 배포 파이프라인(GitOps), 관측가능성(프로메테우스,그라파나,로키)

안녕하세요. AI 시대에 개발자가 알아야 할 인프라 구성 배포 with 클로드 코드 책을 읽고 학습한 내용을 정리했습니다.

 

이전 실습을 통해 클로드 코드를 통해 Notiflex API 서버를 GKE에 배포했습니다. 서비스는 잘 돌아가고 있지만 기능을 추가하거나 버그를 고칠 때마다 '이거 배포해도 괜찮겠지?'라는 의문이 생깁니다. 지금 클러스터에 뭐가 배포되어 있는지 정확히 모릅니다.

 

이번 실습을 통해 Push 기반 배포의 한계를 이해하고, ArgoCD로 GitOps를 도입합니다. GitHub Actions CI를 구성하고, CI와 ArgoCD를 연결하여 코드 Push부터 배포까지 자동화합니다.

 

3장. [SMB] 첫 번째 배포 파이프라인

스토리: 배포할 때마다 긴장된다 → GitOps + CI 자동화

 

3.1 Push 기반 배포의 한계

- 드리프트를 알 수 없다: 클러스터에 실제로 적용된 것과 깃, 문서의 내용이 같은지 보장할 방법이 없습니다. 누가 kubectl edit 명령으로 내용을 수정해도 모르는 채로 지나갑니다.

- '왜'가 남지 않는다: Deployment는 kubectl rollout undo 명령으로 직전 상태로 되돌릴 수  있지만, '왜 이 배포를 했는지'는 어디에도 남지 않습니다. CHANGE-CAUSE는 대부분 <none>이고 revision 보관 개수를 넘기면 과거 이력도 조용히 사라집니다.

- 리소스마다 기준이 다르다: ConfigMap처럼 rollout history가 없는 리소스는 되돌릴 근거 자체가 없습니다. Deployment 하나만 채겨서는 전체 상태를 복원할 수 없습니다.

 

이 문제를 해결하는 첫 단계는 '명령형(imperative) 사고에서 선언형(declarative) 사고로 옮겨가는 것입니다. 명령형은 당장 사용하기는 편하지만 실행이 끝나면 흔적이 없습니다. 선언형은 매번 YAML을 고쳐야 해서 불편해보이지만 곧 기준 내용이 됩니다. YAML을 깃에 커밋하면 자동으로 '누가, 언제, 왜'그렇게 했는지도 기록에 남습니다. 쿠버네티스는 철학 자체가 선언형입니다. 제대로 쓰려면 선언형에 맞춰 생각해야 합니다. 

GitOps는 여기서 한발 더 나아가 '깃에 적힌 YAML이 기준이고 클러스터는 그걸 계속 따라오기만 하면 된다'는 관점입니다. 

3.2 ArgoCD 설치 및 GitOps 연결

코드를 푸시하면 자동으로 배포되는 GitOps 파이프라인을 구축합니다. 

 

[프롬프트]

현재 환경에서 배포 자동화 도구는 어느 걸 쓰는게 좋아?

 

 

[프롬프트]

ArgoCD로 진행해줘

 

[프롬프트]

이제 ArgoCD랑 내 깃허브 저장소 연결해줘

 

GitHub: notiflex-platform ──(연결됨, private 인증)──▶ ArgoCD repo-server
   │                                                        │
   │  git push (k8s/smb/ 변경)                              │ ~3분마다 or 즉시 비교
   ▼                                                        ▼
  main 브랜치  ═══════════ auto-sync ═══════════▶  GKE notiflex 네임스페이스

- 이제 k8s/smb/ 아래 매니페스트를 고쳐 push하면 ArgoCD가 자동 배포합니다.
- 누가 클러스터를 직접 손대도 selfHeal이 Git 상태로 되돌립니다.

3.3 ArgoCD로 롤링 업데이트: Git Push만으로 배포

 

새 기능 추가 및 배포

[프롬프트]

API에 버전 정보 확인할 수 있는 기능 추가하고 배포해줘

 

[프롬프트]

응, 진행해줘

 

 

[프롬프트]

혹시 방금 배포한 버전에 문제가 있으면 어떻게 돌려?

 

3.4 GitHub Actions CI: 빌드 자동화

 

[프롬프트]

지금 빌드할 때마다 명령어를 직접 입력하고 있는데 이거 자동으로 실행되게 할 수 없어?

 

[프롬프트]

깃허브 액션 CI 만들어줘

3.5 CI + ArgoCD 연결: 빌드부터 배포까지

[프롬프트]

CI에서 빌드하면 자동으로 배포까지 되게 할 수 있어?

 

[프롬프트]

CI랑 ArgoCD 연결해줘

 

[프롬프트]

이제 코드만 고치고 푸시하면 진짜로 배포까지 자동으로 되는 거야? 한번 해보자.

💡 마무리: CLAUDE.md에 행동 규칙 추가하기

 

2장에서 만든 CLAUDE.md에는 '이 프로젝트는 Go로 만든 Notiflex야, GCP 리전은 여기야' 같은 환경 정보와 함께 행동 규칙 8가지가 들어 있었습니다. 그중 5번('모든 kubectl 명령에 --gke-sysnet4admin_book_gitaiops를 반드시 지정')을 특히 강조했습니다.

3장에서는 GitOps 원칙과 직결된 세 줄을 CLAUDE.md에 체험 삼아 추가해보고 어떻게 작동하는지 확인한 뒤 다시 되돌려 보았습니다.

ArgoCD를 도입했으니 모든 변경은 깃을 통해야 합니다. 클로드 코드가 습관적으로 kubectl delete나 Kubectl apply를 실행하면 GitOps 원칙이 깨집니다. 이 동작을 막는 자연어 규칙을 CLAUDE.md에 잠시 넣어 동작을 확인해보겠습니다.

 

[프롬프트]

CLAUDE.md에 다음 행동 규칙을 추가해줘. 나중에 되돌릴 거야.
- 이 클러스터에서 kubectl delete를 직접 실행하지 마.
- kubectl apply도 직접 하지 말고, 항상 깃을 이용해서 ArgoCD로 배포해.
- 변경 전에 항상 diff를 먼저 보여줘.

 

[프롬프트]

notiflex 네임스페이스의 notiflex-api deployment를 지워줘

 

- 규칙이 없었다면 AI가 그대로 Kubectl delete deployement notiflex-api -n notiflex를 실행했을 것입니다. 규칙이 있으면 안전 확인과 올바른 경로 제안이 먼저 나옵니다. 사용자가 일일이 가르치지 않아도 AI가 팀의 운영 원칙을 따르게 만드는 것. 이것이 CLAUDE.md의 역할입니다. 다만 이 규칙이 항상 참조되는 것은 아닙니다. 클로드 코드는 대화 초반에 CLAUDE.md를 한 번 읽지만 긴 설치 과정이 이어지면 규칙을 다시 참조하지 안혹 그대로 kubectl delete 명령을 실행하는 경우도 있습니다. 이때 ArgoCD의 selfHeal 이 깃 상태를 기준으로 Pod를 곧 복원하므로 실제 서비스는 곧 정상 상태로 돌아옵니다. 자연어 규칙이 가이드이지 강제가 아니라는 뜻입니다.

 

[프롬프트]

notiflex-api 상태 확인해줘

 

이 책에서는 kubectl delete 나 kubectl apply를 직접 금지하는 규칙을 실제 CLAUDE.md에 넣지 않습니다. 그래서 3장에서는 추가한 규칙을 다시 제거하고 진행합니다. 

 

[프롬프트]

방금 추가한 규칙 되돌려줘

 

 

실무 운영 환경에서는 위와 같은 형태의 규칙을 고려하는 것이 좋습니다. 자연어 규칙만으로는 참조가 일관되지 않으므로 7장에서 settings.local.json으로 kubectl delete와 kubectl apply를 기술적으로 차단하는 방법을 소개합니다. 

 

이제 /update-docs로 변경을 기록합니다.

 

[프롬프트]

/update-docs

 

3장에서는 2장과 달리 3-프롬프트 패턴(탐색 -> 비교 -> 실행)이 등장합니다. 도구를 선택하는 서브챕터에서 클로드 코드가 어떤 파일을 참조하는지 살펴봅니다.

- decision-guides/ 는 독자가 '어떤 걸 쓸까?', '비교해줘'라고 물을 때 참조하는 파일입니다. 클로드 코드가 추천 이유와 비교 테이블을 이 파일에서 가져옵니다.

- prompt-guardrails/는 '진행해줘'라고 할 때 실행 순서를 안내하는 파일입니다. 

 

3장에서 GitOps와 CI/CD 파이프라인을 완성했습니다. 코드를 푸시하면 빌드부터 배포까지 자동으로 이루어집니다. 그런데 한가지 빠진 것이 있습니다. 서비스가 지금 잘 돌아가고 있는지 알 수 없습니다.

 

이번 실습을 통해 메트릭(Prometheus + Grafana), 로그(Loki + Fluent Bit), 알림(PrometheusRule + Alertmanager)을 구축하여 클러스터에서 무슨 일이 일어나고 있는지 한 화면에서 볼 수 있게 합니다.

 

4장. [SMB] 관측 가능성 한번에 구축하기

스토리: 새벽에 고객이 "서비스가 안 된다"고 연락, 뭐가 문제인지 모른다

 

4.1 관측 가능성이란

관측 가능성(Observability)은 메트릭, 로그 그리고 트레이스 3요소로 이루어집니다.

- 메트릭(metrics): 숫자입니다. 'CPU 90%, 초당 요청 500개, 에러율 2%'. 지금 상태가 정상인지 비정상인지를 판단하는 데이터입니다.

- 로그(logs): 텍스트입니다. 'connection refused at line 42, timeout after 30s'. 무엇이 잘못되었는지 원인을 찾는 데이터입니다.

- 트레이스(traces): 흐름입니다. 하나의 요청이 어떤 서비스를 거쳐 어디서 느려졌는지를 추적하는 데이터입니다.

 

4.2 메트릭 모니터링: Prometheus + Grafana

메트릭 수집과 시각화를 위해 어떤 도구를 쓰면 좋을지 클로드 코드에게 먼저 물어봅니다.

 

[프롬프트]

클러스터에서 뭐가 돌아가고 있는지 어떻게 알 수 있어?

 

[프롬프트]

프로메테우스랑 그라파나 설치해줘.

 

[프롬프트]

응 시작해줘.

 

[프롬프트]

설치 끝났으면 그라파나 화면을 한번 보고 싶은데, 어떻게 접속해?

 

 

[프롬프트]

프로메테우스가 데이터 수집하고 있는지 확인해줘.

4.3 로그 수집: Loki + Fluent Bit

메트릭은 '무엇이 잘못됐는지'를 알려주지만, '왜 잘못됐는지'는 로그에서 찾아야 합니다. 로그 수집 파이프라인을 구축합니다.

 

[프롬프트]

로그 수집 뭐 써? Pod 로그를 한곳에서 보고 싶어.

 

[프롬프트]

설치는 됐는데 로그가 진짜 들어오고 있는지 그라파나에서 볼 수 있어?

 

4.4 알림 설정: PrometheusRule

문제가 생기면 자동으로 알려주는 알림을 설정합니다.

 

[프롬프트]

문제가 생기면 자동으로 알림 받을 수 있어?

 

[프롬프트]

알림 설정해줘.

 

[프롬프트]

알림 규칙이 제대로 동작하는지 어떻게 확인해?

 

💡 가장 실무적인 팁: 새 알림 규칙을 만들면 ②(임계값 임시 조정으로 firing 강제)로 배선을 먼저 확인하고, 여유가 있으면 ③(실제 조건 유발)으로 검증하세요. 알림은 "필요할 때 안 울리는 것"이 가장 위험하므로, 만든 직후 한 번은 firing시켜 보는 게 좋습니다.

 

💡 마무리: memory에 작업 컨텍스트 기록

 

클로드 코드에는 두 가지 기억 메커니즘이 있습니다.

• CLAUDE.md : 사용자가 직접 적어두는 지시 사항으로 프로젝트 루트에 두면 매 세션 시작 시 내용 전체가 로드되어 항상 참조욉니다.
• 클로드 코드 메모리 : 클로드가 자동으로 기억하고 관리하는 메모리입니다. 사용자가 '기록해줘'라고 명시하지 않아도 의미있는 컨텍스트(반복되는 사용자 선호, 보류한 결정, 특정 도구에 대한 의도 등)가 발견되면 클로드 코드가 토픽 파일로 분류해 저장합니다. ~/.claude/projects/<프로젝트>/memory/에 저장됩니다.  디렉터리의 MEMORY.md는 세션 시작 시 첫 200줄까지 함께 로드되어 '어떤 기억이 있는지' 알려주는 목차 역할을 하고 개별 토픽 파일은 관련 주제가 나올 때 클로드 코드가 직접 읽어 가져옵니다. 

자동 기록은 클로드 코드의 판단에 따라 일어나지만 자동으로 항상 일어난다고 보장되지는 않습니다. 그래서 명시 요청을 함께 알아두면 좋습니다. 명시 요청은 단순합니다. '메모리에 기록해줘'라는 한 줄이면 됩니다. 

 

 

[프롬프트]

PrometheusRule 임계값은 일단 5분/3회로 뒀는데 운영 데이터를 보고 조정해야해. 메모리에 TODO로 적어둬.

 

같은 방식으로 다양한 항목을 메모리에 적을 수 있습니다.

• TODO : 분산 트레이싱은 서비스 간 호출이 생기는 8장에서 도입
• 사용자 선호: Kubectl apply 보다 헬름 차트 사용 의도
• 작업 패턴 : Pod 리소스 requests 결정 시 resource-budget.md 참조 우선순위
• 금지사항 : 이미지 태그 :latest 금지, 명시적 sha 또는 vX.Y.Z만 사용

 

이렇게 한 항목씩 추가하면 새 대화에서도 클로드 코드가 같은 컨텍스트로 답합니다. 

새 대화에서 같은 주제를 물어보면 클로드 코드가 인덱스에서 해당 토픽을 찾아 답합니다. 시간이 지나 작업 흐름이 흐릿해질 때를 가정해보고 질문해봅시다. 

 

[프롬프트]

PrometheusRule 임계값 조정 TODO가 있었지?

 

[프롬프트]

/update-docs