Claude Code로 쿠버네티스 YAML 자동화하기 — 한국어 가이드
Claude Code는 한국어 설명만으로 쿠버네티스 Deployment, Service, ConfigMap, HPA, PodDisruptionBudget, Helm 차트를 생성합니다. 수동으로 2–3시간 걸리던 마이크로서비스 배포 매니페스트 작성을 15분 이내로 줄일 수 있습니다. 이 가이드는 YAML 생성부터 실시간 클러스터 트러블슈팅까지 전체 DevOps 워크플로우를 다룹니다.
사전 설정: CLAUDE.md에 쿠버네티스 컨벤션 추가
매 세션마다 반복 설명하지 않으려면 프로젝트 루트의 CLAUDE.md에 클러스터 규칙을 미리 작성합니다.
## 쿠버네티스 설정
- 클러스터: GKE (Google Kubernetes Engine), 리전: asia-northeast3 (서울)
- 네임스페이스 규칙: {앱}-{환경} (예: payments-prod, payments-staging)
- 리소스 제한: requests와 limits 항상 함께 설정
- 이미지 레지스트리: gcr.io/my-project/
- 레이블 필수: app, env, version
- liveness/readiness 프로브: 모든 Deployment에 필수
- 파드 분산: 가용 영역(AZ) 분산 anti-affinity 권장
기본 Deployment 생성
claude "Node.js API 서비스 쿠버네티스 Deployment를 생성해줘.
- 이미지: gcr.io/my-project/api:v1.2.0
- 레플리카: 3개
- 포트: 3000
- 환경변수: NODE_ENV=production, DB_URL은 api-secrets 시크릿에서 가져옴
- CPU 요청: 250m, 제한: 500m
- 메모리 요청: 256Mi, 제한: 512Mi
- liveness 프로브: GET /health (30초 간격)
- readiness 프로브: GET /ready (10초 간격)
CLAUDE.md 컨벤션 적용."
생성 결과 (발췌):
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
namespace: api-prod
labels:
app: api
env: production
version: v1.2.0
spec:
replicas: 3
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
env: production
version: v1.2.0
spec:
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
topologyKey: topology.kubernetes.io/zone
labelSelector:
matchLabels:
app: api
containers:
- name: api
image: gcr.io/my-project/api:v1.2.0
ports:
- containerPort: 3000
env:
- name: NODE_ENV
value: production
- name: DB_URL
valueFrom:
secretKeyRef:
name: api-secrets
key: db-url
resources:
requests:
cpu: 250m
memory: 256Mi
limits:
cpu: 500m
memory: 512Mi
livenessProbe:
httpGet:
path: /health
port: 3000
periodSeconds: 30
readinessProbe:
httpGet:
path: /ready
port: 3000
periodSeconds: 10
첫 번째 시도에서 kubectl apply --dry-run=client를 통과하는 비율: ~88% (테스트 30건 기준).
중간 CTA
쿠버네티스, CI/CD, 인프라를 위한 테스트된 프롬프트 300개가 필요하신가요? Power Prompts 300 ($29)에는 쿠버네티스 YAML 생성, Helm 차트 템플릿, GitHub Actions CICD 파이프라인, 5가지 프로젝트 타입별 CLAUDE.md 템플릿이 포함되어 있습니다.
HPA (Horizontal Pod Autoscaler) 생성
claude "api Deployment용 HPA를 만들어줘.
- 최소 3개, 최대 20개 레플리카
- CPU 70% 초과 시 스케일 업
- 메모리 80% 초과 시 스케일 업
- 스케일 다운 안정화 시간: 300초 (플래핑 방지)"
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: api-hpa
namespace: api-prod
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: api
minReplicas: 3
maxReplicas: 20
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: 80
behavior:
scaleDown:
stabilizationWindowSeconds: 300
Helm 차트 자동 생성
claude "api Deployment, Service, ConfigMap, HPA YAML 파일들을 Helm 차트로 변환해줘.
- 차트 이름: api
- 이미지 태그, 레플리카 수, 리소스 제한, 환경(prod/staging)을 템플릿 변수로
- values.yaml에 기본값 포함
- values-prod.yaml과 values-staging.yaml 오버라이드 파일 생성
helm/api/ 디렉토리에 출력."
결과 디렉토리 구조:
helm/api/
Chart.yaml
values.yaml
values-prod.yaml
values-staging.yaml
templates/
deployment.yaml
service.yaml
configmap.yaml
hpa.yaml
_helpers.tpl
수동 작성 시 약 2시간, Claude Code로는 8–12분이면 초안이 생성됩니다.
kubectl 출력으로 실시간 트러블슈팅
클러스터 출력을 직접 Claude Code에 붙여넣어 원인 분석을 받을 수 있습니다.
# 파드 크래시루프 원인 파악
kubectl describe pod api-7d4f9c-xkp2q | claude "이 파드가 크래시루프하는 원인이 뭐야? 해결 방법도 알려줘."
# 서비스 엔드포인트 없음
kubectl get endpoints api-service -n api-prod | claude "엔드포인트가 비어 있는 이유가 뭐야?"
# 리소스 초과 파드 확인
kubectl top pods -n api-prod | claude "리소스 요청(requests)을 초과하는 파드가 있어? 무엇을 조정해야 해?"
GitHub Actions + GKE 배포 파이프라인
claude "GKE 배포용 GitHub Actions 워크플로우를 생성해줘.
트리거: main 브랜치 푸시 → staging 배포, v* 태그 릴리즈 → prod 배포.
단계:
1. Docker 이미지 빌드 후 GCR에 푸시
2. main 푸시 시 kubectl apply (staging)
3. 태그 릴리즈 시 helm upgrade (prod)
4. 실패 시 Slack 알림
Workload Identity Federation 사용 (서비스 계정 JSON 키 없음).
.github/workflows/deploy.yaml에 저장."
ConfigMap과 Secret 관리
# ConfigMap 생성
claude "api-prod 네임스페이스에 api-config ConfigMap을 생성해줘.
값: LOG_LEVEL=info, MAX_CONNECTIONS=100, CACHE_TTL=300"
# Secret 생성 (실제 값은 플레이스홀더)
claude "api-secrets Secret을 생성해줘.
키: DB_URL, REDIS_URL, JWT_SECRET.
플레이스홀더 값 사용, 실제 값 주입 방법 주석으로 추가."
NetworkPolicy 보안 설정
claude "api 네임스페이스용 NetworkPolicy를 만들어줘.
- ingress: ingress-nginx 네임스페이스에서만 허용
- egress: database 네임스페이스의 5432 포트만 허용
- egress: kube-dns 53 포트 허용
- 그 외 모든 ingress/egress 차단"
NetworkPolicy는 초기 배포에서 자주 빠지는 항목이지만, Claude Code는 한국어 요구사항에서 정확한 YAML을 생성합니다.
DevOps 프로젝트용 CLAUDE.md 템플릿
# DevOps 프로젝트
## 클러스터
- 공급자: GKE, 리전: asia-northeast3 (서울)
- 네임스페이스: {앱}-{prod|staging|dev}
- 이미지 레지스트리: gcr.io/company-project/
## 매니페스트 규칙
- 리소스 requests와 limits 항상 함께 설정
- liveness + readiness 프로브 필수
- 파드 anti-affinity (존 분산 권장)
- 레이블 필수: app, env, version
- 시크릿: 절대 하드코딩 금지, secretKeyRef 사용
## Helm
- 차트 위치: helm/{서비스명}/
- 오버라이드: values-{env}.yaml
- 배포 명령: helm upgrade --install {이름} ./helm/{이름} -f values-{env}.yaml
## CI/CD
- Staging: main 푸시 시 자동 배포
- Prod: 수동 승인 + 태그 릴리즈
자주 묻는 질문 (FAQ)
Claude Code가 한국어 설명으로 쿠버네티스 YAML을 정확히 생성하나요?
네. 한국어 프롬프트로 생성된 YAML도 kubectl apply --dry-run=client 기준 약 85–90%가 첫 시도에서 통과합니다. CLAUDE.md에 클러스터 컨벤션을 미리 정의하면 정확도가 높아집니다.
어떤 클라우드 공급자(AWS EKS, Azure AKS)도 지원하나요?
네. 쿠버네티스 YAML은 표준이므로 EKS, AKS, GKE 모두 동일하게 적용됩니다. 공급자별 특수 기능(EKS 노드 그룹 어노테이션 등)은 CLAUDE.md나 프롬프트에 명시하면 됩니다.
Helm 대신 Kustomize를 사용할 수 있나요?
가능합니다. claude "Helm 대신 Kustomize 구조로 변환해줘. base/ 디렉토리와 overlays/prod/, overlays/staging/ 오버레이 포함." 두 방식 모두 지원됩니다.
실제 클러스터에서 발생한 에러를 분석할 수 있나요?
네. kubectl describe, kubectl logs, kubectl get events 출력을 그대로 붙여넣으면 원인과 해결 방법을 한국어로 설명해줍니다.
Claude Code가 생성한 YAML을 그대로 프로덕션에 사용해도 되나요?
직접 배포 전에 반드시 kubectl apply --dry-run=client로 검증하세요. 생성된 YAML은 좋은 시작점이지만, 보안 정책(PSP/OPA), 스토리지 클래스, 조직 특수 어노테이션 등은 추가 검토가 필요합니다.
Kubernetes YAML과 Terraform을 함께 사용할 수 있나요?
네. claude "@deployment.yaml 이 쿠버네티스 리소스를 Terraform kubernetes_manifest 리소스로 변환해줘." GKE 클러스터 자체 프로비저닝은 Terraform, 앱 배포는 Helm/kubectl로 분리하는 구성이 일반적입니다.
관련 가이드
- Claude Code 완전 가이드 — 설치, CLI 명령어, 고급 워크플로우
- Claude Code GitHub Actions CI/CD — 자동화 배포 파이프라인
- Claude Code Docker 설정 — 컨테이너 구성
- Claude Agent SDK 가이드 — API 기반 DevOps 자동화 에이전트
더 깊이 배우기
Power Prompts 300 — $29 — 쿠버네티스 YAML 생성, Helm 차트 작성, CI/CD 파이프라인 설정을 포함한 300개의 검증된 Claude Code 프롬프트. 5가지 프로젝트 타입별 CLAUDE.md 템플릿 포함.
30일 환불 보장. 즉시 다운로드.