Google-Cloud-Run-Container lokal auf einem Mac ausführen und testen

Die Laufzeitanforderungen von Cloud Run

Cloud Run führt jeden Container aus, der einige Vorgaben erfüllt. Laut Googles Dokumentation gehen Anfragen standardmäßig an Port 8080; die Umgebungsvariable PORT wird im Ingress-Container gesetzt. Der Container „muss auf 0.0.0.0 auf Anfragen lauschen“ und „sollte nicht auf 127.0.0.1 lauschen“. Außerdem unterstützt Cloud Run laut Dokumentation „ausdrücklich das Linux-x86_64-ABI-Format“; ein Image für mehrere Architekturen muss linux/amd64 enthalten.

Zwei dieser Regeln führen bei der Entwicklung auf dem Mac oft zu Problemen: Eine an localhost gebundene App funktioniert im lokalen Terminal, scheitert aber in Cloud Run. Und ein nativ auf Apple-Chips gebautes Image ist arm64. Ein lokaler Test des tatsächlichen Containers deckt beides vor dem Deployment auf.

Einen Cloud-Run-Dienst lokal auf Apple-Chips testen

1. Auf $PORT und 0.0.0.0 lauschen. Der Server muss die Umgebungsvariable PORT lesen (Cloud Run sendet Anfragen standardmäßig an 8080) und an 0.0.0.0 binden, nicht an 127.0.0.1.
2. Für linux/amd64 bauen. Führe docker buildx build --platform linux/amd64 --load -t my-service . aus. Cloud Run unterstützt das Linux-x86_64-ABI; ein nativ auf deinem Mac gebautes arm64-Image hat also die falsche Zielarchitektur.
3. Wie in Cloud Run ausführen. Führe docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 my-service aus. Oxcart führt das amd64-Image über Rosetta aus.
4. Den Dienst aufrufen. Führe curl localhost:8080 aus. Um die Verarbeitung von PORT zu prüfen, starte eine zweite Instanz mit -e PORT=9090 -p 9090:9090.
5. In Artifact Registry hochladen. Führe einmal gcloud auth configure-docker REGION-docker.pkg.dev aus, versieh das Image dann mit dem Tag REGION-docker.pkg.dev/PROJECT/REPO/my-service:TAG und lade es mit docker push hoch.

Was wir auf Oxcart ausgeführt haben

Einen kleinen Python-Dienst, der an $PORT bindet, zweimal mit unterschiedlichen Ports ausgeführt, sowie Googles eigenes Beispiel-Image:

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!"

Googles Beispiel ist ein reines amd64-Image. Oxcart lud es herunter und führte es ohne zusätzliche Flags über Rosetta aus. Bei selbst gebauten reinen amd64-Images solltest du auch bei docker run --platform linux/amd64 angeben: In unseren Tests wurde ein lokal gebautes amd64-Image nur gefunden, wenn die Plattform angegeben war.

Für linux/amd64 auf Apple-Chips bauen

# 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 .

Oxcarts Standard-Builder listet sowohl linux/amd64 als auch linux/arm64 auf. Der Build für mehrere Plattformen wird lokal abgeschlossen, und beide Varianten sind ausführbar. Das Hochladen eines Images für mehrere Plattformen aus Oxcart wird nicht unterstützt. Lade für Cloud Run deshalb den amd64-Tag hoch, denn diesen führt es aus. Builds sind schnell: 341 ms ohne Cache und 121 ms mit Cache bei einem kleinen lokalen Kontext: die besten Werte unter den drei getesteten Laufzeitumgebungen.

In Artifact Registry hochladen und bereitstellen

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

Abhängigkeiten mit Compose

Ein Cloud-Run-Dienst kommuniziert meist mit einer Datenbank, einem Cache oder einem anderen Dienst. Führe diese mit Compose daneben aus, setze PORT in der Umgebung des Dienstes und steuere die Startreihenfolge mit 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: 30

docker compose up -d --wait kehrt zurück, sobald der Cache seinen Healthcheck besteht und die API gestartet ist. Die Anleitung zu Compose auf Apple-Chips behandelt Healthchecks, amd64-Images und Ports ausführlich.

Ports auf deinem Mac

