Os requisitos de execução de contêineres do Cloud Run
O Cloud Run executa qualquer contêiner que siga alguns requisitos. A documentação do Google diz que as solicitações vão para a porta 8080 por padrão, a variável de ambiente PORT é definida no contêiner de entrada, e o contêiner “deve escutar solicitações em 0.0.0.0” e “não deve escutar em 127.0.0.1”. Também diz que o Cloud Run “aceita especificamente o formato ABI Linux x86_64” e que uma imagem com várias arquiteturas deve incluir linux/amd64.
Duas dessas regras costumam causar problemas para quem desenvolve no Mac: um app vinculado a localhost funciona no terminal local e falha no Cloud Run, e uma imagem compilada nativamente no Apple silicon é arm64. Testar o contêiner real localmente detecta os dois problemas antes da implantação.
Teste um serviço do Cloud Run localmente no Apple silicon
- Escute em $PORT e 0.0.0.0. Faça o servidor ler a variável de ambiente
PORT(o Cloud Run envia solicitações para 8080 por padrão) e vincular-se a0.0.0.0, não a127.0.0.1. - Compile para linux/amd64. Execute
docker buildx build --platform linux/amd64 --load -t my-service .. O Cloud Run aceita a ABI Linux x86_64, então uma imagem arm64 compilada nativamente no seu Mac tem a arquitetura de destino errada. - Execute como o Cloud Run faria. Execute
docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 my-service. O Oxcart executa a imagem amd64 via Rosetta. - Faça uma chamada. Execute
curl localhost:8080. Para verificar o tratamento de PORT, inicie uma segunda cópia com-e PORT=9090 -p 9090:9090. - Publique no Artifact Registry. Execute
gcloud auth configure-docker REGION-docker.pkg.devuma vez, marque a imagem com a tagREGION-docker.pkg.dev/PROJECT/REPO/my-service:TAGe envie comdocker push.
O que executamos no Oxcart
Um pequeno serviço Python vinculado a $PORT, executado duas vezes com portas diferentes, além da imagem de exemplo do próprio 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!"O exemplo do Google é uma imagem somente amd64; o Oxcart a baixou e executou via Rosetta sem opções extras. Para imagens somente amd64 que você compilar, passe --platform linux/amd64 também no docker run: nos nossos testes, uma imagem amd64 compilada localmente só foi encontrada quando a plataforma foi informada.
Compilar para linux/amd64 no Apple silicon
# 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 .O builder padrão do Oxcart lista linux/amd64 e linux/arm64, e a compilação multiplataforma termina localmente com as duas variantes executáveis. O envio de uma imagem multiplataforma pelo Oxcart não é suportado; para o Cloud Run, publique a tag amd64, que é a variante que ele executa. As compilações são rápidas: 341 ms sem cache e 121 ms com cache para um contexto local pequeno, o mais rápido dos três ambientes testados.
Publique no Artifact Registry e implante
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-central1Dependências com Compose
Um serviço do Cloud Run geralmente se comunica com um banco de dados, cache ou outro serviço. Execute-os ao lado dele com Compose, defina PORT no ambiente do serviço e condicione a ordem de inicialização aos healthchecks:
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 retorna quando o cache está saudável e a API iniciou. O guia do Compose no Apple silicon detalha healthchecks, imagens amd64 e portas.
Portas no seu Mac
As portas publicadas escutam em todas as interfaces do Mac, como no padrão do Docker. Se outro app do Mac já escuta em 127.0.0.1:8080, localhost:8080 pode alcançar esse app em vez do seu contêiner. Escolha uma porta livre no host (-p 18080:8080) e mantenha PORT como o Cloud Run define. A visualização Ports do Oxcart mostra todos os serviços escutando no Mac ao lado dos seus contêineres e explica por que uma porta de contêiner não responde, inclusive quando o servidor está vinculado a 127.0.0.1 dentro do contêiner, o mesmo erro rejeitado pelo Cloud Run. Veja redes de contêineres no Mac.
Perguntas
Como executo um serviço do Cloud Run localmente no Mac?
Execute o contêiner com a variável PORT definida e a porta publicada: docker run -e PORT=8080 -p 8080:8080 IMAGE. Esse é o método que o Google documenta para testes locais com Docker. No Oxcart, verificamos com nossa imagem nas portas 8080 e 9090 e com o exemplo do Google us-docker.pkg.dev/cloudrun/container/hello.
Por que a implantação no Cloud Run falha com uma imagem compilada no Apple silicon?
O Google documenta que o Cloud Run aceita a ABI Linux x86_64 e que uma imagem com várias arquiteturas deve incluir linux/amd64. Um simples docker build em um Mac com Apple silicon produz uma imagem arm64. Compile com --platform linux/amd64.
Posso executar a imagem amd64 no Mac antes de implantar?
Sim. O Oxcart executa imagens linux/amd64 via Rosetta. Passe --platform linux/amd64 ao executar uma imagem somente amd64 compilada localmente; as imagens amd64 baixadas, como o exemplo hello do Google, rodaram sem essa opção no nosso teste.
Meu contêiner funciona localmente, mas o Cloud Run diz que ele não conseguiu escutar na porta. Por quê?
A causa mais comum é vincular-se a 127.0.0.1 ou a uma porta fixa no código. Os requisitos do Cloud Run dizem que o contêiner deve escutar em 0.0.0.0 na porta indicada por PORT. Teste localmente com um PORT diferente do padrão (por exemplo, 9090) para detectar portas fixas no código.
Preciso de gcloud beta code dev ou Cloud Code?
Não, são opcionais. O Google lista Docker simples, Docker com acesso ao Google Cloud, o emulador Cloud Code e gcloud beta code dev como formas de testar localmente. Docker no Oxcart permite testar diretamente a imagem e seu tratamento de PORT. gcloud beta code dev adiciona um fluxo de desenvolvimento baseado em Kubernetes usando minikube ou um contexto Kubernetes existente; escolha essa opção quando precisar dessa integração.
Como dou ao contêiner local acesso às APIs do Google Cloud?
Monte as credenciais como o Google documenta para “Docker com acesso ao Google Cloud”, normalmente Application Default Credentials por meio de um arquivo montado e GOOGLE_APPLICATION_CREDENTIALS. As conexões de saída dos contêineres no Oxcart são abertas pelo seu Mac, então sua VPN e seu DNS se aplicam.
Fontes e método
- Exemplos testados com Oxcart 0.1.2, Mac17,14, macOS 27.2, 2026-10-10 (PORT em 8080 e 9090, exemplo hello do Google como linux/amd64, compilações Buildx para uma e várias plataformas).
- Requisitos de contêineres do Cloud Run (porta, 0.0.0.0, x86_64): https://docs.cloud.google.com/run/docs/container-contract. Opções de teste local: https://docs.cloud.google.com/run/docs/testing/local e https://docs.cloud.google.com/sdk/gcloud/reference/beta/code/dev. Verificado em 2026-10-10.
- Velocidade de compilação: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPUs e 12 GiB, medianas de cinco amostras; os demais ambientes foram medidos mais cedo no mesmo dia, no mesmo Mac e com o mesmo sistema de medição, usando o cliente docker 29.4.