기준 문서

• 103 V1 아키텍쳐 설계
• 101 서버 구성
• docs/103-Milestones-Docker-Compose.md

이 문서는 V1 아키텍처의 결정을 Terraform 등의 IaC 코드에 바로 옮길 수 있도록 리소스, 변수, 권한과 미결정 값을 분리한다. 아직 부하 테스트와 운영 정책으로 확정되지 않은 수치를 확정 사양으로 취급하지 않는다.

아래 값은 V1 Terraform의 기본 입력값으로 사용한다. 실제 값 없이는 정할 수 없는 팀 공인 IP와 도메인만 필수 변수로 남긴다.

단일 AZ이므로 AZ 장애 시 Dev와 Prod가 동시에 영향을 받는다. 이 구성은 환경별 배포와 리소스 경합은 분리하지만 가용 영역 장애를 격리하지는 않는다.

Prod는 80/443을 0.0.0.0/0에 공개하고 SSH 규칙을 생성하지 않는다. Dev의 80/443은 dev_qa_cidrs, 22는 admin_cidrs의 실제 공인 IPv4 /32 목록만 허용한다. 두 목록에는 0.0.0.0/0를 허용하지 않는다. 양쪽 환경의 egress는 tcp/443 -> 0.0.0.0/0 한 개다.

EC2 custom policy는 ECR pull 4개 action, CloudWatch Logs 3개 action과 자기 환경의 S3 backup/deployment prefix 접근만 허용한다. GitHub role trust의 sub에는 실제 FE, BE, AI, CLOUD repository와 branch 또는 GitHub Environment를 입력한다.

배포에는 tag가 아닌 @sha256:<digest>를 사용한다. 질문에서 중복된 ECR 항목은 repository 설정과 EC2의 ECR pull 권한으로 나누어 반영한다.

Secret을 Parameter Store에 둘 경우 경로만 IaC에서 만들고 실제 SecureString 값은 Terraform 밖에서 주입한다. V1 필수 secret은 환경별 MySQL 사용자 비밀번호, MySQL root 비밀번호, JWT secret의 3개이며 Dev/Prod 합계 6개다. AI 활성화 시 환경별 외부 API key를 추가한다.

환경별 alarm 초기값은 다음과 같다.

알람 수신용 SNS topic은 공용 1개를 만들고 실제 구독 이메일 또는 ChatOps endpoint는 별도 입력값으로 받는다.

실제 <domain>, hosted zone ID, dev_qa_cidrs, admin_cidrs, Dev key pair 이름과 알람 구독 대상은 apply 전 필수 입력값이다.

IPv6, ALB, NAT Gateway, RDS, Auto Scaling Group은 V1 범위에 포함하지 않는다.

다음 값은 IaC 골격을 만들기 위한 초기 권장값이다. 특히 인스턴스와 볼륨 크기는 부하 테스트 및 실제 데이터 증가량으로 조정한다.

컨테이너 제한의 합계는 AI를 제외해도 CPU 2.0, 메모리 약 2.125 GiB다. OS, Docker daemon, 로그 수집기, 파일 캐시와 배포 작업의 여유가 필요하므로 Dev는 t3.medium을 시작점으로, Prod는 t3.large를 시작점으로 둔다. 이는 성능 보장값이 아니며 HTTP p95/p99, WebSocket 동시 연결, JVM GC, MySQL buffer와 OOM 발생 여부로 검증해야 한다. FastAPI를 활성화하면 별도 측정 후 인스턴스 타입을 다시 선택한다.

IaC가 직접 컨테이너를 생성하지는 않지만, 인스턴스 크기와 Security Group 검증에는 다음 실행 계약을 사용한다.

