[AI 시대에 개발자가 알아야 할 인프라 구성 배포 with 클로드코드]스터디 1주차

https://www.yes24.com/product/goods/191693950

 

요즘 개인 공부에 너무 소홀했던 것 같아 스터디를 시작했다.

 

“AI 시대에 개발자가 알아야 할 인프라 구성 배포 with 클로드 코드” 라는 책을 읽고 공부한 내용을 올리는 모각코 형식의 스터디이고 이번주는 챕터 1~2를 읽고 실습한 후 공부한 내용에 대해 포스팅을 진행해야 한다.

 

---

 

CH01. AI 시대, 개발자의 인프라

1.1 개발자에게 인프라가 다가온 시대

"you build it, you run it"

 

Amazon의 CTO Werner Vogels가 20년 전 인터뷰에서 언급한 '제품팀에서 개발과 운영을 같이 진행한다'라는 개념은 이제는 당연하게 다가온다.

 

하지만 현실에서는 "개발" 조직에서 클라우드 서비스 등의 "인프라" 영역을 제대로 같이 하는 경우는 AWS SDE 말고는 보지 못했던 것이 사실인데... 최근 클로드 코드를 위시한 AI 개발 도구를 통해 인프라와 크게 관련이 없는 개발 직무에서도 인프라에 대한 접근성이 높아지면서 인프라 엔지니어도 단순히 인프라를 구축 & 전달하는 것이 아니라 AI 도구를 통해 개발자가 필요할 때 빠르고 안전하게 인프라를 구성할 수 있는 환경을 조성하는 형태로 역할이 변하고 있다고 생각한다.

 

1.2 쿠버네티스, 클라우드 인프라의 공통 언어

이 책에서 쿠버네티스를 학습 대상으로 삼는 이유는 다음과 같다. 

1. 특정 벤더에 종속되지 않음
2. 쿠버네티스 자체가 일종의 클라우드 플랫폼 역할
3. 배포, 네트워킹, 설정 관리, 스케일링, 모니터링 등 인프라 핵심 영역을 포괄. 이를 이해하면 다른 플랫폼 학습도 용이

 

1.3 GitOps에서 GitAIOps로

GitOps는 Git에 선언된 상태를 클러스터에 자동으로 반영하지만, 그 상태를 '정의하는 작업'은 여전히 사람의 몫이다. GitAIOps는 그 앞단(정의·트러블슈팅·문서화·검증)을 AI가 가속하는 개념이다.

 

GitOps vs GitAIOps 

구분	GitOps	GitAIOps
상태 정의 (매니페스트 작성)	사람이 YAML 직접 작성	자연어로 의도 전달 → AI가 YAML 생성
배포 반영	Git 커밋 → 도구(ArgoCD)가 자동 반영	동일 (Git 커밋 → ArgoCD, 유지)
트러블슈팅	사람이 명령어를 순서대로 실행하며 원인 추적	AI가 조회·분석을 빠르게 수행
문서화	별도 작업 필요, 현실에선 가장 먼저 빠짐	작업 과정 자체가 기록으로 남음
검증	사람이 수동 확인	"문서와 클러스터 상태 일치하는지 확인해줘" → AI가 조회·비교·차이 리포트
사람의 역할	정의 + 배포 + 운영 전반	도구 결정 + 의도 전달 + 결과 검증에 집중
병목	배포는 자동화됐지만 그 앞단 작업량은 그대로	앞단을 AI가 가속 → 1~2명으로도 감당 가능

 

 

GitAIOps에서 AI가 하는 일은 구체적으로는 다음과 같다.

매니페스트 작성	자연어로 의도를 전달하면 완성된 매니페스트가 나옴
트러블슈팅	명령어를 순서대로 실행하며 원인 추적하는 과정을 AI가 빠르게 수행
문서화	AI와 작업하면 그 과정 자체가 기록됨
검증	"현재 클러스터 상태가 문서와 일치하는지 확인해줘" → 실제 클러스터 조회 후 문서와 비교, 차이 리포트

 

1.4 이 책의 구성과 실습 흐름

이 책에서는 Notiflex라는 가상의 SaaS 서비스가 성장하는 과정을 클로드코드를 통해 따라가는 내용을 담고 있다. 

2장	환경 구성 — GKE + 클로드 코드 + 첫 배포
3~5장	SMB — GitOps, CI, 관측 가능성, 무중단 배포
6장	캐시, 보안, Canary
7~8장	규모 확장, 고도화
9장	GitAIOps: 살아있는 운영 표준

 

1.5 Notiflex 스타트업 시나리오

• Notiflex = B2B 알림 SaaS 플랫폼. 고객사 서비스에서 발생하는 이벤트(회원 가입 등)를 받아 이메일·SMS·푸시 알림으로 발송
• 기술 스택: API 서버(Go), scratch 기반 컨테이너 이미지, GKE

 

1.6 가드레일: 클로드 코드가 정확하게 동작하는 이유

