Los requisitos de ejecución de contenedores de Cloud Run
Cloud Run ejecuta cualquier contenedor que cumpla unos pocos requisitos. La documentación de Google indica que las solicitudes van al puerto 8080 por defecto, que la variable de entorno PORT se establece en el contenedor de entrada y que el contenedor «debe escuchar solicitudes en 0.0.0.0» y «no debería escuchar en 127.0.0.1». También indica que Cloud Run «admite específicamente el formato ABI Linux x86_64» y que una imagen de varias arquitecturas debe incluir linux/amd64.
Dos de esas reglas suelen causar problemas al desarrollar en Mac: una app vinculada a localhost funciona en un terminal local y falla en Cloud Run, y una imagen compilada de forma nativa en equipos con chip de Apple es arm64. Probar el contenedor real en local detecta ambos problemas antes del despliegue.
Prueba un servicio de Cloud Run localmente en equipos con chip de Apple
- Escucha en $PORT y 0.0.0.0. Haz que el servidor lea la variable de entorno
PORT(Cloud Run envía solicitudes a 8080 por defecto) y se vincule a0.0.0.0, no a127.0.0.1. - Compila para linux/amd64. Ejecuta
docker buildx build --platform linux/amd64 --load -t my-service .. Cloud Run admite la ABI Linux x86_64, por lo que una imagen arm64 compilada de forma nativa en tu Mac tiene la arquitectura de destino incorrecta. - Ejecútalo como lo haría Cloud Run. Ejecuta
docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 my-service. Oxcart ejecuta la imagen amd64 a través de Rosetta. - Haz una solicitud. Ejecuta
curl localhost:8080. Para comprobar el manejo de PORT, inicia una segunda copia con-e PORT=9090 -p 9090:9090. - Publica en Artifact Registry. Ejecuta
gcloud auth configure-docker REGION-docker.pkg.devuna vez, etiqueta la imagen comoREGION-docker.pkg.dev/PROJECT/REPO/my-service:TAGy súbela condocker push.
Qué ejecutamos en Oxcart
Un pequeño servicio Python vinculado a $PORT, ejecutado dos veces con puertos distintos, y la imagen de ejemplo de 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!"El ejemplo de Google es una imagen solo para amd64; Oxcart la descargó y ejecutó a través de Rosetta sin opciones adicionales. Para las imágenes solo amd64 que compiles tú, pasa --platform linux/amd64 también en docker run: en nuestras pruebas, una imagen amd64 compilada localmente solo se encontraba al especificar la plataforma.
Compilar para linux/amd64 en equipos con chip de Apple
# 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 .El constructor predeterminado de Oxcart muestra tanto linux/amd64 como linux/arm64, y la compilación para varias plataformas se completa localmente con ambas variantes ejecutables. No se admite publicar una imagen multiplataforma desde Oxcart, así que para Cloud Run publica la etiqueta amd64, que es la que ejecuta. Las compilaciones son rápidas: 341 ms sin caché y 121 ms con caché para un contexto local pequeño: los mejores resultados de los tres entornos que probamos.
Publica en Artifact Registry y despliega
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-central1Dependencias con Compose
Un servicio de Cloud Run suele comunicarse con una base de datos, una caché u otro servicio. Ejecútalos a su lado con Compose, establece PORT en el entorno del servicio y condiciona el orden de arranque a las comprobaciones de salud:
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: 30docker compose up -d --wait termina cuando la caché está en buen estado y la API ha arrancado. La guía de Compose en equipos con chip de Apple explica en detalle las comprobaciones de salud, las imágenes amd64 y los puertos.
Puertos en tu Mac
Los puertos publicados escuchan en todas las interfaces del Mac, igual que el comportamiento predeterminado de Docker. Si otra app del Mac ya escucha en 127.0.0.1:8080, localhost:8080 puede llegar a esa app en lugar de a tu contenedor. Elige un puerto libre en el host (-p 18080:8080) y conserva PORT tal como lo establece Cloud Run. La vista Ports de Oxcart muestra todos los servicios que escuchan en el Mac junto a tus contenedores y explica por qué no responde un puerto del contenedor, incluido un servidor vinculado a 127.0.0.1 dentro del contenedor, el mismo error que Cloud Run rechaza. Consulta redes de contenedores en Mac.
Preguntas
¿Cómo ejecuto un servicio de Cloud Run localmente en un Mac?
Ejecuta su contenedor con la variable PORT establecida y el puerto publicado: docker run -e PORT=8080 -p 8080:8080 IMAGE. Es el método que Google documenta para pruebas locales con Docker. En Oxcart lo verificamos con nuestra propia imagen en los puertos 8080 y 9090 y con el ejemplo de Google us-docker.pkg.dev/cloudrun/container/hello.
¿Por qué falla mi despliegue en Cloud Run con una imagen compilada en equipos con chip de Apple?
Google documenta que Cloud Run admite la ABI Linux x86_64 y que una imagen de varias arquitecturas debe incluir linux/amd64. Un simple docker build en un Mac con chip de Apple genera una imagen arm64. Compila con --platform linux/amd64.
¿Puedo ejecutar la imagen amd64 en mi Mac antes de desplegarla?
Sí. Oxcart ejecuta imágenes linux/amd64 a través de Rosetta. Pasa --platform linux/amd64 al ejecutar una imagen solo amd64 que hayas compilado localmente; en nuestra prueba, las imágenes amd64 descargadas, como el ejemplo hello de Google, funcionaron sin esa opción.
Mi contenedor funciona localmente, pero Cloud Run dice que no ha podido escuchar en el puerto. ¿Por qué?
La causa más común es vincularse a 127.0.0.1 o a un puerto fijo en el código. Los requisitos de Cloud Run indican que el contenedor debe escuchar en 0.0.0.0 en el puerto definido por PORT. Prueba localmente con un PORT distinto del predeterminado (por ejemplo 9090) para detectar puertos fijos en el código.
¿Necesito gcloud beta code dev o Cloud Code?
No, son opcionales. Google enumera Docker sin más, Docker con acceso a Google Cloud, el emulador Cloud Code y gcloud beta code dev como opciones para pruebas locales. Docker en Oxcart permite probar directamente la imagen y su manejo de PORT. gcloud beta code dev añade un flujo de desarrollo basado en Kubernetes con minikube o un contexto Kubernetes existente; úsalo si necesitas esa integración.
¿Cómo doy al contenedor local acceso a las API de Google Cloud?
Monta las credenciales como documenta Google para «Docker con acceso a Google Cloud», normalmente Application Default Credentials mediante un archivo montado y GOOGLE_APPLICATION_CREDENTIALS. Las conexiones salientes de los contenedores en Oxcart las abre tu Mac, así que se aplican tu VPN y tu DNS.
Fuentes y método
- Ejemplos probados con Oxcart 0.1.2, Mac17,14, macOS 27.2, 2026-10-10 (PORT en 8080 y 9090, ejemplo hello de Google como linux/amd64 y compilaciones Buildx para una y varias plataformas).
- Requisitos de contenedores de Cloud Run (puerto, 0.0.0.0, x86_64): https://docs.cloud.google.com/run/docs/container-contract. Opciones de pruebas locales: https://docs.cloud.google.com/run/docs/testing/local y https://docs.cloud.google.com/sdk/gcloud/reference/beta/code/dev. Comprobado el 2026-10-10.
- Velocidad de compilación: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPU y 12 GiB, medianas de cinco muestras; los demás entornos se midieron antes ese mismo día en el mismo Mac, con el mismo sistema de medición y el cliente docker 29.4.