인프라 전체 가이드 — GCP·Terraform·CI

1. Terraform은 "무엇이 존재하고 누가 권한을 갖는가"를 코드로 선언하는 도구다. CI(GitHub Actions)는 "그 위에 어떤 코드가 돌고 있는가"를 담당한다. 경계 문장: Terraform = 리소스 존재·권한 / CI = 코드 배포. 대체재가 아니라 계층이다.
2. 지금 이 프로젝트의 GCP 리소스는 0개다(API 활성화만 완료). 관리할 것이 없으니 Terraform도 아직 없다 — 대신 도입 트리거 3개를 정해뒀고, 엔진(뉴스 수집) 리소스를 실제로 만드는 M6에서 트리거가 발동해 infra/가 생긴다.
3. GCP 쪽 기본 세팅은 끝나 있다(2026-08-09 실측) — 조직 소속·결제 연결(Blaze)·API 44종, 그리고 개발 머신의 gcloud 로그인·ADC까지(§02·§03·§10). 없는 것은 리소스와 Terraform 코드뿐이다. 킥오프 승인도 2026-08-09 완료 — M6는 착수 가능 상태다.
4. 그전까지는 runbook 방식이다 — 인프라 명령을 실행하면 docs/spec/deploy.md에 손으로 기록해 재현성을 확보한다.

이 문서의 시제 표기 규칙 — 지금 있음 은 레포·GCP에 실재하는 것, M6 예정 은 계획만 확정된 것. 신입이 가장 흔히 하는 오해가 "계획 문서에 있으니 이미 있겠지"다.

GCP의 권한과 비용은 계층을 따라 흐른다: 조직 → 프로젝트 → 리소스. 이 프로젝트의 현재 위치(2026-08-09 실측):

비용 지도 — 어디서 돈이 나가나

"로그인"이 하나가 아니라는 것이 GCP 인증의 첫 관문이다. 터미널에서 gcloud 명령을 칠 때의 자격과, 같은 머신에서 Terraform이나 파이썬 라이브러리가 API를 부를 때의 자격 (ADC)은 별개 파일이다. 그리고 CI와 배포된 서비스는 아예 다른 방식 — 키 없는 토큰 교환(WIF)과 서비스 계정(SA) — 을 쓴다.

2026-08-07, 이 프로젝트에서 실제로 있었던 일이다. ADR-0005가 요구하는 GCP API 6종(run·sqladmin·cloudscheduler·secretmanager·artifactregistry·aiplatform)을 gcloud services enable로 켰다. 결과를 세어 보니 활성 API가 37종에서 44종이 됐다 — 요청은 6개인데 7개가 늘었다. containerregistry가 다른 API의 자동 의존으로 함께 켜진 것이다. 우리가 요청한 적 없는 변화가 프로젝트에 남았고, 이 사실은 담당자가 눈치채고 문서에 적어뒀기 때문에 아는 것이지, 시스템 어디에도 "의도한 상태"와 "실제 상태"의 대조표는 없다.

이것이 수동 인프라 관리의 본질적 한계다. 콘솔 클릭과 CLI 명령은 절차만 남기고 결과의 전모는 남기지 않는다. 지금 이 프로젝트에 정확히 뭐가 켜져 있는지 아는 방법은 콘솔을 열어 눈으로 확인하는 것뿐이다.

IaC(Infrastructure as Code)는 이 문제를 뒤집는다. "API 6종이 켜져 있어야 한다", "큐가 1개 있고 초당 1건만 내보내야 한다"처럼 원하는 최종 상태를 코드 파일로 선언하면, 도구(Terraform)가 현실과 비교해서 모자란 것은 만들고 남는 것은 알려준다. 코드니까 리뷰를 거치고, 이력이 남고, 다시 실행하면 같은 결과가 나온다(멱등성).

건물 관리에 비유하면

Terraform은 건물·전기·출입권한을 관리하는 시설팀이다. "이 건물에 사무실이 4칸 있고, 택배기사는 로비까지만 들어올 수 있다"는 설계도(.tf 코드)를 유지한다. 입주자가 들여놓는 가구(애플리케이션 코드)는 시설팀 소관이 아니다 — 그건 CI가 나른다. 그리고 시설팀에는 자산 대장이 있어서, 대장에 없는 물건이 건물에 나타나면(drift) 다음 점검 때 드러난다.

신입이 가장 먼저 부딪히는 혼란이 이것이다. 배포 자동화(CI)가 이미 있는데 Terraform은 뭘 더 해주나? 원 설계 문서의 표현을 그대로 빌리면 — "대체재가 아니라 계층입니다. CI가 Terraform을 실행합니다." 건물 비유로: 시설팀(Terraform)과 이삿짐 운송(CI)은 둘 다 "건물에서 일하는" 주체지만 하는 일이 겹치지 않고, 이사 트럭이 들어오려면 시설팀이 만들어 둔 출입구와 권한이 먼저 있어야 한다.

