Cloudflare Python Workers 정식 출시 | 파이썬 API를 명령 세 줄로 무료 배포하기

파이썬으로 간단한 API를 만들었는데 막상 인터넷에 올리려면 서버를 빌리고 설정하는 일이 더 큽니다. 클라우드플레어가 9월 21일 Python Workers 정식 출시(GA)를 발표하면서, 이제 파이썬 코드만으로 클라우드플레어 네트워크에 바로 배포할 수 있게 됐습니다.

2년 전 처음 소개한 기능을 정식 지원 언어로 올린 것입니다. 파이썬을 조금 다뤄 본 분이 무료 플랜으로 첫 배포까지 가는 과정을 공식 문서 명령어 그대로 정리하고, 해 보기 전에 알아야 할 제약도 함께 짚었습니다.

Cloudflare Python Workers는 파이썬 코드를 서버 없이 클라우드플레어 네트워크에 올려 실행하는 서비스다. uv와 Node.js를 설치한 뒤 pywrangler로 init, dev, deploy 세 명령이면 배포된다. 무료 플랜은 하루 10만 요청, 요청당 CPU 10ms까지이고, 스레드·멀티프로세싱이 동작하지 않는 등 일반 서버 파이썬과 다른 점이 있다.

PART 01

무엇이 달라졌나

Python Workers가 정식 출시되면서 달라진 점

Workers는 클라우드플레어가 운영하는 서버리스 실행 환경입니다. 원래 자바스크립트 중심이었고, 파이썬은 웹어셈블리로 컴파일한 파이썬(Pyodide) 위에서 돌아가는 베타였습니다. 이번 GA로 파이썬이 타입스크립트와 같은 1급 지원 언어가 됐다고 클라우드플레어는 밝혔습니다.

출처: Cloudflare 블로그

발표에서 눈에 띄는 변화는 세 가지입니다. 첫째, Workers AI·R2(파일 저장)·D1(데이터베이스)·큐 같은 클라우드플레어 서비스를 파이썬에서 바로 부를 수 있습니다. 둘째, FastAPI·장고·플라스크 같은 익숙한 웹 프레임워크를 Workers 안에서 돌릴 수 있습니다.

셋째, 패키지 생태계입니다. 클라우드플레어는 브라우저·웹어셈블리 환경용 파이썬 플랫폼 규격인 PEP 783을 제안했고, 1년 넘는 논의 끝에 채택됐다고 밝혔습니다. 패키지 제작자가 이 규격(PyEmscripten)용 파일을 PyPI에 올리면 Workers에서 쓸 수 있는 구조입니다. requests·httpx 같은 HTTP 라이브러리가 제대로 동작하도록 상위 프로젝트에 기여했다는 설명도 있습니다.

데이터베이스 연결도 달라졌습니다. 클라우드플레어는 파이썬 DB 드라이버가 여는 TCP 연결을 Workers의 connect API로 옮겨 주는 소켓 연결 계층을 만들었고, 이 덕분에 Hyperdrive로 PostgreSQL 같은 외부 데이터베이스에 붙을 수 있다고 설명했습니다. 한 Worker 안에서 다른 파이썬 Worker를 만드는 Dynamic Workers도 함께 소개됐습니다.

PART 02

첫 배포 따라 하기

준비물: uv와 Node.js

공식 문서 기준 준비물은 두 가지입니다. 파이썬 패키지 관리 도구 uv와, 내부적으로 쓰는 Node.js입니다. 그리고 무료 클라우드플레어 계정이 있어야 배포할 수 있습니다. 명령은 pywrangler라는 Python Workers 전용 도구로 실행합니다.

명령 세 줄로 배포하기

# 1) 새 프로젝트 만들기 (템플릿 선택)
uvx --from workers-py pywrangler init

# 2) 내 컴퓨터에서 실행해 보기
uv run pywrangler dev

# 3) 클라우드플레어에 배포
uv run pywrangler deploy

init을 실행하면 pyproject.toml과 wrangler 설정 파일이 만들어지고, workers-py가 개발용 의존성으로 들어갑니다. dev는 로컬에서 먼저 확인하는 단계입니다. deploy 때 클라우드플레어에 로그인돼 있지 않다면 인증 과정을 거치고, 배포가 끝나면 결과에 표시되는 접속 주소로 확인하면 됩니다.

템플릿만으로 감이 오지 않는다면 공식 예제 모음도 있습니다. python-workers-examples 저장소를 내려받아 hello 폴더부터 열어 보면 파일 구성과 설정을 한눈에 볼 수 있습니다.

git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/hello