가드레일 시스템 = 에이전틱 AI 도구가 정해진 범위에서, 검증된 방식으로 동작하도록 하는 장치.

 

가이드 저장소 루트의 CLAUDE.md를 클로드 코드가 자동으로 읽어 다음 세개 디렉터리의 가드레일을 따르도록 구성되어 있고, 사용자의 질문 유형에 따라 참조하는 디렉터리 / 파일이 달라진다. 인프라 작업에는 특히 정확성이 중요하기 때문에 실행 가드레일을 통해 기본적으로 제한되어야 하는 사항을 잡아주는 형태(k8s 컨텍스트 구성 등)로 구성되어있다.

decision-guides/	의사결정 가이드 — "왜 이 도구인가", "대안은 무엇인가" (도구 선택 근거)
prompt-guardrails/	실행 가드레일 — 사전 조건, 단계별 절차, 트러블슈팅
result-templates/	결과 템플릿 — 검증 체크리스트, 실행 결과가 기대와 일치하는지 확인

 

CH02. 환경 구성과 첫 배포

책에서는 gcloud CLI 를 활용하도록 안내되어있지만, 나는 CLI 대신 테라폼 코드를 작성하도록 커스터마이징했다. 
테라폼 코드를 통해 클러스터를 배포할 경우 실습 시작 & 종료 시 리소스 생성 & 제거를 일관성있고 빠르게 진행할 수 있다.

2.1 GCP 계정 생성과 무료 크레딧 활용 전략

https://cloud.google.com/ 에서 무료 크레딧($300)으로 진행하면 된다.

만일 기존에 무료 크레딧을 사용했다면 지메일 계정을 신규 생성해서 무료 크레딧을 받아서 쓰면 된다.

 

2.2 Claude Code 설치 확인

개인적으로 오토모드는 필요할때만 shift + tab으로 모드 전환해서 사용하고 기본적으로는 확인하는 단계가 있는 걸 선호해서 위 명령어는 사용하지 않았다.

curl -fsSL <https://claude.ai/install.sh> | bash   # macOS/Linux
claude --version

# 실습은 승인 없이 자동 진행하는 모드 기준
claude --dangerously-skip-permissions

 

그리고 statusline도 책에 나와있는 방법 대신 https://github.com/jarrodwatts/claude-hud 이 플러그인 사용중인데 개인적으로는 커스터마이징도 잘 되고 해서 토큰/컨텍스트 사용율 모니터링, 현재 사용 모델, To Do List 표시 기능 등을 활성화 해서 잘 쓰고 있다.

 

2.3 gcloud 설정

# 개인 계정으로 gcloud 로그인
gcloud auth login <gmail>

# 실습 프로젝트/리전 설정
gcloud config set project <PROJECT_ID>
gcloud config set compute/zone asia-northeast3-a
gcloud config set compute/region asia-northeast3

 

다음으로는 실습에 필요한 API를 활성화 하면 되는데 Terraform 을 사용할 경우 cloudresourcemaanger API도 활성화 해야한다.

gcloud services enable \
  compute.googleapis.com \
  container.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com   # Terraform provider 프로젝트 검증용

 

나는 기존에도 GCP를 쓰고 있어서 실습 이후에는 기존 계정으로 설정을 원복하기 위해 .claude/settings.local.json 파일에 Session End 훅을 걸어놨다.

{
  "hooks": {
    "SessionEnd": [
      { "hooks": [ { "type": "command",
        "command": "... gcloud config set account <메인계정> ... ; ... gh auth switch --user <메인계정> ..." } ] }
    ]
  }
}

 

2.4 GitHub 저장소 구성

실습 가이드대로 레포를 하나 생성해서 작업을 진행하면 된다.

gh repo create notiflex-platform-test --public --clone

 

CLAUDE.md에는 클로드 코드의 행동 규칙을, JOURNEY.md에서는 실습 체크리스트를 관리하도록 되어있는데 기본 CLAUDE.md에서 내가 추가한 건 아래와 같다.

 

• 리소스 생성·삭제 시 사용자 확인 필수
• 크레덴셜(토큰/키/비밀번호) 하드코딩·프롬프트 출력 금지 — Secret Manager / K8s Secret / GitHub Secrets로만 관리
• Terraform 실행 시 .envrc 활성화를 && 로 한 줄에 같이 실행한다 (셸 상태가 명령 간 유지되지 않기 때문)

그리고 추가로 해당 레포가 어떻게 구성되어있는지 한눈에 보기 위해 링크 처럼 README.md 도 추가했다. 

 

2.5 GKE 클러스터 (Terraform으로 생성)

위에서도 말했듯 나는 gcloud CLI를 쓰지 않고 Terraform 코드를 통해 GKE 클러스터를 배포했다.

 

① State 버킷 부트스트랩: state를 GCS backend에 저장하기 위해, 버킷은 gcloud CLI로 먼저 만들었다.