Veröffentlichte Ports lauschen auf allen Netzwerkschnittstellen des Macs, wie in Dockers Standardeinstellung. Lauscht eine andere Mac-App bereits auf 127.0.0.1:8080, kann localhost:8080 diese App statt deines Containers erreichen. Wähle deshalb einen freien Host-Port (-p 18080:8080) und belasse PORT so, wie Cloud Run es setzt. Oxcarts Ansicht Ports zeigt neben deinen Containern alle lauschenden Dienste auf dem Mac und erklärt, warum ein Container-Port nicht antwortet. Dazu zählt auch ein Server, der im Container an 127.0.0.1 gebunden ist – derselbe Fehler, den Cloud Run ablehnt. Siehe Container-Netzwerke auf einem Mac.

Fragen

Wie führe ich einen Cloud-Run-Dienst lokal auf einem Mac aus?

Starte seinen Container mit gesetzter Variable PORT und veröffentlichtem Port: docker run -e PORT=8080 -p 8080:8080 IMAGE. Diesen Weg dokumentiert Google für lokale Tests mit Docker. Auf Oxcart haben wir ihn mit unserem eigenen Image auf den Ports 8080 und 9090 sowie mit Googles Beispiel us-docker.pkg.dev/cloudrun/container/hello überprüft.

Warum scheitert mein Cloud-Run-Deployment mit einem auf Apple-Chips gebauten Image?

Google dokumentiert, dass Cloud Run das Linux-x86_64-ABI unterstützt und ein Image für mehrere Architekturen linux/amd64 enthalten muss. Ein einfaches docker build auf einem Mac mit Apple-Chip erzeugt ein arm64-Image. Baue mit --platform linux/amd64.

Kann ich das amd64-Image vor dem Deployment auf meinem Mac ausführen?

Ja. Oxcart führt linux/amd64-Images über Rosetta aus. Gib beim Ausführen eines lokal selbst gebauten reinen amd64-Images --platform linux/amd64 an. Heruntergeladene amd64-Images wie Googles hello-Beispiel liefen in unserem Test ohne diese Angabe.

Mein Container funktioniert lokal, aber laut Cloud Run lauscht er nicht auf dem Port. Warum?

Am häufigsten bindet der Server an 127.0.0.1 oder einen fest codierten Port. Cloud Runs Laufzeitanforderungen verlangen, dass der Container auf 0.0.0.0 am Port aus PORT lauscht. Teste lokal mit einem anderen PORT als dem Standard, etwa 9090, um fest codierte Ports aufzudecken.

Brauche ich gcloud beta code dev oder Cloud Code?

Nein, beide sind optional. Google nennt normales Docker, Docker mit Google-Cloud-Zugriff, den Cloud-Code-Emulator und gcloud beta code dev als Möglichkeiten für lokale Tests. Mit Docker auf Oxcart testest du das Image und seine PORT-Verarbeitung direkt. gcloud beta code dev ergänzt einen Kubernetes-basierten Entwicklungsablauf mit minikube oder einem bestehenden Kubernetes-Kontext; wähle es, wenn du diese Integration brauchst.

Wie gebe ich dem lokalen Container Zugriff auf Google-Cloud-APIs?

Binde Zugangsdaten so ein, wie Google es unter „Docker mit Google-Cloud-Zugriff“ beschreibt. Üblich sind Application Default Credentials über eine eingebundene Datei und GOOGLE_APPLICATION_CREDENTIALS. Ausgehende Verbindungen von Oxcart-Containern öffnet dein Mac; damit gelten auch dein VPN und DNS.

Quellen und Methode

• Beispiele getestet mit Oxcart 0.1.2, Mac17,14, macOS 27.2, 2026-10-10 (PORT auf 8080 und 9090, Googles hello-Beispiel als linux/amd64, Buildx-Builds für eine und mehrere Plattformen).
• Cloud-Run-Laufzeitanforderungen für Container (Port, 0.0.0.0, x86_64): https://docs.cloud.google.com/run/docs/container-contract. Optionen für lokale Tests: https://docs.cloud.google.com/run/docs/testing/local und https://docs.cloud.google.com/sdk/gcloud/reference/beta/code/dev. Geprüft am 2026-10-10.
• Build-Geschwindigkeit: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPUs und 12 GiB, Mediane aus fünf Messungen; die anderen Laufzeitumgebungen wurden früher am selben Tag auf demselben Mac mit demselben Messaufbau und dem docker-Client 29.4 gemessen.