가장 작은 코드

Python Worker의 기본 형태는 네 줄입니다. WorkerEntrypoint를 상속한 Default 클래스에 fetch 메서드를 만들면, 들어온 요청마다 이 메서드가 실행됩니다.

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello World!")

공식 문서는 설정 파일에 python_workers 호환성 플래그를 반드시 넣으라고 안내합니다. init으로 만든 프로젝트라도 생성된 설정 파일에 이 플래그가 있는지 먼저 확인하세요.

FastAPI 그대로 올리기

간단한 FastAPI 앱이라면 발표 글의 예시처럼 workers 모듈의 asgi 연결 도구로 앱을 감싸 Default에 넣으면 실행됩니다. 기존 프로젝트는 쓰는 의존성이 Workers에서 동작하는지 따로 확인해야 하고, fastapi를 의존성에 추가하는 방법은 패키지 문서에 나와 있습니다.

from fastapi import FastAPI
from workers import asgi

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "안녕하세요, Workers"}

Default = asgi.entrypoint(app)

PART 03

해 보기 전에 알아둘 제약

반응형

무료 플랜 한도

항목	무료 플랜	유료 플랜
요청 수	하루 10만 건	제한 없음(사용량 과금)
요청당 CPU 시간	10ms	기본 30초, 최대 5분
메모리	격리 단위당 128MB	128MB

숫자는 Workers 한도 문서 기준입니다. CPU 시간은 계산에 쓴 시간만 세고 외부 응답을 기다리는 시간은 포함하지 않습니다. 개인 프로젝트나 간단한 API라면 하루 10만 건은 넉넉한 편입니다.

제 판단으로는 무료 플랜의 10ms가 가장 먼저 부딪힐 벽입니다. 데이터를 받아 넘기는 API는 괜찮지만, 요청마다 무거운 계산을 하는 코드라면 무료 한도 안에서 돌기 어려울 수 있습니다. 배포 뒤 대시보드에서 CPU 시간을 먼저 확인해 보세요.

일반 서버 파이썬과 다른 점

Python Workers는 웹어셈블리 안에서 돌기 때문에 일반 서버와 다릅니다. 표준 라이브러리 문서에 따르면 threading과 multiprocessing은 불러올 수는 있어도 동작하지 않습니다. 비동기 처리가 필요하면 asyncio 기반 코드로 짜는 편이 맞습니다.

파일 저장도 주의해야 합니다. open()으로 파일을 쓸 수는 있지만 메모리 위의 임시 파일 시스템이라, Worker 실행 단위가 사라지면 함께 없어집니다. 오래 보관할 데이터는 KV, R2, Durable Objects 같은 저장소를 써야 합니다.

패키지도 모두 되는 건 아닙니다. 순수 파이썬 패키지와 PyEmscripten용으로 빌드된 패키지, Pyodide에 포함된 패키지만 쓸 수 있습니다. 공식 문서도 웹어셈블리용 패키지 지원은 아직 초기 단계라고 적고 있으니, 쓰려는 라이브러리가 있다면 설치부터 시험해 보세요.

비밀번호나 API 키는 코드에 적지 말고 Workers의 시크릿으로 넣으세요. 공식 문서는 환경 변수와 시크릿을 바인딩으로 불러 쓰는 방법을 안내하고, pywrangler는 wrangler의 명령을 모두 지원합니다. 코드가 공개 저장소에 올라가도 키가 새지 않게 하는 기본 습관입니다.

Q. 파이썬을 잘 몰라도 해 볼 수 있나요?

함수와 클래스를 조금 읽을 수 있다면 충분합니다. 템플릿이 기본 구조를 만들어 주고, 명령 세 줄로 배포까지 갑니다. 다만 터미널에서 uv와 Node.js를 설치하는 과정은 직접 해야 합니다.

Q. 기존 장고 프로젝트도 옮길 수 있나요?

클라우드플레어는 장고·플라스크를 Workers 안에서 돌릴 수 있다고 밝혔습니다. 하지만 스레드, 파일 저장, 데이터베이스 연결 방식이 달라 큰 프로젝트는 손볼 곳이 생깁니다. 작은 API부터 옮겨 보는 편이 안전합니다.

정리하면

Python Workers GA는 "파이썬 코드만 있으면 서버 없이 바로 배포"를 정식으로 지원한다는 뜻입니다. 오늘은 공식 문서의 init 명령으로 템플릿을 만들고 dev로 로컬에서 돌려 보세요. 무료 한도와 스레드 제약만 기억하면 개인 API 배포 도구로 충분히 쓸 만합니다.