gcloud storage buckets create gs://<state-bucket> \
  --location=asia-northeast3 \
  --uniform-bucket-level-access \
  --public-access-prevention

gcloud storage buckets update gs://<state-bucket> --versioning

 

② 폴더 구조 (terraform/gcp/gke/)

00-backend.tf      # GCS backend
01-provider.tf     # google provider 버전 고정
02-variables.tf    # project_id, region, zone
03-locals.tf       # gke_definitions map (클러스터 정의)
10-gke.tf          # google_container_cluster + node_pool (for_each)
99-outputs.tf
.terraform-version # tfenv 버전 고정 (1.15.7)
.envrc             # direnv, TF_VAR_* 환경변수

 

③ 리소스 정의: AI 가 코드를 수정할 때 local 변수만 읽고 수정해도 인프라 배포가 가능하도록 locals에 map + for_each 형태로 변수를 선언하는 형태로 작성했다. 전체 코드는 링크 참조.

# 03-locals.tf
locals {
  gke_definitions = {
    notiflex-cluster = {
      az                  = ["asia-northeast3-a"]  # 단일 존 = Zonal
      gateway_api_channel = "CHANNEL_STANDARD"     # 5장에서 사용, 생성 시점에 켬
      node_pools = {
        default-pool = {
          machine_type = "e2-medium"
          node_count   = 2
          disk_size_gb = 30
          spot         = true   # 비용 절감
        }
      }
    }
  }
  common_labels = { project = "notiflex", managed-by = "terraform" }
}

 

④ kubectl 컨텍스트 설정: 이 설정은 실습 가이드를 그대로 적용했다.

gcloud container clusters get-credentials notiflex-cluster --zone=asia-northeast3-a
kubectl config rename-context "$(kubectl config current-context)" gke-sysnet4admin_book_gitaiops

kubectl --context gke-sysnet4admin_book_gitaiops get nodes
kubectl --context gke-sysnet4admin_book_gitaiops get gatewayclass

 

2.6 빌드/배포

① Go 앱 (app/): 가이드 그대로 실행하면 go 파일과 Dockerfile을 생성하게 된다.

• main.go: GET /health(상태), GET /id(인메모리 순차 ID + Pod 이름). Pod 이름은 Downward API로 POD_NAME 주입
• Dockerfile: golang:1.25-alpine 로 빌드 후 scratch 베이스 이미지에 바이너리만 올려 실행하는 멀티 스테이지 빌드
• go.mod: go 1.25

② Artifact Registry: 이것도 Terraform으로 생성했고 확장을 고려해서 for_each map을 이용해서 변수 정의해서 생성하도록 했는데 생성되는 리소스가 1개 앱에 대한 Registry 구성 하나라 뒤에서 추가되는 리소스가 없다면 gke 코드에 합칠 생각이다.

# 03-locals.tf
locals {
  app_definitions = {
    notiflex = { create_registry = true }   # 플래그로 저장소 생성 여부, key를 저장소 이름으로
  }
}

 

③ 이미지 빌드·푸시: Cloud Build를 cli를 통해 실행

gcloud builds submit app/ \
  --tag=asia-northeast3-docker.pkg.dev/<PROJECT_ID>/notiflex/api:v0.1.0

 

④ K8s 매니페스트 (k8s/smb/) — namespace race condition 방지를 위해 namespace를 먼저 적용한다.

kubectl --context gke-sysnet4admin_book_gitaiops apply -f k8s/smb/namespace.yaml
kubectl --context gke-sysnet4admin_book_gitaiops apply -f k8s/smb/
kubectl --context gke-sysnet4admin_book_gitaiops rollout status deployment/notiflex-api -n notiflex

• deployment.yaml: replicas 2, /health readiness/liveness probe, POD_NAME 주입
• service.yaml: ClusterIP, 80 → 8080

⑤ 배포 검증: 아직 cluster IP 서비스밖에 없기 때문에 포트포워딩으로 확인한다.

kubectl --context gke-sysnet4admin_book_gitaiops get pods -n notiflex
kubectl --context gke-sysnet4admin_book_gitaiops port-forward svc/notiflex-api -n notiflex 8080:80 &
curl <http://localhost:8080/health>   # {"status":"ok"}
curl <http://localhost:8080/id>       # {"id":1,"generated_by":"notiflex-api-..."}

 

2.7 첫 커밋

각 장의 결과물을 Git에 커밋한다. 커밋 author는 이 저장소에만 개인 정보로 설정(전역 회사 설정 유지):

git config --local user.name "<개인 이름>"
git config --local user.email "<개인 이메일>"
git add -A && git commit -m "..." && git push origin main

 

GKE Zonal 클러스터는 control plane이 무료이고 비용은 노드(VM)에서만 발생하기 때문에 실습이 끝날 때마다 노드만 0으로 축소하면 비용은 사실상 0이면서 클러스터·배포 설정을 유지할 수 있다.

# 03-locals.tf — node_count만 변경
node_count = 0   # 재개 시 2로 복원