[FastAPI/Pyhton] - FastAPI Github Actions 자동 배포하기 #1

최근 해커톤에서 AI 기술을 활용해야 하는 상황이 있어, FastAPI 환경을 구축하고 직접 배포를 진행하게 되었습니다.
Spring Boot 배포 방식과 다른 점들이 있어, 나중에 헷갈리지 않도록 정리해 두려 합니다.
이번 환경은 FastAPI(Python) + MySQL 조합이며,
배포에는 Dockerfile, docker-compose.yml, 그리고 .github/workflows/deploy.yml을 이용한 GitHub Actions 자동 배포 방식을 사용했습니다.

기타 => Spring Boot + Github Actions 자동 배포

 

✏️ 인스턴스 생성

AI 모델을 사용해야 하기 때문에 t3.micro처럼 용량이 작은 인스턴스는 적합하지 않아, 이번에는 t3.large 유형으로 설정했습니다. 만약 단순 배포만 목적인 경우라면, t2.micro 프리 티어 유형을 사용하는 것을 추천합니다.
아래 사진과 같이 단계를 진행하면 인스턴스가 정상적으로 생성됩니다.

 

 

 

✏️ 보안그룹 생성 및 적용

다음 단계는 보안그룹(Security Group) 생성입니다.
보안그룹은 AWS EC2 인스턴스의 방화벽 역할을 하며, 어떤 트래픽이 EC2 인스턴스로 들어오고 나가는지를 제어합니다.
만약 보안그룹을 제대로 설정하지 않으면 외부 공격이나 무단 접근에 취약해질 수 있으므로, 반드시 허용된 트래픽만 통과하도록 구성해야 합니다.

보안그룹에서는 인바운드 규칙과 아웃바운드 규칙을 설정할 수 있습니다.

• 인바운드 규칙: 외부에서 EC2로 들어오는 트래픽 허용 규칙
• 아웃바운드 규칙: EC2에서 외부로 나가는 트래픽 허용 규칙

AWS 콘솔에서 EC2 → 보안 그룹으로 이동하면, 인스턴스에 적용된 인바운드/아웃바운드 규칙을 확인할 수 있습니다.
이번 예시에서는 MySQL + FastAPI 조합이기 때문에, 인바운드 규칙에 3306번(MySQL)과 8000번(FastAPI) 포트를 추가했습니다.

허용할 IP는 일반적으로 본인 현재 IP로 설정하는 것이 안전합니다.
소스(Source)에서 사용자 지정을 선택한 뒤 내 IP를 지정하면 됩니다.

규칙을 저장한 후, 다시 인스턴스 상세 정보를 확인하면 설정한 보안그룹이 적용된 것을 볼 수 있습니다.

 

✏️ 탄력적 IP 할당

인스턴스 자세히 보기를 클릭하면 퍼블릭 IPv4 주소를 확인할 수 있습니다.
이 주소는 EC2 인스턴스를 생성할 때 자동으로 할당되지만, 별도로 설정하지 않으면 인스턴스를 중지 후 재시작할 때마다 변경됩니다.
따라서 고정된 IP가 필요한 서비스 운영에는 적합하지 않습니다.

 

이 문제를 해결하기 위해 사용하는 것이 바로 탄력적 IP(Elastic IP) 입니다.
탄력적 IP를 사용하면 인스턴스를 재시작해도 IP가 변하지 않아, 안정적인 서비스 운영이 가능합니다.

설정 방법은 다음과 같습니다.

EC2 → 인스턴스 → 네트워크 및 보안 → 탄력적 IP 메뉴로 이동한 뒤 생성하기를 클릭합니다.
이후 생성된 탄력적 IP를 선택하고 탄력적 IP 주소 할당을 클릭하여, 연결할 인스턴스를 지정하면 됩니다.

탄력적 IP를 연결하고 나면, 인스턴스의 퍼블릭 IPv4 주소가 해당 탄력적 IP로 고정된 것을 확인할 수 있습니다.

• 탄력적 IP는 AWS에서 무료로 제공되지만, 인스턴스에 연결하지 않고 보유만 하면 과금됩니다.
• 한 계정당 기본 5개까지만 생성할 수 있습니다.
• 주로 도메인 연결, 고정 IP 기반 방화벽 설정, 외부 API 화이트리스트 등록 등에 활용됩니다.

 

 

 

✏️ 인스턴스 접속하기

