Python 애플리케이션 빌드

빌드팩은 환경 변수를 통해 언어 관용적 구성을 지원합니다.

Python 버전 지정

기본적으로 Python 런타임 빌드팩은 최신 Python 인터프리터 안정화 버전을 사용합니다. 애플리케이션에 특정 버전이 필요한 경우 애플리케이션 루트 디렉터리에 .python-version 파일을 포함하여 버전을 지정하면 됩니다.

3.13

GOOGLE_PYTHON_VERSION 사용

GOOGLE_PYTHON_VERSION 환경 변수를 통해 Python 버전을 지정할 수도 있습니다. 두 구성이 모두 설정된 경우 GOOGLE_PYTHON_VERSION 값이 .python-version 파일보다 우선 적용됩니다. 기본적으로 .python-version 파일과 GOOGLE_PYTHON_VERSION 환경 변수가 모두 지정되지 않은 경우 Python의 최신 LTS 버전이 사용됩니다.

앱을 배포할 때 Python 3.13을 사용하도록 빌드팩을 구성하려면 다음을 실행합니다.

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.13.x"

또한 project.toml 프로젝트 설명자를 사용하여 프로젝트 파일과 함께 환경 변수를 인코딩할 수 있습니다. 환경 변수로 애플리케이션 빌드에 대한 안내를 참조하세요.

pip로 종속 항목 지정

Python 빌드팩에서는 pip를 사용하여 애플리케이션 종속 항목을 관리할 수 있습니다. 애플리케이션 종속 항목은 루트 디렉터리의 requirements.txt 파일에 선언되어야 합니다.

requirements.txt 파일에는 패키지당 한 줄이 포함됩니다. 각 줄에는 패키지 이름과 선택사항으로 요청된 버전이 포함됩니다. 자세한 내용은 requirements.txt 참조를 참조하세요.

다음은 requirements.txt 파일의 예시입니다.

requests==2.20.0
numpy

pip 구성

환경 변수를 사용하여 pip 동작을 구성할 수 있습니다.

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

Artifact Registry의 비공개 종속 항목

Artifact Registry Python 저장소는 Python 함수의 비공개 종속 항목을 호스팅할 수 있습니다. Cloud Build에서 애플리케이션을 빌드할 때 Python 빌드팩은 Cloud Build 서비스 계정의 Artifact Registry 사용자 인증 정보를 자동으로 생성합니다. 추가 사용자 인증 정보를 생성하지 않고도 requirements.txt에 Artifact Registry URL만 포함하면 됩니다. 예를 들면 다음과 같습니다.

--extra-index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

애플리케이션 진입점

다음 섹션에서는 Python 빌드팩의 기본 진입점을 설명합니다.

Cloud Run 소스 배포의 진입점

이 기능은 Python 런타임으로 Cloud Run에 소스 코드를 배포하는 경우에만 사용할 수 있습니다. Cloud Run 소스 배포 프로세스 외부에서 pack build를 사용하여 컨테이너 이미지를 직접 빌드하는 경우에는 이 기능이 적용되지 않습니다.

Python 빌드팩은 FastAPI, Gradio, Streamlit과 같은 최신 웹 프레임워크를 지원합니다.

Python 버전 3.12 이하

Python 버전 3.12 이하를 사용하는 경우 Python 빌드팩은 기본적으로 Gunicorn을 워크로드의 WSGI HTTP 서버로 사용합니다. Python 빌드팩은 기본 진입점을 gunicorn -b :8080 main:app로 설정합니다.

Python 버전 3.13 이상

Python 버전 3.13 이상에서는 Python 빌드팩이 requirements.txt 파일의 웹 서버 또는 프레임워크 구성을 기반으로 Cloud Run 소스 배포의 기본 진입점을 설정합니다. 이 기본 설정은 Cloud Run 함수가 아닌 Cloud Run 서비스 소스 배포에만 적용됩니다.

Python 런타임을 사용하여 소스에서 Cloud Run 서비스를 배포하면 빌드팩은 다음과 같은 방식으로 Python 버전과 기본 진입점을 결정합니다.

  • 소스 파일에 Python 버전을 지정하지 않으면 Python 빌드팩이 기본값을 지원되는 최신 Python 버전으로 설정합니다. 빌드팩은 requirements.txt 파일에 구성한 웹 서버 또는 프레임워크를 기반으로 기본 진입점을 결정합니다.

  • requirements.txt 파일에 웹 서버나 프레임워크를 지정하지 않으면 Python 빌드팩은 기본적으로 Gunicorn을 워크로드의 WSGI HTTP 서버로 사용합니다. Python 빌드팩은 기본 진입점을 gunicorn -b :8080 main:app로 설정합니다.

  • Python 빌드팩은 requirements.txt 파일에 정의된 다음 우선순위에 따라 기본 진입점을 설정합니다.

    1. gunicorn
    2. uvicorn
    3. fastapi[standard]
    4. gradio
    5. streamlit

웹 서버 또는 프레임워크 구성

requirements.txt 파일의 각 일반 Python 구성에 대해 다음 표는 소스에서 Cloud Run에 배포할 때의 기본 진입점을 보여줍니다.

기본 구성 기본 진입점 환경 변수
gunicorn gunicorn -b :8080 main:app
numpy gunicorn -b :8080 main:app
fastapi
uvicorn		 uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard] uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn
gunicorn		 gunicorn -b :8080 main:app
gradio python main.py GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=8080
streamlit streamlit run main.py --server.address 0.0.0.0 --server.port 8080

배포 실패를 방지하려면 소스 파일에서 지원되는 Python 버전을 사용하고 requirements.txt 파일에서 웹 서버를 지정하세요.

또는 다음 소스 배포 명령어를 실행하여 진입점을 지정할 수도 있습니다.

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

다음을 바꿉니다.

  • SERVICE: 배포할 서비스의 이름입니다.
  • ENTRYPOINT: 소스 코드에 사용할 기본 진입점입니다.

소스 코드를 Cloud Run에 배포할 수 없거나 로그에서 오류를 찾을 수 없는 경우 Cloud Run 문제 해결 가이드를 참고하세요.

기타 모든 배포의 진입점

Python 빌드팩은 Gunicorn을 워크로드의 기본 WSGI HTTP 서버로 사용합니다. Python 빌드팩으로 빌드된 앱은 다음 실행과 비슷하게 기본 설정을 사용해서 gunicorn 프로세스를 시작합니다.

gunicorn --bind :8080 main:app

애플리케이션 진입점 맞춤설정

Procfile 또는 환경 변수를 사용하여 애플리케이션 시작 명령어를 맞춤설정할 수 있습니다. 기본 진입점 구성을 맞춤설정하려면 이 작업을 수행해야 할 수 있습니다.

루트 디렉터리에서 커스텀 설정으로 Procfile을 만들 수 있습니다. 예시:

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

또는 pack 명령어에 GOOGLE_ENTRYPOINT 환경 변수를 사용할 수 있습니다. 예시:

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

환경 변수

Python 빌드팩은 컨테이너를 맞춤설정하기 위해 다음 환경 변수를 지원합니다.

PIP_<key>

pip 문서를 참조하세요.

예: PIP_DEFAULT_TIMEOUT=60은 pip 명령어에 --default-timeout=60을 설정합니다.