Gemini: AWS Elastic Beanstalk에 Python Flask 앱을 배포하는 방법

웹 애플리케이션을 배포하는 것은 단순히 코드를 작성하는 것 이상의 작업입니다. 여기에는 서버 관리, 로드 밸런서, 그리고 확장 정책(scaling policies) 설정 등이 포함됩니다. AWS Elastic Beanstalk은 여러분이 Python 로직에 집중하는 동안 인프라를 대신 관리해 주는 관리형 서비스를 제공하여 이 과정을 간소화합니다. 이 가이드에서는 Flask 애플리케이션을 운영 환경에 맞게 준비하고, Elastic Beanstalk 명령줄 인터페이스(EB CLI)를 사용하여 배포하는 과정을 단계별로 살펴보겠습니다.

프로젝트 환경 설정

애플리케이션을 작성하기 전에 깨끗한 환경을 구축해야 합니다. AWS Elastic Beanstalk은 애플리케이션의 진입점과 의존성 패키지를 식별하기 위해 특정 구성을 요구합니다. 먼저 프로젝트 디렉토리를 생성하고 패키지를 격리하기 위한 가상 환경을 만드는 것부터 시작합니다.

mkdir flask-aws-deploy
cd flask-aws-deploy
python3 -m venv venv
source venv/bin/activate

가상 환경이 활성화되면 Flask와 Gunicorn을 설치합니다. Flask는 웹 프레임워크이며, Gunicorn은 WSGI HTTP 서버입니다. Flask의 내장 개발 서버는 보안이나 높은 동시성을 처리하도록 설계되지 않았으므로 운영 환경에서는 절대 사용해서는 안 됩니다.

pip install flask gunicorn
pip freeze > requirements.txt

requirements.txt 파일은 필수입니다. 배포 시 Elastic Beanstalk은 이 파일을 읽어 Amazon Linux EC2 인스턴스에 필요한 라이브러리를 설치합니다. 이 파일에 패키지가 누락되면 배포 중 ImportError가 발생하며 실패하게 됩니다.

⚠️ 참고: requirements.txt에 gunicorn이 포함되어 있는지 확인하세요. 로컬 환경에서는 flask run으로 문제없이 실행될 수 있지만, AWS 환경에서는 Gunicorn을 사용하여 애플리케이션을 외부 인터넷에 서비스합니다.

Flask 애플리케이션 생성

Elastic Beanstalk의 Python 플랫폼은 기본적으로 application.py라는 이름의 파일을 찾도록 설정되어 있습니다. 또한 해당 파일 내의 Flask 객체 이름이 일반적인 app이 아닌 application으로 명명되기를 기대합니다. 이러한 명명 규칙을 따르면 나중에 수동으로 설정해야 하는 번거로움을 줄일 수 있습니다.

from flask import Flask, jsonify

# Elastic Beanstalk은 'application'이라는 이름의 변수를 찾습니다.
application = Flask(__name__)

@application.route("/")
def index():
    return jsonify(
        status="success",
        message="Flask application is running on AWS Elastic Beanstalk",
        version="1.0.0"
    )

@application.route("/health")
def health_check():
    # 이 엔드포인트는 로드 밸런서가 앱의 상태를 확인하는 데 사용됩니다.
    return jsonify(status="healthy"), 200

if __name__ == "__main__":
    # debug=True 설정은 로컬 개발 시 유용하지만,
    # AWS에서 WSGI를 통해 실행될 때는 이 블록이 무시됩니다.
    application.run(host="0.0.0.0", port=5000, debug=True)

/health 경로는 클라우드 배포의 모범 사례입니다. AWS Application Load Balancer(ALB)는 인스턴스가 올바르게 응답하는지 확인하기 위해 주기적으로 요청을 보냅니다. 로드 밸런서가 200 OK 응답을 받으면 해당 인스턴스를 정상 상태로 유지하고, 그렇지 않으면 비정상(unhealthy)으로 표시하여 트래픽 전송을 중단합니다.

파일을 저장한 후, 스크립트를 실행하여 로컬에서 제대로 작동하는지 확인하세요. 브라우저에서 로컬 URL에 접속했을 때 JSON 응답이 나타나야 합니다.

python application.py

예상 출력: * Running on http://0.0.0.0:5000. 해당 URL에 접속하면 index 경로에 정의된 JSON 상태 메시지가 표시될 것입니다.

배포 환경 구성

Elastic Beanstalk이 많은 설정을 자동으로 추측할 수 있지만, 명시적인 구성을 제공하면 애플리케이션이 올바르게 확장되고 동작하도록 보장할 수 있습니다. .ebextensions라는 디렉토리를 생성하여 배포 프로세스 중에 AWS가 읽을 구성 파일을 저장합니다.

mkdir .ebextensions
touch .ebextensions/python.config

python.config 내부에는 WSGI 애플리케이션의 경로를 정의합니다. 이를 통해 서버에 Flask 객체가 어디에 위치해 있는지 정확히 알려줍니다. 만약 파일 이름을 application.py가 아닌 다른 이름으로 지었거나 객체명을 application이 아닌 다른 것으로 정했다면 이 단계가 매우 중요합니다.

option_settings:
  aws:elasticbeanstalk:container:python:
    WSGIPath: application:application
  aws:elasticbeanstalk:environment:proxy:staticfiles:
    /static: static

WSGIPath의 값 application:application은 파일명:객체명 패턴을 따릅니다. staticfiles 섹션은 AWS가 static 디렉토리의 파일들을 Nginx를 통해 직접 서비스하도록 설정합니다. 이는 Python 애플리케이션을 거치는 것보다 훨씬 빠릅니다.