/       -> frontend:3000
/api/*  -> backend:8080
/ws/*   -> backend:8080 (WebSocket Upgrade)
/ai/*   -> ai:8000 (선택 기능)

Prod에는 22번 ingress를 만들지 않는다. 운영 접속과 배포는 SSM을 사용한다.

dev_qa_cidrs와 admin_cidrs는 /32 또는 조직의 고정 CIDR만 허용한다. 두 변수에 0.0.0.0/0가 들어오면 plan 단계의 validation으로 실패시킨다.

AWS Security Group의 목적지는 도메인 이름이 아니라 CIDR, Security Group 또는 Prefix List로 표현한다. 따라서 문서의 "외부 전체 또는 허용 도메인" 중 V1 IaC로 직접 구현 가능한 값은 tcp/443 -> 0.0.0.0/0이다. 도메인 단위 egress 통제가 필수라면 HTTP proxy, DNS Firewall, Network Firewall 등의 별도 설계가 필요하며 V1 최소 구성에는 포함하지 않는다.

Project     = moyeota
Environment = dev | prod
ManagedBy   = terraform
Service     = compose-host
Owner       = cloud

1. Docker Engine과 Docker Compose v2 설치
2. SSM Agent와 CloudWatch Agent 설치·활성화
3. data EBS format/mount 및 재부팅 후 자동 mount
4. Docker data-root를 data EBS로 지정
5. /opt/moyeota/{deploy,certs,backup} 생성과 권한 설정
6. /opt/moyeota/deploy/runtime.env와 release.env를 0600으로 관리
7. CloudWatch 로그 전송 설정
8. 배포 스크립트가 사용할 AWS region과 환경명 설정

MySQL named volume을 root EBS가 아니라 별도 data EBS에 보존하려면 Docker의 data-root를 data EBS mount 아래로 이동한다. 이 설정 없이 EC2를 교체하면 named volume도 함께 잃을 수 있다. Prod data volume은 Terraform의 실수로 삭제되지 않도록 별도의 보호 정책과 삭제 전 수동 승인 절차를 둔다.

실제 비밀번호, JWT Secret, 외부 API key, 인증서 private key를 user data, Terraform variable, tfvars, output에 넣지 않는다. IaC는 secret의 경로와 접근 권한만 만들고, 실제 값은 배포 과정에서 별도로 주입한다.

Dev와 Prod role을 분리하고 각 환경의 S3 prefix와 CloudWatch log group만 접근하게 한다.

s3:*, ecr:*, logs:*와 같은 광범위 권한은 사용하지 않는다.

OIDC provider는 https://token.actions.githubusercontent.com, audience는 sts.amazonaws.com을 사용한다. Trust policy의 sub 조건을 조직 전체 wildcard로 두지 않고 실제 repository와 branch 또는 GitHub Environment로 제한한다. Prod role은 GitHub의 Prod Environment 승인 이후에만 assume할 수 있게 분리한다.

이미지는 dev-<sha7>, rc-v<version>-<sha7>, prod-v<version>-<sha7> tag로 push하되 배포 manifest에는 tag가 아닌 @sha256:<digest>를 저장한다. MySQL도 floating tag가 아닌 digest를 사용한다.

버킷 이름은 전역 유일성이 필요하므로 AWS account ID 또는 별도 suffix를 포함한다.

세 버킷 모두 Public Access Block, server-side encryption, versioning을 활성화한다. 사용자 파일 버킷은 public ACL을 사용하지 않고 애플리케이션의 서명 URL 또는 이후 도입할 CloudFront를 통해 제공한다. DB backup과 사용자 파일은 IAM policy에서도 prefix를 분리한다.

/moyeota/dev/nginx
/moyeota/dev/frontend
/moyeota/dev/backend
/moyeota/dev/mysql
/moyeota/dev/ai
/moyeota/prod/nginx
/moyeota/prod/frontend
/moyeota/prod/backend
/moyeota/prod/mysql
/moyeota/prod/ai

IaC는 log group과 retention을 먼저 생성한다. Compose는 서비스별 awslogs driver를 사용하거나 CloudWatch Agent가 Docker log를 서비스별로 구분해 전송하도록 후속 설정이 필요하다. 현재의 로컬 json-file rotation만으로는 EC2 장애 후 로그를 보존할 수 없다.

ALB 없이 EC2 Nginx에서 TLS를 종료하므로 Route 53 record만 만드는 것으로 인증서가 설치되지는 않는다. Certbot/ACME 사용, 외부에서 발급한 인증서 배포, 또는 향후 ALB와 ACM 사용 중 하나를 별도 결정해야 한다. 인증서 private key는 Terraform state에 넣지 않는다.

아래 값은 실제 Secret을 포함하지 않는 root module 입력의 예시다.

project_name = "moyeota"
aws_region   = "ap-northeast-2"

network = {
  vpc_cidr = "10.20.0.0/16"
  prod = {
    subnet_cidr      = "10.20.10.0/24"
    availability_zone = "ap-northeast-2a"
  }
  dev = {
    subnet_cidr      = "10.20.20.0/24"
    availability_zone = "ap-northeast-2a"
  }
}

environments = {
  dev = {
    instance_type        = "t3.medium"
    root_volume_size_gib = 30
    data_volume_size_gib = 30
    log_retention_days   = 14
    backup_retention_days = 7
    public_ingress_cidrs = ["<DEV_QA_PUBLIC_IP>/32"]
    ssh_ingress_cidrs    = ["<ADMIN_PUBLIC_IP>/32"]
    ssh_enabled          = true
  }
  prod = {
    instance_type        = "t3.large"
    root_volume_size_gib = 30
    data_volume_size_gib = 50
    log_retention_days   = 30
    backup_retention_days = 30
    public_ingress_cidrs = ["0.0.0.0/0"]
    ssh_ingress_cidrs    = []
    ssh_enabled          = false
  }
}

ecr_repositories = ["moyeota/nginx", "moyeota/fe", "moyeota/be", "moyeota/ai"]

<DEV_QA_PUBLIC_IP>와 <ADMIN_PUBLIC_IP>는 placeholder이므로 그대로 apply할 수 없게 validation을 추가한다.

infra/
├── bootstrap/       # remote state bucket와 잠금
├── modules/
│   ├── network/
│   ├── compute/
│   ├── iam-ec2/
│   ├── ecr/
│   ├── s3/
│   ├── observability/
│   └── github-oidc/
└── live/
    ├── shared/      # VPC, ECR, OIDC, 공용 bucket
    ├── dev/         # Dev EC2, EIP, SG, IAM, logs
    └── prod/        # Prod EC2, EIP, SG, IAM, logs

Dev와 Prod state를 분리해 Dev 변경이 Prod 리소스를 함께 수정하거나 삭제하는 위험을 줄인다. Prod state, S3 backup bucket과 data EBS에는 삭제 방지와 별도 승인 절차를 둔다.

• AWS account ID와 Terraform 실행 role
• VPC CIDR이 학교·회사·VPN 네트워크와 충돌하지 않는지
• 사용할 Availability Zone
• Dev/QA public CIDR과 운영자 SSH CIDR
• Dev SSH public key 또는 기존 EC2 Key Pair 이름
• 실제 도메인과 Route 53 hosted zone ID
• Nginx TLS 인증서 발급·갱신 방식
• FE, BE, AI, CLOUD의 정확한 GitHub repository 이름과 허용 branch/environment
• 실제 S3 bucket 이름 또는 이름 suffix
• DB backup 주기, RPO, 보존기간과 정기 복구 훈련 절차
• 사용자 파일의 보존·삭제·CORS 정책
• CloudWatch 로그 보존기간과 알람 수신 대상
• Dev/Prod 인스턴스와 data EBS의 최종 용량
• FastAPI 활성화 여부와 활성화 시 CPU·메모리 측정값
• EC2 교체 시 MySQL data volume을 재연결하고 복구하는 runbook

1. terraform fmt, validate와 정적 보안 검사를 통과한다.
2. plan에 NAT Gateway, ALB, RDS, Prod SSH ingress가 없어야 한다.
3. Dev의 80/443/22 source에 0.0.0.0/0가 없어야 한다.
4. Prod에는 80/443 ingress만 있고 운영 접속은 SSM으로 가능해야 한다.
5. EC2에서 ECR pull, S3 backup upload, CloudWatch log 전송이 최소 권한으로 동작한다.
6. 내부 서비스 포트 3000, 8080, 8000, 3306은 호스트나 Security Group에 공개되지 않는다.
7. EC2를 교체해도 별도 data EBS와 S3 backup을 이용해 MySQL을 복구할 수 있어야 한다.
8. Dev와 Prod의 IAM role, S3 prefix, log group, state가 서로 분리되어야 한다.
9. 배포 manifest의 모든 애플리케이션 이미지는 ECR digest를 사용해야 한다.
10. 인스턴스 타입은 실제 부하 테스트 후 확정하고, AI 활성화 시 다시 검증한다.