Les exigences d’exécution des conteneurs Cloud Run
Cloud Run exécute tout conteneur qui respecte quelques règles. La documentation de Google indique que les requêtes arrivent au port 8080 par défaut, que la variable d’environnement PORT est définie sur le conteneur d’entrée et que celui-ci « doit écouter les requêtes sur 0.0.0.0 » et « ne devrait pas écouter sur 127.0.0.1 ». Elle précise aussi que Cloud Run « prend spécifiquement en charge le format ABI Linux x86_64 » et qu’une image multiarchitecture doit inclure linux/amd64.
Deux de ces règles piègent les développeurs sur Mac : une application liée à localhost fonctionne dans un terminal local mais échoue sur Cloud Run, et une image construite nativement sur puce Apple est arm64. Tester le vrai conteneur en local permet de détecter les deux avant le déploiement.
Tester un service Cloud Run en local sur puce Apple
- Écoutez sur $PORT et 0.0.0.0. Faites lire au serveur la variable d’environnement
PORT(Cloud Run envoie les requêtes à 8080 par défaut) et liez-le à0.0.0.0, pas à127.0.0.1. - Construisez pour linux/amd64. Exécutez
docker buildx build --platform linux/amd64 --load -t my-service .. Cloud Run prend en charge l’ABI Linux x86_64 ; une image arm64 construite nativement sur votre Mac vise donc la mauvaise architecture. - Lancez le conteneur comme Cloud Run. Exécutez
docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 my-service. Oxcart exécute l’image amd64 via Rosetta. - Appelez le service. Exécutez
curl localhost:8080. Pour vérifier la gestion de PORT, lancez une seconde copie avec-e PORT=9090 -p 9090:9090. - Publiez dans Artifact Registry. Exécutez une fois
gcloud auth configure-docker REGION-docker.pkg.dev, puis donnez à l’image le tagREGION-docker.pkg.dev/PROJECT/REPO/my-service:TAGet publiez-la avecdocker push.
Ce que nous avons exécuté sur Oxcart
Un petit service Python qui écoute sur $PORT, lancé deux fois avec des ports différents, ainsi que l’image d’exemple 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!"L’exemple de Google est une image uniquement amd64 ; Oxcart l’a téléchargée et exécutée via Rosetta sans option supplémentaire. Pour les images uniquement amd64 que vous construisez vous-même, passez aussi --platform linux/amd64 à docker run : dans nos tests, une image amd64 construite localement n’était trouvée que si la plateforme était précisée.
Construire pour linux/amd64 sur puce 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 .Le builder par défaut d’Oxcart liste linux/amd64 et linux/arm64, et la construction multiplateforme aboutit en local avec les deux variantes exécutables. La publication d’une image multiplateforme depuis Oxcart n’est pas prise en charge : pour Cloud Run, publiez le tag amd64, puisqu’il exécute cette variante. Les constructions sont rapides : 341 ms sans cache et 121 ms avec cache pour un petit contexte local, le plus rapide des trois environnements testés.
Publier dans Artifact Registry et déployer
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-central1Les dépendances avec Compose
Un service Cloud Run communique généralement avec une base de données, un cache ou un autre service. Exécutez-les à ses côtés avec Compose, définissez PORT dans l’environnement du service et conditionnez l’ordre de démarrage aux contrôles de santé :
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 se termine lorsque le cache est sain et que l’API a démarré. Le guide de Compose sur puce Apple détaille les contrôles de santé, les images amd64 et les ports.
Les ports de votre Mac
Les ports publiés écoutent sur toutes les interfaces du Mac, comme avec Docker par défaut. Si une autre application Mac écoute déjà sur 127.0.0.1:8080, localhost:8080 peut atteindre cette application au lieu de votre conteneur. Choisissez donc un port libre sur l’hôte (-p 18080:8080) et gardez PORT tel que Cloud Run le définit. La vue Ports d’Oxcart affiche tous les services à l’écoute sur le Mac à côté de vos conteneurs et explique pourquoi un port de conteneur ne répond pas. Elle détecte notamment un serveur lié à 127.0.0.1 dans le conteneur, la même erreur que Cloud Run refuse. Voir le réseau des conteneurs sur Mac.
Questions
Comment exécuter un service Cloud Run en local sur Mac ?
Lancez son conteneur avec la variable PORT définie et le port publié : docker run -e PORT=8080 -p 8080:8080 IMAGE. C’est la méthode documentée par Google pour tester en local avec Docker. Sur Oxcart, nous l’avons vérifiée avec notre image aux ports 8080 et 9090 et avec l’exemple Google us-docker.pkg.dev/cloudrun/container/hello.
Pourquoi mon déploiement Cloud Run échoue-t-il avec une image construite sur puce Apple ?
Google précise que Cloud Run prend en charge l’ABI Linux x86_64 et qu’une image multiarchitecture doit inclure linux/amd64. Un simple docker build sur un Mac à puce Apple produit une image arm64. Construisez avec --platform linux/amd64.
Puis-je exécuter l’image amd64 sur mon Mac avant de la déployer ?
Oui. Oxcart exécute les images linux/amd64 via Rosetta. Passez --platform linux/amd64 pour lancer une image uniquement amd64 construite localement. Les images amd64 téléchargées, comme l’exemple hello de Google, ont fonctionné sans cette option lors de notre test.
Mon conteneur fonctionne en local, mais Cloud Run dit qu’il n’a pas pu écouter sur le port. Pourquoi ?
La cause la plus courante est une liaison à 127.0.0.1 ou à un port codé en dur. Les exigences de Cloud Run imposent au conteneur d’écouter sur 0.0.0.0 au port indiqué par PORT. Testez en local avec un PORT différent de la valeur par défaut (9090, par exemple) pour repérer les ports codés en dur.
Ai-je besoin de gcloud beta code dev ou de Cloud Code ?
Non, ils sont facultatifs. Google propose Docker seul, Docker avec accès à Google Cloud, l’émulateur Cloud Code et gcloud beta code dev pour les tests locaux. Docker sur Oxcart permet de tester directement l’image et sa gestion de PORT. gcloud beta code dev ajoute un environnement de développement fondé sur Kubernetes, avec minikube ou un contexte Kubernetes existant ; choisissez-le si vous avez besoin de cette intégration.
Comment donner au conteneur local accès aux API Google Cloud ?
Montez les identifiants comme Google le décrit pour « Docker avec accès à Google Cloud » : généralement des Application Default Credentials transmis par un fichier monté et GOOGLE_APPLICATION_CREDENTIALS. Les connexions sortantes des conteneurs Oxcart sont ouvertes par votre Mac ; votre VPN et votre DNS s’appliquent donc.
Sources et méthode
- Exemples testés avec Oxcart 0.1.2, Mac17,14, macOS 27.2, 2026-10-10 (PORT à 8080 et 9090, exemple hello de Google en linux/amd64, constructions Buildx pour une et plusieurs plateformes).
- Exigences des conteneurs Cloud Run (port, 0.0.0.0, x86_64) : https://docs.cloud.google.com/run/docs/container-contract. Options de test local : https://docs.cloud.google.com/run/docs/testing/local et https://docs.cloud.google.com/sdk/gcloud/reference/beta/code/dev. Vérifié le 2026-10-10.
- Vitesse de construction : Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPU et 12 GiB, médianes de cinq échantillons ; les autres environnements ont été mesurés plus tôt le même jour sur le même Mac et avec le même dispositif, avec le client docker 29.4.