⚠️ 참고: YAML 파일은 들여쓰기에 민감합니다. 각 들여쓰기 수준에 탭(tab) 대신 공백(space) 2개를 사용해야 하며, 그렇지 않으면 AWS 파서가 구성 파일을 거부할 수 있습니다.

Elastic Beanstalk CLI 초기화

로컬 머신에 EB CLI가 설치되어 있어야 합니다. 아직 설치하지 않았다면 pip install awsebcli를 사용하세요. 또한 AWS CLI나 환경 변수를 통해 AWS 자격 증명이 설정되어 있어야 합니다. 초기화 명령을 실행하여 로컬 디렉토리를 AWS 애플리케이션에 연결합니다.

eb init -p python-3.12 flask-aws-app

이 과정에서 CLI가 몇 가지 질문을 던집니다. 선호하는 리전(예: us-east-1)을 선택하세요. SSH 설정 여부를 묻는 경우, 디버깅을 위해 EC2 인스턴스에 직접 접속하고 싶다면 "Yes"를 선택하세요. 배포 자체에 필수적인 사항은 아닙니다.

초기화가 완료되면 프로젝트 폴더에 .elasticbeanstalk 디렉토리가 생성됩니다. 이 디렉토리에는 프로젝트 설정이 저장되어 있으므로 삭제해서는 안 됩니다. 이제 환경을 생성하고 코드를 배포합니다. 이 단계에서 EC2 인스턴스, 보안 그룹, CloudWatch 로그를 포함한 실제 AWS 리소스가 생성됩니다.

eb create flask-env

이 명령은 완료까지 약 3~5분이 소요됩니다. CLI는 각 리소스 생성에 대한 실시간 업데이트를 제공합니다. S3 버킷, 로드 밸런서, 오토 스케일링 그룹 생성과 관련된 이벤트들을 확인할 수 있습니다.

생성 중 예상 터미널 출력:

INFO: createEnvironment is starting.
INFO: Using elasticbeanstalk-us-east-1-1234567890 as Amazon S3 storage bucket for environment data.
INFO: Created target group named: eb-t-flask-env
INFO: Created load balancer named: awseb-e-m-AWSEBLoa-12345
INFO: Environment health has transitioned from Pending to Ok.
INFO: Successfully launched environment: flask-env

배포 확인

eb create 명령이 완료되면 애플리케이션이 인터넷에 라이브 상태가 됩니다. 기본 브라우저에서 애플리케이션 주소를 바로 열어주는 간단한 명령어로 공개 URL을 확인할 수 있습니다.

eb open

터미널에서 상태를 확인하고 싶다면 status 명령어를 사용하세요. 환경의 상태(health), 사용 중인 플랫폼 버전, 로드 밸런서의 CNAME(URL) 등이 표시됩니다.

eb status

만약 애플리케이션에 "502 Bad Gateway"나 "Internal Server Error"가 표시된다면 가장 먼저 확인해야 할 곳은 애플리케이션 로그입니다. Elastic Beanstalk을 사용하면 웹 서버 로그의 마지막 100줄을 터미널에서 바로 간편하게 가져올 수 있습니다.

eb logs

특히 Python 트레이스백(traceback)이나 Gunicorn 오류를 유심히 살펴보세요. 흔한 오류로는 requirements.txt의 의존성 누락이나 WSGI 서버 실행을 방해하는 application.py의 구문 오류 등이 있습니다.

⚠️ 참고: 데이터베이스 URL이나 API 키와 같은 환경 변수가 필요한 경우 코드에 직접 작성하지 마세요. EB CLI를 사용하여 안전하게 설정할 수 있습니다: eb setenv KEY=VALUE. 설정된 값은 Python에서 os.environ.get('KEY')를 통해 접근할 수 있습니다.

애플리케이션 업데이트

코드를 수정했을 때 eb create를 다시 실행할 필요는 없습니다. 대신 변경 사항을 Git에 커밋하거나(사용 중인 경우), 단순히 배포 명령을 실행하면 됩니다. EB CLI는 업데이트된 코드를 패키징하여 S3에 업로드하고 EC2 인스턴스에 롤링 업데이트를 수행합니다.

# application.py를 수정한 후:
eb deploy

Elastic Beanstalk은 인스턴스를 소규모 배치 단위로 업데이트하여 서비스 중단 없이 업데이트를 처리합니다. 이를 통해 일부 인스턴스가 새 코드 버전으로 업데이트되는 동안에도 항상 다른 인스턴스가 유입되는 트래픽을 처리할 수 있도록 보장합니다.

리소스 정리

AWS는 EC2 인스턴스와 로드 밸런서를 포함하여 Elastic Beanstalk에서 사용하는 리소스에 대해 비용을 청구합니다. 본 튜토리얼을 마친 후 예상치 못한 비용 발생을 방지하려면 환경을 삭제하세요. 이 명령은 eb create로 생성된 모든 리소스를 제거합니다.

eb terminate flask-env

CLI에서 삭제 확인을 위해 환경 이름을 입력하라는 메시지가 표시됩니다. AWS가 네트워킹 및 컴퓨팅 리소스를 해제하는 데 몇 분 정도 소요됩니다.

지금까지 운영 환경에 적합한 Flask 애플리케이션을 구축하고 이를 관리형 클라우드 환경에 배포하는 과정을 성공적으로 마쳤습니다. 필수적인 파일 구조, application 명명 규칙의 중요성, 그리고 EB CLI를 사용해 앱의 라이프사이클을 관리하는 방법을 살펴보았습니다. 다음 단계로는 Amazon RDS와 같은 데이터베이스를 추가하거나, GitHub Actions를 사용하여 메인 브랜치에 푸시할 때마다 eb deploy 명령이 자동으로 실행되도록 CI/CD 파이프라인을 구축해 보는 것을 추천합니다.

Gemini 3 Flash

AI 평가

전체 응답