infra · app · ai
코드가 main에 들어간 뒤 dev를 거쳐 prod에 올라가기까지의 경로와, 그 과정에서 GitHub Actions가 AWS에 들어가는 방법(OIDC)을 2026-10-01 실제 배포 기록으로 정리했다.
원칙은 하나다. prod에서는 빌드하지 않는다. dev 배포가 만든 산출물(이미지, FE tar)을 SHA로 골라 그대로 prod에 올린다.
be/**·fe/** 변경 시papertutor-fe-artifactsfe/<sha>.tar.gz왼쪽은 자동, 오른쪽은 사람이 버튼을 누른다. 가운데 보관소가 두 세계를 잇는다.
레포 세 곳에 워크플로가 하나씩 있다. main에 push되면 돌고, 끝나면 그 커밋 SHA 이름으로 산출물이 남는다.
be/** 변경 시papertutor-dev-app-deployfe/** 변경 시dist/papertutor-dev-ai-deploy왜 tar를 따로 보관하나. BE·AI는 ECR에 이미지가 남지만 FE는 S3에 파일을 뿌리고 끝이라 "그때 빌드한 결과"가 남지 않았다. prod가 재빌드 없이 같은 것을 쓰려면 보관소가 필요했다. (YMC-399)
infra 레포 Actions의 Deploy prod를 main 브랜치에서 실행한다. 입력은 세 개, 전부 선택이다. 채운 것만 배포하고 순서는 항상 AI → BE → FE다. 승인 단계는 없다. 실행하는 사람이 승인자다.
| job | 하는 일 | 건너뛰는 조건 |
|---|---|---|
| verify | 입력한 SHA의 이미지(dev ECR)·tar(산출물 버킷)가 실제로 있는지 확인. 하나라도 없으면 여기서 끝. | — |
| ai-image | dev ECR → prod ECR 복사 (docker pull·tag·push, ARM runner). 이미 있으면 복사 생략. | ai_sha 비움 |
| deploy-ai ×3 | 서비스 3개에 동시에 새 revision 배포, 안정화 대기. | 같음 |
| be-image / deploy-be | 위와 같은 방식, backend 1개. | be_sha 비움, 또는 AI 실패 |
| deploy-fe | tar 다운로드 → asset sync → index.html 마지막에 교체 → CloudFront 무효화. | fe_sha 비움, 또는 앞 단계 실패 |
총 19분. 막대 길이는 실제 소요 시간에 비례한다.
시간의 대부분은 ECS 안정화 대기다. 새 태스크가 뜨고 헬스체크를 통과할 때까지 워크플로가 기다린다. 워크플로가 느린 게 아니라 ECS 설정(헬스체크 간격, 최소 healthy 비율)의 영역이다.
전용 워크플로가 없다. 같은 워크플로에 이전 SHA를 넣으면 된다. 이미지가 prod ECR에 이미 있으면 복사를 건너뛰고 revision만 새로 등록한다. BE는 Flyway가 기동 시 돌기 때문에 마이그레이션이 expand/contract를 지켰을 때만 되돌릴 수 있다.
워크플로는 GitHub 서버에서 돌면서 AWS의 ECR·ECS·S3를 조작해야 한다. 예전 방식은 AWS 액세스 키를 발급해 GitHub Secrets에 넣는 것인데, 영구 비밀번호라 유출되면 끝이고 주기적으로 바꿔야 한다. OIDC는 저장된 비밀번호 없이 매 실행마다 임시 자격을 받는 방식이다.
아래 단계를 누르면 그림의 해당 화살표가 강조된다.
permissions: id-token: write가 이 요청을 허용한다.repo:team-ymc/infra:ref:refs/heads/main에서 왔다"가 적혀 있고 GitHub의 서명이 붙어 있다. 위조하면 서명이 깨진다.aws-actions/configure-aws-credentials가 토큰과 Role ARN을 STS에 보낸다.| Role | 맡을 수 있는 곳 | 할 수 있는 것 |
|---|---|---|
| papertutor-dev-app-deploy | team-ymc/app main | dev ECR backend 쓰기, dev BE 배포, dev FE 버킷, 산출물 버킷 fe/* 쓰기 |
| papertutor-dev-ai-deploy | team-ymc/ai main | dev ECR ai 쓰기, dev AI 서비스 3개 배포 |
| papertutor-prod-deploy | team-ymc/infra main | dev ECR 읽기, prod ECR 쓰기, prod ECS 4개 갱신, PassRole, 산출물 버킷 읽기, prod FE 버킷, CloudFront 무효화 |
왜 prod Role을 infra 레포에 묶었나. app·ai 레포 코드가 아무리 바뀌어도 prod에는 손댈 수 없다. prod를 바꾸는 건 infra main에서 사람이 실행한 워크플로뿐이다.
Terraform은 "이런 자원이 있어야 한다"는 코드와, "내가 만든 자원이 AWS에서 어떤 ID를 가졌나"를 적은 장부(state)로 동작한다. 코드에 있고 장부에 없으면 만들고, 코드에 없고 장부에 있으면 지운다. 이 마지막 줄이 위험한 지점이다.
infra에는 묶음(root)이 세 개 있다. OIDC provider는 원래 dev 묶음에 있었는데, prod도 같은 provider가 필요해서 공용 자리인 bootstrap으로 옮겼다.
papertutor/dev/…papertutor/prod/…코드에서 provider 블록을 dev에서 빼고 bootstrap에 넣은 뒤 그냥 apply하면, dev는 "코드에 없다"며 provider를 지우고 bootstrap은 "새로 만든다"며 실패한다. 그 순간 dev 배포가 끊긴다. 그래서 장부만 직접 고쳤다.
| 순서 | 명령 | 기대 결과 |
|---|---|---|
| 1 | bootstrap: terraform import | bootstrap 장부에 기존 provider 등록. AWS 변화 없음 |
| 2 | bootstrap: terraform plan | 태그만 1건 변경 (dev 태그 → bootstrap 태그) |
| 3 | dev: terraform state rm | dev 장부에서 기록만 삭제. AWS 변화 없음 |
| 4 | dev: terraform plan | No changes |
| 5 | bootstrap: terraform apply | 태그 갱신 |
| 6 | prod: terraform apply | Role·정책 2개 추가, 기존 자원 변경 없음 |
import를 먼저 하는 이유는 "어느 장부에도 없는 순간"을 만들지 않기 위해서다. 잠깐 두 장부에 같이 있는 건 안전하지만, 어디에도 없으면 실수로 apply했을 때 새로 만들려다 실패한다.
산출물 이름은 main에 push된 커밋의 SHA다. 우리는 PR을 merge 커밋으로 합치기 때문에, 파일을 실제로 고친 커밋과 main에 push된 커밋이 다르다.
git log -1 -- fe/는 왼쪽 위 커밋을 돌려주고, 그 이름의 tar는 없다. 그래서 runbook은 git 명령 대신 app·ai 레포 Actions의 dev 배포 실행 이력에서 성공한 실행의 커밋을 고르라고 안내한다. 산출물 버킷의 tar 이름이나 dev ECR 태그를 직접 봐도 같은 답이다. 없는 SHA를 넣어도 verify가 걸러 준다.
첫 시나리오로 FE만 최신(10060c3)으로 올렸더니 실패한 논문에 재시도 버튼이 없었다.
버그가 아니라 세대 불일치다. BE·FE는 API 응답 필드를 같이 바꾸는 일이 많으니 같은 SHA로 함께 올리는 것을 기본으로 runbook에 적었다.
| 대상 | 어디서 | 지금 값 |
|---|---|---|
| BE·AI | ECS 서비스 → task definition → 이미지 태그 | BE 10060c3 · AI 94b5037 |
| FE | S3에는 SHA가 안 남는다. infra Actions의 Deploy prod summary가 기록 | 10060c3 |