아래 그림이 이 문서의 중심이다. 박스의 테두리 색이 "껍데기를 누가 만드나"를, 박스 안의 색 칩이 "내용물을 누가 채우나"를 나타낸다. 왼쪽 JP 트랙은 runbook(수기 gcloud)으로 만들고, 오른쪽 엔진 트랙은 M6부터 Terraform이 만든다 — 한 프로젝트 안에 두 관리 방식이 나란히 놓인, 이 레포만의 과도기 그림이다.

관리 주체 4분면 — 표로 다시 보기

GCP 프로젝트 안에는 무엇이 있나 — 정의 · 역할 · AWS 대응

관리 주체는 위 표의 넷(Terraform · CI · 앱 데이터 · 콘솔)이 전부고, 여기서는 그 관리 대상 — 그림 ①의 GCP 프로젝트 프레임 안에 있는 것들 — 을 하나씩 본다. 각 이름이 무엇이고 이 구성에서 무슨 일을 하는지, 그리고 AWS를 먼저 배운 사람을 위해 같은 자리를 메우는 AWS 제품을 함께 적는다.

그 위에서 도는 프로그램 넷 — worker · api · backfill · admin-web

앞의 표가 GCP가 파는 제품이었다면, 이 넷은 우리가 만든 프로그램이다. AWS 대응이 없는 것이 당연하다 — 클라우드를 옮겨도 이름은 그대로고 밑에 깔리는 런타임만 바뀐다. 그림 ①에서 파란 테두리 + 초록 칩으로 그려진 박스들이 정확히 이 넷이다: 껍데기(Cloud Run 서비스·잡이 존재한다는 사실과 권한)는 Terraform, 그 안에 들어가는 내용물(이미지 태그)은 CI가 관리한다. 넷 다 엔진 트랙(서울)이고 M6 생성 예정이다.

경계가 "Terraform=껍데기 / CI=내용물"로 나뉘면 필연적으로 충돌 지점이 하나 생긴다. Terraform으로 Cloud Run을 만들려면 image 필드를 채워야 하는데, 바로 그 필드를 CI가 배포 때마다 계속 바꾼다. 그러면 다음 plan은 "코드에 적힌 값과 다르네?" 하며 이미지를 옛 값으로 되돌리려 든다. 건물 비유로: 시설팀이 도면대로 원상복구를 하다가 입주자가 새로 들인 가구를 옛 가구로 바꿔놓는 사고다.

해법은 "이 필드는 Terraform이 못 본 척해라"를 선언하는 것이다. 이 문서에서 유일한 코드 조각:

resource "google_cloud_run_v2_service" "worker" {
  name     = "worker"
  location = var.region

  template {
    containers {
      image = "asia-northeast3-docker.pkg.dev/${var.project}/news/worker:bootstrap"
    }
  }

  lifecycle {
    ignore_changes = [template[0].containers[0].image]
  }
}

"좋은 도구면 처음부터 쓰지, 왜 미뤘나?"는 정당한 질문이다. 팀의 답(ADR-0007 Decision 8): 현재 배포 산출물이 0인 단계에서 Terraform을 들이면 얻는 것 없이 state·backend 관리 비용만 추가된다. 도구는 문제가 생기는 시점에 들인다 — 단, "그 시점"을 감으로 정하지 않도록 트리거를 문서로 박아뒀다. 하나라도 충족되면 도입한다:

결정 이력 — 어떻게 여기까지 왔나

M6에서 레포에 생기는 것:

• infra/modules/ — 반복되는 리소스 묶음(module)
• infra/envs/prod/ — 환경별 값. 지금은 prod 한 벌뿐(트리거 (c) 미발동이므로 dev를 미리 만들지 않는다)
• .github/workflows/engine-infra.yml — 인프라 레인(plan → PR 코멘트 → 승인 → apply)
• .github/workflows/deploy.yml — 앱 레인(빌드 → push → deploy)

state는 GCS 버킷 conket-tfstate에 원격 저장한다(backend). 이유는 한 문장이다 — "로컬 state는 2명 이상이 만지는 순간 충돌한다." GitHub Actions가 GCP 권한을 얻는 방식은 WIF로, SA 키 파일을 레포나 시크릿에 두지 않는다.

연동이 제대로 됐는지 30초 검증 — 셋 다 통과해야 한다:

• gcloud services list --enabled | wc -l → 44 (runbook 기록과 일치)
• gcloud sql instances list → 0건 (리소스는 아직 없어야 정상 — 있으면 누가 만들었는지부터 확인)
• 로컬 DB의 engine.sources에 epnc 시드 1행, enabled=false

참고 — 리소스를 실제로 만드는 명령은 킥오프 승인(2026-08-09) 완료로 이제 가능하다. 실행하면 docs/spec/deploy.md runbook에 기록하는 것이 팀 규칙이다.

셀프체크 — 이 변경은 누구 소관인가?

각 상황을 읽고 4분면 중 하나를 고른 뒤 펼쳐서 확인.