Mac에서 Google Cloud Run 컨테이너를 로컬로 실행하고 테스트하기

Cloud Run의 컨테이너 실행 요구 사항

Cloud Run은 몇 가지 요구 사항을 따르는 컨테이너를 실행합니다. Google 문서에 따르면 요청은 기본적으로 포트 8080으로 전달되고, 인그레스 컨테이너에 PORT 환경 변수가 설정됩니다. 컨테이너는 “0.0.0.0에서 요청을 수신해야” 하며 “127.0.0.1에서 수신해서는 안 됩니다”. 또한 Cloud Run은 “구체적으로 Linux x86_64 ABI 형식을 지원”하며, 다중 아키텍처 이미지에는 linux/amd64가 포함되어야 한다고 명시합니다.

이 중 두 규칙이 Mac 개발자에게 자주 문제를 일으킵니다. localhost에 바인딩한 앱은 로컬 터미널에서 작동해도 Cloud Run에서는 실패하고, Apple Silicon에서 네이티브로 빌드한 이미지는 arm64입니다. 실제 컨테이너를 로컬에서 테스트하면 배포 전에 두 문제를 모두 발견할 수 있습니다.

Apple Silicon에서 Cloud Run 서비스 로컬 테스트하기

1. $PORT와 0.0.0.0에서 수신하세요. 서버가 PORT 환경 변수를 읽도록 하고 (Cloud Run은 기본적으로 8080에 요청을 보냅니다), 127.0.0.1이 아닌 0.0.0.0에 바인딩하세요.
2. linux/amd64용으로 빌드하세요. docker buildx build --platform linux/amd64 --load -t my-service .를 실행하세요. Cloud Run은 Linux x86_64 ABI를 지원하므로 Mac에서 네이티브로 빌드한 arm64 이미지는 대상 아키텍처가 맞지 않습니다.
3. Cloud Run과 같은 방식으로 실행하세요. docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 my-service를 실행하세요. Oxcart는 amd64 이미지를 Rosetta로 실행합니다.
4. 서비스를 호출하세요. curl localhost:8080를 실행하세요. PORT 처리를 확인하려면 -e PORT=9090 -p 9090:9090으로 두 번째 인스턴스를 시작하세요.
5. Artifact Registry로 푸시하세요. gcloud auth configure-docker REGION-docker.pkg.dev를 한 번 실행하고, 이미지에 REGION-docker.pkg.dev/PROJECT/REPO/my-service:TAG 태그를 붙인 뒤 docker push로 보내세요.

Oxcart에서 실행한 항목

$PORT에 바인딩하는 작은 Python 서비스를 서로 다른 포트로 두 번 실행했고, Google 자체 샘플 이미지도 실행했습니다.

docker run -d -e PORT=8080 -p 18081:8080 my-service
docker run -d -e PORT=9090 -p 18090:9090 my-service
curl localhost:18081        # hello from PORT=8080
curl localhost:18090        # hello from PORT=9090

docker run -d -e PORT=8080 -p 8081:8080 us-docker.pkg.dev/cloudrun/container/hello
docker image inspect us-docker.pkg.dev/cloudrun/container/hello --format '{{.Os}}/{{.Architecture}}'
# linux/amd64
curl localhost:8081         # "It's running!"

Google 샘플은 amd64 전용 이미지입니다. Oxcart는 추가 플래그 없이 이를 내려받아 Rosetta로 실행했습니다. 직접 빌드한 amd64 전용 이미지에는 docker run에도 --platform linux/amd64를 전달하세요. 테스트에서 로컬로 빌드한 amd64 이미지는 플랫폼을 지정했을 때만 찾을 수 있었습니다.

Apple Silicon에서 linux/amd64용 빌드하기

# Cloud Run target: amd64
docker buildx build --platform linux/amd64 --load -t my-service:amd64 .

# Both architectures in the local image store (runs locally either way)
docker buildx build --platform linux/amd64,linux/arm64 -t my-service:multi .

Oxcart의 기본 빌더는 linux/amd64와 linux/arm64를 모두 표시하며, 다중 플랫폼 빌드는 로컬에서 완료되고 두 변형 모두 실행할 수 있습니다. Oxcart에서 다중 플랫폼 이미지를 푸시하는 것은 지원되지 않으므로 Cloud Run에는 실제로 실행되는 amd64 태그를 푸시하세요. 작은 로컬 컨텍스트의 빌드는 캐시 없이 341 ms, 캐시를 사용하면 121 ms로, 테스트한 세 런타임 중 가장 빨랐습니다.

Artifact Registry로 푸시하고 배포하기

gcloud auth configure-docker us-central1-docker.pkg.dev
docker tag my-service:amd64 us-central1-docker.pkg.dev/my-project/apps/my-service:1.0.0
docker push us-central1-docker.pkg.dev/my-project/apps/my-service:1.0.0
gcloud run deploy my-service \
  --image us-central1-docker.pkg.dev/my-project/apps/my-service:1.0.0 --region us-central1

Compose로 의존 서비스 실행하기

Cloud Run 서비스는 보통 데이터베이스, 캐시 또는 다른 서비스와 통신합니다. Compose로 함께 실행하고, 서비스 환경에 PORT를 설정하고, 상태 검사로 시작 순서를 제어하세요.

