Google Cloud Run konteynerlerini Mac'te yerel olarak çalıştırın ve test edin

Cloud Run konteyner çalışma gereksinimleri

Cloud Run, kısa bir gereksinim listesine uyan her konteyneri çalıştırır. Google belgelerine göre istekler varsayılan olarak 8080 portuna gider, giriş konteynerinde PORT ortam değişkeni ayarlanır ve konteyner “istekleri 0.0.0.0 üzerinde dinlemeli”, “127.0.0.1 üzerinde dinlememelidir”. Belgeler ayrıca Cloud Run'ın “özellikle Linux x86_64 ABI biçimini desteklediğini” ve çok mimarili bir imajın linux/amd64 içermesi gerektiğini belirtir.

Bu kurallardan ikisi Mac geliştiricilerini zorlar: localhost'a bağlanan bir uygulama yerel terminalde çalışır ama Cloud Run'da başarısız olur; Apple silicon'da yerel olarak derlenen imaj ise arm64'tür. Gerçek konteyneri yerel olarak test etmek, dağıtımdan önce ikisini de yakalar.

Cloud Run servisini Apple silicon'da yerel olarak test edin

1. $PORT ve 0.0.0.0 üzerinde dinleyin. Sunucunun PORT ortam değişkenini okumasını sağlayın (Cloud Run istekleri varsayılan olarak 8080'e gönderir) ve 127.0.0.1 yerine 0.0.0.0'a bağlanın.
2. linux/amd64 için derleyin. docker buildx build --platform linux/amd64 --load -t my-service . komutunu çalıştırın. Cloud Run Linux x86_64 ABI'sini destekler; dolayısıyla Mac'inizde yerel olarak derlediğiniz arm64 imajı yanlış hedef mimariye sahiptir.
3. Cloud Run'ın çalıştıracağı gibi çalıştırın. docker run --rm --platform linux/amd64 -e PORT=8080 -p 8080:8080 my-service komutunu çalıştırın. Oxcart amd64 imajını Rosetta üzerinden çalıştırır.
4. Servise istek gönderin. curl localhost:8080 komutunu çalıştırın. PORT işlemesini kontrol etmek için -e PORT=9090 -p 9090:9090 ile ikinci bir kopya başlatın.
5. Artifact Registry'ye gönderin. gcloud auth configure-docker REGION-docker.pkg.dev komutunu bir kez çalıştırın, ardından imajı REGION-docker.pkg.dev/PROJECT/REPO/my-service:TAG olarak etiketleyip docker push ile gönderin.

Oxcart'ta neleri çalıştırdık

Farklı portlarla iki kez çalıştırılan, $PORT'a bağlanan küçük bir Python servisi ve Google'ın kendi örnek imajı:

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'ın örneği yalnızca amd64 içeren bir imajdır; Oxcart bunu indirip ek bayrak olmadan Rosetta üzerinden çalıştırdı. Kendiniz derlediğiniz yalnızca amd64 imajlarında docker run için de --platform linux/amd64 belirtin: testlerimizde yerel olarak derlenen amd64 imajı yalnızca platform verildiğinde bulundu.

Apple silicon'da linux/amd64 için derleme

# 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'ın varsayılan derleyicisi hem linux/amd64 hem de linux/arm64 listeler; çok platformlu derleme yerel olarak tamamlanır ve iki varyant da çalıştırılabilir. Oxcart'tan çok platformlu imaj göndermek desteklenmez; Cloud Run için çalıştırdığı varyant olan amd64 etiketini gönderin. Derlemeler hızlıdır: küçük bir yerel bağlamda önbelleksiz 341 ms, önbellekli 121 ms; test ettiğimiz üç çalışma ortamının en hızlısı.

Artifact Registry'ye gönderin ve dağıtın

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 ile bağımlılıklar

Bir Cloud Run servisi genellikle veritabanı, önbellek veya başka bir servisle iletişim kurar. Bunları Compose ile yanında çalıştırın, servisin ortamında PORT'u ayarlayın ve başlatma sırasını sağlık denetimlerine bağlayın:

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, önbellek sağlıklı olduğunda ve API başladığında döner. Apple silicon'da Compose rehberi sağlık denetimlerini, amd64 imajlarını ve portları ayrıntılı açıklar.

Mac'inizdeki portlar

Yayımlanan portlar, Docker'ın varsayılan davranışında olduğu gibi Mac'in tüm ağ arayüzlerinde dinler. Başka bir Mac uygulaması zaten 127.0.0.1:8080 üzerinde dinliyorsa localhost:8080 konteyneriniz yerine ona ulaşabilir. Bu yüzden boş bir ana makine portu seçin (-p 18080:8080) ve PORT'u Cloud Run'ın ayarladığı gibi bırakın. Oxcart'ın Ports görünümü, konteynerlerinizin yanında Mac'teki tüm dinleyicileri gösterir ve bir konteyner portunun neden yanıt vermediğini açıklar. Buna, Cloud Run'ın da reddettiği hata olan konteyner içindeki sunucunun 127.0.0.1'e bağlanması da dahildir. Bkz. Mac'te konteyner ağı.

Sorular

Cloud Run servisini Mac'te yerel olarak nasıl çalıştırırım?

Konteyneri PORT değişkeni ayarlanmış ve port yayımlanmış olarak çalıştırın: docker run -e PORT=8080 -p 8080:8080 IMAGE. Bu, Google'ın Docker ile yerel test için belgelediği yöntemdir. Oxcart'ta kendi imajımızla 8080 ve 9090 portlarında ve Google'ın us-docker.pkg.dev/cloudrun/container/hello örneğiyle doğruladık.

Apple silicon'da derlediğim imajla Cloud Run dağıtımım neden başarısız oluyor?

Google, Cloud Run'ın Linux x86_64 ABI'sini desteklediğini ve çok mimarili bir imajın linux/amd64 içermesi gerektiğini belirtir. Apple silicon Mac'te düz bir docker build arm64 imajı üretir. --platform linux/amd64 ile derleyin.

Dağıtımdan önce amd64 imajını Mac'imde çalıştırabilir miyim?

Evet. Oxcart linux/amd64 imajlarını Rosetta üzerinden çalıştırır. Yerel olarak derlediğiniz yalnızca amd64 imajını çalıştırırken --platform linux/amd64 belirtin; Google'ın hello örneği gibi indirilen amd64 imajları testimizde buna gerek olmadan çalıştı.

Konteynerim yerelde çalışıyor ama Cloud Run portu dinleyemediğini söylüyor. Neden?

En yaygın neden 127.0.0.1'e veya kodda sabitlenmiş bir porta bağlanmaktır. Cloud Run gereksinimlerine göre konteyner, PORT'taki portu 0.0.0.0 üzerinde dinlemelidir. Sabitlenmiş portları yakalamak için yerelde varsayılandan farklı bir PORT ile (örneğin 9090) test edin.

gcloud beta code dev veya Cloud Code gerekli mi?

Hayır, isteğe bağlıdır. Google yerel test seçenekleri olarak düz Docker, Google Cloud erişimli Docker, Cloud Code emülatörü ve gcloud beta code dev seçeneklerini listeler. Oxcart üzerindeki Docker, imajı ve PORT işlemesini doğrudan test etmenizi sağlar. gcloud beta code dev, minikube veya mevcut bir Kubernetes bağlamıyla Kubernetes tabanlı geliştirme akışı ekler; bu entegrasyona ihtiyaç duyduğunuzda seçin.

Yerel konteynere Google Cloud API'lerine erişimi nasıl veririm?

Kimlik bilgilerini Google'ın “Google Cloud erişimli Docker” için belgelediği şekilde bağlayın; genellikle bağlanan bir dosya ve GOOGLE_APPLICATION_CREDENTIALS üzerinden Application Default Credentials kullanılır. Oxcart'taki konteynerlerin dış bağlantılarını Mac'iniz açar; dolayısıyla VPN ve DNS ayarlarınız geçerlidir.

Kaynaklar ve yöntem

• Örnekler Oxcart 0.1.2 ile test edildi, Mac17,14, macOS 27.2, 2026-10-10 (PORT 8080 ve 9090, Google'ın hello örneği linux/amd64 olarak, tek ve çok platformlu Buildx derlemeleri).
• Cloud Run konteyner gereksinimleri (port, 0.0.0.0, x86_64): https://docs.cloud.google.com/run/docs/container-contract. Yerel test seçenekleri: https://docs.cloud.google.com/run/docs/testing/local ve https://docs.cloud.google.com/sdk/gcloud/reference/beta/code/dev. 2026-10-10 tarihinde kontrol edildi.
• Derleme hızı: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPU ve 12 GiB, beş örneğin medyanı; diğer çalışma ortamları aynı gün daha erken, aynı Mac ve ölçüm düzeneğinde docker 29.4 istemcisiyle ölçüldü.