EC2 인스턴스를 생성했으니 이제 로컬 환경에서 원격 접속을 해보겠습니다.
만약 자신의 퍼블릭 IPv4 도메인을 모르겠다면, 인스턴스를 클릭한 뒤 연결 버튼을 누르고, SSH 클라이언트 탭에서 확인할 수 있습니다.

먼저, 인스턴스를 만들 때 다운로드했던 pem 키 파일을 ~/.ssh 경로로 옮겨줍니다
예를 들어 파일명이 myserver.pem이라면 터미널에서 mv myserver.pem ~/.ssh처럼 입력합니다.

 

이 상태에서 바로 접속을 시도하면 Permission denied 또는 권한 관련 오류가 발생할 수 있습니다.
이는 SSH가 개인키 파일에 매우 엄격한 권한 조건을 요구하기 때문입니다.
따라서 chmod 400 ~/.ssh/myserver.pem 명령어를 통해 소유자만 읽을 수 있도록 권한을 설정합니다. (chmod 600도 가능하지만 400이 더 안전하다.)

 

이제 ssh -i ~/.ssh/myserver.pem ubuntu@퍼블릭IPv4도메인 명령어로 접속할 수 있습니다
다만, 이렇게 할 경우 접속할 때마다 -i ~/.ssh/myserver.pem를 계속 입력해야 하는 번거로움이 있습니다.

 

이럴 때는 ~/.ssh/config 파일을 만들어서 아래와 같이 설정하면 훨씬 편리합니다.

이렇게 설정한 후에는 ssh my-server 한 줄만 입력해도 바로 접속할 수 있습니다.

# 테스트용 서버
Host my-server
    HostName 52.78.110.130
    User ubuntu
    IdentityFile ~/.ssh/myserver.pem

 

 

 

✏️ ECR 생성

ECR은 AWS에서 제공하는 도커(Docker) 이미지 저장소입니다.
개발자가 만든 애플리케이션 이미지를 안전하게 저장하고, 필요할 때 ECS나 EC2, 또는 다른 컨테이너 환경에서 가져다 쓸 수 있도록 지원합니다.
기본적으로 프라이빗(Private) 리포지토리로 생성되며, 접근 권한을 IAM 정책으로 세밀하게 제어할 수 있습니다.
쉽게 말해 AWS 전용 Docker Hub라고 생각하면 됩니다.

ECS는 AWS에서 제공하는 컨테이너 오케스트레이션 서비스입니다.
ECR에 저장된 이미지를 가져와서 EC2 인스턴스나 AWS Fargate 위에서 실행하고, 배포, 확장, 모니터링까지 자동으로 관리해줍니다.쿠버네티스(Kubernetes)와 비슷한 역할을 하지만, AWS 환경에 최적화되어 있어 설정이 더 간단합니다.

• ECR: 컨테이너 이미지를 저장하는 곳
• ECS: 저장된 이미지를 실행·관리하는 곳

 

✏️ 역할 생성

ECR에 접속하려면 먼저 IAM 권한을 설정해야 합니다.
AWS 콘솔에서 IAM을 검색한 뒤 역할 메뉴로 이동하여 역할 생성을 클릭합니다.

역할 생성 과정에서 웹 자격 증명(Web identity)을 선택하면, 공급자 유형을 지정해야 합니다.
공급자 유형을 아직 만들지 않았다면, 먼저 생성해 주세요. (OpenID Connect 사용 시 GitHub 계정/레포와 연동)

 

권한 추가 단계에서는 AmazonEC2ContainerRegistryFullAccess 정책을 선택해 추가합니다.

 

역할 생성이 완료되면 해당 역할을 클릭하고 신뢰 관계(Trust relationships) 탭으로 이동하면 JSON 형식의 정책 문서를 확인할 수 있습니다. 여기서 주의할 점이 있습니다.
저 같은 경우 이미 OpenID Connect 형식으로 역할을 생성했기 때문에, 기본 예시(첫 번째 사진)와는 다르게 설정했습니다.
GitHub Actions에서 배포를 허용하려면, StringLike 항목에 배포할 GitHub 레포지토리를 추가해야 합니다.
이렇게 해야 해당 레포지토리에서만 ECR에 접근할 수 있도록 제한할 수 있습니다.

 

 

여기까지 설정을 완료했다면, AWS에서 진행해야 하는 부분은 모두 마무리된 것입니다.
이후에는 로컬 환경에서 설정할 GitHub 관련 구성, Dockerfile, docker-compose.yml, 그리고 GitHub Actions workflow 파일 작성 방법이 남아 있습니다. 이 부분은 다음 게시물에서 자세히 다루겠습니다.