services:
  api:
    build: .
    platform: linux/amd64
    environment:
      PORT: "8080"
      REDIS_URL: redis://cache:6379
    ports: ["8080:8080"]
    depends_on:
      cache:
        condition: service_healthy
  cache:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 2s
      retries: 30

docker compose up -d --wait는 캐시가 정상이고 API가 시작되면 반환됩니다. Apple Silicon의 Compose 가이드에서 상태 검사, amd64 이미지, 포트를 자세히 설명합니다.

Mac의 포트

게시한 포트는 Docker 기본 동작과 같이 Mac의 모든 인터페이스에서 수신합니다. 다른 Mac 앱이 이미 127.0.0.1:8080에서 수신 중이면 localhost:8080이 컨테이너 대신 그 앱에 연결될 수 있습니다. 비어 있는 호스트 포트(-p 18080:8080)를 선택하고 PORT는 Cloud Run이 설정하는 값으로 유지하세요. Oxcart의 Ports 뷰는 컨테이너 옆에 Mac의 모든 수신 서비스를 표시하고 컨테이너 포트가 응답하지 않는 이유를 설명합니다. 컨테이너 내부 서버가 127.0.0.1에 바인딩된 경우도 포함하며, 이는 Cloud Run에서도 거부하는 같은 오류입니다. Mac의 컨테이너 네트워킹을 참고하세요.

질문

Mac에서 Cloud Run 서비스를 로컬로 실행하려면 어떻게 하나요?

PORT 변수를 설정하고 포트를 게시해 컨테이너를 실행하세요: docker run -e PORT=8080 -p 8080:8080 IMAGE. Google이 Docker 로컬 테스트용으로 문서화한 방법입니다. Oxcart에서는 자체 이미지를 8080과 9090 포트에서, Google의 us-docker.pkg.dev/cloudrun/container/hello 샘플과 함께 검증했습니다.

Apple Silicon에서 빌드한 이미지로 Cloud Run 배포가 실패하는 이유는 무엇인가요?

Google 문서는 Cloud Run이 Linux x86_64 ABI를 지원하고 다중 아키텍처 이미지에 linux/amd64가 포함되어야 한다고 설명합니다. Apple Silicon Mac에서 일반적인 docker build는 arm64 이미지를 만듭니다. --platform linux/amd64로 빌드하세요.

배포 전에 Mac에서 amd64 이미지를 실행할 수 있나요?

네. Oxcart는 linux/amd64 이미지를 Rosetta로 실행합니다. 로컬에서 직접 빌드한 amd64 전용 이미지를 실행할 때는 --platform linux/amd64를 전달하세요. Google의 hello 샘플처럼 내려받은 amd64 이미지는 테스트에서 이 옵션 없이 실행됐습니다.

컨테이너가 로컬에서는 작동하지만 Cloud Run은 포트를 수신하지 못했다고 합니다. 왜 그런가요?

가장 흔한 원인은 127.0.0.1 또는 코드에 고정된 포트에 바인딩하는 것입니다. Cloud Run 요구 사항에 따르면 컨테이너는 0.0.0.0에서 PORT의 포트를 수신해야 합니다. 기본값이 아닌 PORT(예: 9090)로 로컬 테스트해 코드에 고정된 포트를 찾으세요.

gcloud beta code dev나 Cloud Code가 필요한가요?

아니요, 선택 사항입니다. Google은 일반 Docker, Google Cloud 접근 권한이 있는 Docker, Cloud Code 에뮬레이터, gcloud beta code dev를 로컬 테스트 방법으로 안내합니다. Oxcart의 Docker로 이미지와 PORT 처리를 직접 테스트할 수 있습니다. gcloud beta code dev는 minikube나 기존 Kubernetes 컨텍스트를 사용하는 개발 흐름을 추가합니다. 해당 통합이 필요할 때 선택하세요.

로컬 컨테이너에 Google Cloud API 접근 권한을 주려면 어떻게 하나요?

Google의 ‘Google Cloud 접근 권한이 있는 Docker’ 문서에 따라 인증 정보를 마운트하세요. 보통 마운트한 파일과 GOOGLE_APPLICATION_CREDENTIALS를 통해 Application Default Credentials를 전달합니다. Oxcart 컨테이너의 외부 연결은 Mac이 열기 때문에 Mac의 VPN과 DNS가 적용됩니다.

출처와 방법

• 예제 테스트 환경: Oxcart 0.1.2, Mac17,14, macOS 27.2, 2026-10-10 (PORT 8080과 9090, Google hello 샘플을 linux/amd64로 실행, Buildx 단일 및 다중 플랫폼 빌드).
• Cloud Run 컨테이너 요구 사항(포트, 0.0.0.0, x86_64): https://docs.cloud.google.com/run/docs/container-contract. 로컬 테스트 옵션: https://docs.cloud.google.com/run/docs/testing/local 및 https://docs.cloud.google.com/sdk/gcloud/reference/beta/code/dev. 2026-10-10에 확인했습니다.
• 빌드 속도: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, CPU 8개와 12 GiB, 5회 표본의 중앙값. 다른 런타임은 같은 날 더 이른 시간에 같은 Mac과 측정 도구에서 docker 29.4 클라이언트로 측정했습니다.