aws로 실시간 온라인 보드게임(da vinci coda) 배포하기 (1)
사이드 프로젝트로 da vinci coda라는 멀티플레이어 웹 보드게임을 만들었는데, 이 프로젝트를 CI/CD 파이프라인을 포함하여 배포하기로 했다.
들어가기에 앞서 프로젝트 리포지토리에 대한 배경을 먼저 설명해야할 것 같은데 이 사이드 프로젝트는 하나의 리포지토리에 Client와 Server 애플리케이션이 모두 담겨있는 monorepo 이다.
해당 프로젝트의 Client는 React + Vite + Three.js로 개발했고, Server는 Express + Socket.io로 개발했다. 또한 Client, Server가 패키지로 코드를 공통으로 사용하고 있는 부분이 하나의 리포지토리에 모두 들어가 있다.
이러한 배경 때문에 처음에는 Nx나 turborepo로 선택적 빌드/배포를 하고, GitHub Actions로 CI/CD를 하고자 했지만, 애플리케이션이 2개 밖에 없는데 Nx나 turborepo를 활용하는 것은 오버스펙인 것 같아 GitHub Actions path filter를 활용하기로 했다.
Client는 S3에 CloudFront를 연동해 배포하고, Server(백엔드)는 AWS Systems Manager(SSM) Run Command를 사용해 EC2 t4g.small 인스턴스에 배포하기로 했다.
AWS Fargate로 scaling이 가능하게 구축하고 싶었지만, 어차피 트래픽이 몰려서 인스턴스가 늘어났을 때 감당할 돈이 없기에 사용하지 않기로 했다.
GitHub Actions을 위한 YAML 파일을 작성하기 전에 아래와 같은 작업을 순차적으로 거쳐야한다.
- AWS Route 53 도메인 구입
- AWS S3 버킷 생성
- CloudFront 배포 생성
- ECR private registry 생성
- AWS EC2 인스턴스 생성
- 탄력적 IP 할당
- IAM 정책 설정
- IAM 사용자 설정
- Route 53 Subdomain 등록
- Route 53 도메인에 CloudFront 연결
- GitHub Secrets 추가
먼저 frontend(client)에 쉽게 접근할 수 있도록 도메인을 구입해야한다.
Porkbun 같은 외부 레지스트라에서 도메인을 구입하고 Route 53에 연결하면 4 정도 더 저렴해서 그렇게 할까 고민해보았지만 결론부터 말하면 Route 53에서 도메인을 구입했다.
외부에서 도메인을 구입하면 도메인 등록 완료까지 걸리는 시간도 Route 53보다 오래걸리고, 자잘한 설정을 추가로 하는 과정을 거치는게 귀찮았다. Route 53에서 도메인을 구입하면 별도의 네임서버 변경 과정 없이 자동으로 연결되고, AWS 콘솔에서 관리 가능하다는 점에서 매우 편리하다. 역시 돈이 최고야
도메인 등록 과정은 어렵지 않아서 소개를 생략한다.
보통 DNS 등록까지 30분 ~ 60분 소요된다고 하는데, 도메인 구입 후 DNS 등록까지 12분 밖에 소요되지 않았다.
콘솔에서 배포하고자하는 리전을 선택하고 S3 페이지에 접속한다. "버킷 만들기"를 선택한다.
버킷 이름(YOUR_BUCKET_NAME)을 정한다. 추후에 IAM 권한 정책 설정할 때 필요하니 메모해둔다.
CloudFront를 통해서만 접근하도록 설정할 것이기 때문에 초기 설정값인 "모든 퍼블릭 액세스 차단"을 그대로 유지해줬다.
스크롤을 내려 하단의 "버킷 만들기"를 클릭해준다.
CloudFront는 AWS에서 CDN을 편리하게 제공하는 서비스라고 생각하면 된다. CloudFront를 사용하면 S3 버킷을 public에 노출하지 않아도 되므로 보안적으로 더 좋다.
다음으로 CloudFront 배포 생성을 진행해야한다.
Distribution name(YOUR_DISTRIBUTION_ID)을 정한다. 추후에 IAM 권한 정책 설정할 때 필요하니 메모해둔다.
앞서 Route 53에서 도메인을 구입했으므로 구입한 도메인 주소를 입력하고 체크한다. Route 53을 통해 구입하면 CloudFront에서 자동으로 DNS를 관리해준다.
만약 외부에서 도메인을 구입했다면 넘어가고 나중에 설정해야 한다.
"Next"를 눌러준다.
S3 버킷을 원본으로 연결해야하니 Origin type를 "Amazon S3"로 선택하고, "Browse S3"를 눌러서 사용할 S3 버킷을 선택해준다.
나머지 설정은 그대로 유지하고 "Next"를 눌러준다.
Web Application Firewall (WAF)는 SQL 인젝션, XSS(크로스 사이트 스크립팅) 등 일반적인 웹 공격을 막아주는 훌륭한 보안 서비스이지만, 1천만 건당 $14 가량 과금되기 때문에 세팅 단계에서는 "보안 보호 비활성화"를 누르고 넘어가도 된다.
WAF는 나중에 서비스가 안정화되고 실제 트래픽이 발생할 때 언제든지 추가할 수 있다.
CloudFront를 처음 세팅하면 다음과 같은 에러를 마주하게 될 것이다.
CloudFront는 전 세게 엣지 로케이션에서 작동하는 글로벌 서비스이기 때문에, SSL 인증서(AWS Certificate Manager, ACM)는 반드시 us-east-1 region에 생성되어 있어야 한다.
"Create certificate in ACM" 링크를 클릭하여 AWS Certificate Manager(ACM)를 새 탭으로 열고 설정하는데,
그냥 "Create certificate"를 누르면 된다.
certificate 생성이 완료된 것을 확인하고 "Next"를 눌러 다음으로 넘어간다.
설정이 이루어졌는지 다시 한 번 확인하고 "Create distribution"을 눌러준다.
추후에 IAM 정책 연결할 때 필요하므로 화면에 표시된 distribution ID를 복사한다.
배포를 진행하면서 많은 troubleshooting이 있었지만 이건 특히 헷갈려서 따로 부제목을 지어놨다.
모든 설정을 마치고 frontend 배포를 완료한 뒤 도메인주소로 접속했는데 AccessDenied 에러가 발생했다.
처음에는 Origin Access Control(OAC) 정책을 S3 버킷에 추가하지 않아서 발생한 문제인줄 알았다.
CloudFront의 Origin(원본)에 들어가보니 파란 박스에 위와 같은 설명이 있었기 때문..
"이 정책 설명을 사용하여 CloudFront에 대한 액세스를 허용해야 합니다. S3 버킷에 액세스할 수 있는 CloudFront 권한 부여에 대해 자세히 알아보세요."
그래서 배포에 쓰이는 S3 버킷에서 "권한"을 누르고 스크롤을 내려보았는데, 이미 정책이 잘 기입되어 있었다.
사실 위의 과정과 동일한 CloudFront 설정을 했다면 S3 버킷에 자동으로 OAC에 대한 정책이 추가되는 것이 정상이다.
그런데 또다른 파란 박스가 나를 헷갈리게 한다.
"이 버킷에 대해 퍼블릭 액세스 차단 설정이 활성화되어 있기 때문에 퍼블릭 액세스가 차단됩니다. 활성화된 설정을 확인하려면 이 버킷의 퍼블릭 액세스 차단 설정을 확인하세요. Amazon S3 퍼블릭 액세스 차단 사용에 대해 자세히 알아보기"
그래서 나는 순간 모든 퍼블릭 액세스를 차단한게 문제였나? CloudFronte OAC를 활용해도 마지막 옵션은 차단을 해제해주어야하나? 싶었다.
하지만 결론부터 말하면 CloudFront OAC를 사용할 때는 S3 퍼블릭 액세스 차단은 활성화되어 있어도 된다.
오히려 권장되는 설정이다.
그럼 무엇이 문제였나?
바로 기본 루트 객체(Default root object)를 설정해주지 않았다는 점이다.
처음 CloudFront 설정을 보면 기본 루트 객체가 비어있을텐데 명시적으로 "index.html"을 추가해주어야 CloudFront가 S3 버킷의 루트에서 index.html 파일을 찾아 사용자에게 반환할 수 있다.
frontend 배포를 위한 정적 파일이 업로드된 S3 버킷을 보면 루트 경로에 폴더 2개와 index.html 파일이 있는 것을 확인할 수 있는데, 다른 폴더가 있어서 index.html을 반환하지 못했던 것으로 보인다.
CloudFront가 루트 경로(/)로 접근했을 때 어떤 파일을 보여줄지 몰라서 S3에 직접 접근하려 했고, 그 과정에서 403 에러가 발생한 것이다.
GitHub Actions에서 server에 대한 docker image를 build하면 해당 docker image를 저장할 docker 이미지 저장소가 필요하다. 저장소에 push를 하면 SSM으로 EC2 instance가 저장소에 있는 docker image를 pull 하고 실행하도록 하여 server에 대한 배포가 이루어지게 된다.
이를 위해 AWS ECR(Amazon Elastic Container Registry)를 사용하거나, Docker Hub를 사용하는 등의 옵션이 있다. 이번 배포는 ECR를 사용하기로 했다. 같은 리전에 있어 빠르다는 장점이 있고, 프리티어는 프라이빗 리포지토리에 대해 월 500MB까지 1년간 무료로 사용할 수 있다.
aws 콘솔 창에 ECR를 검색해서 Amazon ECR - 프라이빗 레지스트리 - 리포지토리(ECR - Private registry - Repositories)에 들어간다.
"리포지토리 생성"을 누른다.
리포지토리 이름을 짓고, "생성"을 누른다.
복잡한 프로젝트가 아니라면 굳이 namespace까지 지정할 필요 없이 repo-name만 지으면 된다.
"인스턴스 시작"을 눌러준다.
"이름 및 태그"에서 인스턴스 이름을 지어준다.
특이사항 : T4g 인스턴스를 활용할 예정이기 때문에 ARM64 아키텍처를 선택해야한다.
이번 배포에서는 CI/CD에 AWS Systems Manager(SSM)을 사용할 것이므로 SSM Agent가 기본적으로 설치되어 있고 활성화 상태로 부팅되는 Amazon Linux를 Amazon Machine Image(AMI)로 선택했다.
인스턴스 유형으로 t4g.small을 선택해준다.
인스턴스는 각자의 사정에 맞게 선택하면 된다.
SSH 연결에 쓰이는 키 페어를 선택해야하는데, 만약 키 페어가 없거나 새로운 키 페어를 사용하고 싶다면 "새 키 페어 생성"을 누르고 만들면 된다.
키 페어 이름을 입력하고 "키 페어 생성"을 누른다.
키 페어 유형은 RSA, ED25519 중 아무것이나 선택해도 되고, 키 파일 형식은 보통 OpenSSH를 사용하므로 .pem으로 진행하면 된다.
GitHub Actions로 CI/CD를 구축할 때 SSH_PRIVATE_KEY를 등록하고 EC2에 SSH로 직접 접속하여 배포하도록 하는 방법이 있고, SSM을 사용해서 배포를 진행하는 방법이 있는데, 이번에는 후자의 방식을 사용하므로 "다음에서 SSH 트래픽 허용"이 체크되어있는 것을 비활성화 한다.
OS, 애플리케이션, 의존성 설치 및 로그 저장까지 고려한다면, 최소 20~30GiB는 사용하는 것이 바람직하다.
물론 어떤 서비스이냐와 서비스 규모에 따라 다르지만, 이번 사이트 프로젝트는 이정도면 충분할 것 같다.
고급 세부 정보를 열어준다.
SSM을 사용하려면 GitHub Actions IAM 사용자뿐만 아니라 EC2 인스턴스 자체에도 SSM 권한이 필요하다.
AmazonSSMManagedInstanceCore 정책이 포함된 IAM 역할을 생성하여 인스턴스에 연결해야한다.
"새 IAM 프로파일 생성"을 클릭한다.
"역할 생성"을 누른다.
EC2를 선택하고 넘어간다.
AmazonSSMManagedInstanceCore 정책을 검색하고 선택한 뒤 넘어간다.
역할 이름을 짓고 "역할 생성"을 누른다.
역할 생성이 완료되었으면 다시 인스턴스 설정하던 페이지로 돌아와 방금 만든 역할 이름을 검색해 선택한다.
완료되었으면 "인스턴스 시작"을 누른다.
인스턴스 시작이 잘 이루어졌음을 확인할 수 있다.
추후에 IAM 정책 연결할 때 필요하므로 화면에 표시된 인스턴스 ID를 복사한다.
인스턴스에 벡엔드 서버를 띄울 것이므로 서버가 listening하고 있을 포트를 열어주어야 외부에서 오는 요청을 인스턴스에 있는 서버가 받아들일 수 있다.
포트를 여는 것은 인바운드 규칙 편집으로 가능하다.
궁금하다면 아래 링크에 있는 게시글 참고 바란다.
탄력적 IP를 할당하지 않으면, EC2 인스턴스는 동적 IP를 가지게 된다. 이 IP는 인스턴스를 중지했다가 다시 시작할 때마다 변경된다.
클라이언트(사용자)는 my-domain.com같은 도메인 주소로 접속하게 되는데, 이 도메인은 서버의 IP 주소를 가리켜야 한다. (DNS A record)
IP가 바뀌면 DNS에 설정된 IP주소(이전 IP)가 실제 서버의 IP(새 IP)와 달라져 사용자가 서버에 접속할 수 없게 된다.
SSM을 활용해 배포하기에 배포 자체에는 탄력적 IP가 필수는 아니지만, 위의 이유로 EIP를 할당하는 것이 좋다.
EC2 - 네트워크 및 보안 - 탄력적 IP를 클릭한다.
"탄력적 IP 주소 할당"을 클릭한다.
"할당"을 클릭한다.
방금 생성한 "할당된 IPv4 주소"를 클릭한다.
"탄력적 IP 주소 연결"을 클릭한다.
직전에 생성한 인스턴스와 연결하고, 이어서 프라이빗 IP 주소를 선택한다.
"연결"을 클릭한다.
탄력적 IP에 인스턴스 연결이 잘 되었음을 확인할 수 있다.
CI/CD과정에서 GitHub Actions가 AWS 리소스를 조작할 수 있도록 전용 IAM 사용자를 생성해야 한다.
IAM 사용자를 생성하기 전에, 정책을 생성해야한다.
"AWS 관리형 정책"을 선택해도 되지만, 보안을 생각하면 커스텀이 가능한 "고객 관리형 정책"을 선택하는 것이 좋다.
"정책 생성"을 클릭한다.
"JSON"을 누르고 아래 코드를 복사해 입력한다.
아래 요소는 대치해서 넣어주어야 한다. 입력을 완료했으면 우측 하단의 "다음"을 클릭한다.
- YOUR_BUCKET_NAME : S3 버킷 이름
- YOUR_AWS_ACCOUNT_ID : aws 계정 ID (콘솔 우측 상단에 12자리 숫자로 되어있다)
- YOUR_DISTRIBUTION_ID : CloudFront의 distribution ID
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "S3ListAndSync",
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
},
{
"Sid": "S3ObjectAccess",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
},
{
"Sid": "CloudFrontInvalidation",
"Effect": "Allow",
"Action": "cloudfront:CreateInvalidation",
"Resource": "arn:aws:cloudfront::YOUR_AWS_ACCOUNT_ID:distribution/YOUR_DISTRIBUTION_ID"
}
]
}이 정책은 GitHub Actions가 React 클라이언트 앱을 S3에 업로드하고 CloudFront 캐시를 갱신하는 데 필요한 권한만 허용한다.
정책 이름을 짓고 "정책 생성"을 클릭한다.
정책이 잘 생성되었음을 확인할 수 있다.
같은 방법으로 아래 JSON 코드를 복사해 정책을 하나 더 생성한다.
- YOUR_REGION : region명 (ex. ap-northeast-2)
- YOUR_INSTANCE_ID : 배포하고자하는 인스턴스 ID
- YOUR_AWS_ACCOUNT_ID : aws 계정 ID (콘솔 우측 상단에 12자리 숫자로 되어있다)
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSSMRunCommand",
"Effect": "Allow",
"Action": "ssm:SendCommand",
"Resource": [
"arn:aws:ec2:YOUR_REGION:YOUR_AWS_ACCOUNT_ID:instance/YOUR_INSTANCE_ID",
"arn:aws:ssm:YOUR_REGION:*:document/AWS-RunShellScript"
]
},
{
"Sid": "AllowSSMCommandTracking",
"Effect": "Allow",
"Action": [
"ssm:GetCommandInvocation"
],
"Resource": "*"
}
]
}목적 : GitHub Actions IAM User용 (ECR에 빌드된 docker image를 push 할 수 있게 한다)
정책 이름 : github-actions-ecr-push-policy
- YOUR_REGION : region명 (ex. ap-northeast-2)
- YOUR_AWS_ACCOUNT_ID : aws 계정 ID (콘솔 우측 상단에 12자리 숫자로 되어있다)
- YOUR_REPOSITORY_NAME : ECR 프라이빗 리포지토리 이름
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ECRPushAccess",
"Effect": "Allow",
"Action": [
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:PutImage",
"ecr:InitiateLayerUpload",
"ecr:UploadLayerPart",
"ecr:CompleteLayerUpload"
],
"Resource": "arn:aws:ecr:YOUR_REGION:YOUR_AWS_ACCOUNT_ID:repository/YOUR_REPOSITORY_NAME"
},
{
"Sid": "ECRAuthToken",
"Effect": "Allow",
"Action": "ecr:GetAuthorizationToken",
"Resource": "*"
}
]
}목적 : EC2에서 SSM으로 ECR pull 하도록 명령을 받았을 때 수행할 수 있는 권한 부여
해당 정책은 생성 후 이전에 생성한 ec2 IAM 인스턴스 프로파일에 추가해준다.
정책 이름 : ec2-ecr-pull-policy
- YOUR_REGION : region명 (ex. ap-northeast-2)
- YOUR_AWS_ACCOUNT_ID : aws 계정 ID (콘솔 우측 상단에 12자리 숫자로 되어있다)
- YOUR_REPOSITORY_NAME : ECR 프라이빗 리포지토리 이름
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ECRPullAccess",
"Effect": "Allow",
"Action": [
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage"
],
"Resource": "arn:aws:ecr:YOUR_REGION:YOUR_AWS_ACCOUNT_ID:repository/YOUR_REPOSITORY_NAME"
},
{
"Sid": "ECRAuthToken",
"Effect": "Allow",
"Action": "ecr:GetAuthorizationToken",
"Resource": "*"
}
]
}
"사용자 생성" 클릭
사용자 이름을 짓고 "다음"을 클릭한다.
사이드 프로젝트의 CI/CD용이라 여러 사람에게 접근권한을 줄 필요는 없으므로 "그룹에 사용자 추가" 대신 "직접 정책 연결"을 클릭한다.
직전에 생성한 권한 고객 관리형 정책을 3개 추가하고 "다음"을 클릭한다. (스크린샷에 없는 github-actions-ecr-push-policy 도 추가하세요.)
잘 추가되었는지 확인하고 "사용자 생성"을 클릭한다.
사용자가 잘 생성된 것을 확인할 수 있다.
해당 페이지에서만 암호를 확인할 수 있으므로 콘솔 로그인 URL과 콘솔 암호를 반드시 복사해놓자!
이제 액세스 키를 만들어야한다. 사용자 이름을 클릭하고 "액세스 키 만들기"를 클릭한다.
"AWS 외부에서 실행되는 애플리케인션"을 선택하고 "다음"을 클릭한다.
설명 태그는 선택적으로 넘어가도 좋다. 물론 어떤 용도인지 적어두면 나중에 무슨 용도로 만든 키인지 까먹었을 때 상기에 도움이 된다.
"액세스 키 만들기"를 클릭한다.
액세스 키와 비밀 액세스 키를 복사한다.
비밀 액세스 키는 여기서만 확인가능하니 반드시 기록해두어야한다.
Route 53에 api.를 subdomain으로 추가하고 EC2의 public IP(탄력적 IP)를 등록해놓으면 그럴일은 없겠지만 나중에 혹시 EC2 IP가 바뀌어도 클라이언트 환경변수를 수정할 필요 없이 Route 53만 업데이트하면 된다.
물론 Route 53을 사용하는 쿼리 비용이 발생하긴하지만 쿼리 100만 개당 0.40 USD이므로 무시 가능한 수준이다.
Route 53 - 호스팅 영역을 들어와 등록한 도메인(호스팅 영역 이름)을 클릭한다.
subdomain을 api로 할 것이므로 "레코드 이름"에 api를 기입하고, 레코드 유형은 A를 유지한다.
값에 EC2의 public IP(탄력적 IP)를 붙여넣는다.
TTL은 테스트 단계에서는 300 (5분), 실제 배포할 때는 3600 (1시간)으로 설정한다.
라우팅 정책은 단순 라우팅(Simple routing)을 유지하면 된다.
"레코드 생성"을 클릭한다.
도메인에 CloudFront를 가리키는 A 레코드를 추가해주어야한다.
Route 53 - 호스팅 영역 에서 도메인을 클릭하고, "레코드 생성"을 클릭한다.
위와 같은 설정을 하고 "레코드 생성"을 클릭한다.
마지막으로 GitHub Secrets에 환경변수를 추가해 주어야 한다.
CI/CD를 하고자하는 repository에서 Settings - Security - Secrets and variables - Actions 로 접근한다.
"Manage environment secrets"를 클릭한다.
여러 변수들을 저장할 그룹에 대한 이름을 정하는 것이니 이름을 임의로 짓고 "Configure environment"를 클릭하면 된다.
위의 캡처는 이미 "Environment secrets"를 모두 추가해서 이렇게 보이는 것이고 "Add environment secret"을 클릭하고 하나씩 추가해주면 된다.
위에는 환경변수 명을 입력하고, 아래는 실제 값을 입력한 뒤 "Add secret"을 클릭한다.
이렇게 CI/CD를 위한 AWS 세팅 및 GitHub Secrets 추가를 마쳤다. 2부에서는 실제 배포를 어떻게 진행했는지 이야기해볼 예정이다.