Compute Engine API tarihli sürümlere geçti, /v1 varsayılan kalıyor

Google, Compute Engine API için tarihli sürümlemeyi tüm bölgelerde genel kullanıma açtı. İlk stable sürüm 2026-09-01, ilk preview sürüm 2026-10-01-preview oldu. Sürüm belirtmeyen çağrılar eskisi gibi /v1’e gidiyor.

Compute Engine nedir, ne işe yarar?

Compute Engine, Google Cloud’un sanal makine hizmetidir. Kullanıcılar bu hizmetle VM oluşturur, disk ve ağ yapılandırır, GPU gibi donanımları iş yüklerine bağlar. Google Kubernetes Engine node’ları da Compute Engine üzerinde çalışır. Yönetimi web konsolu, gcloud CLI, REST API ve Terraform gibi araçlarla yapılır. AWS tarafındaki karşılığı EC2, Azure tarafındaki karşılığı Azure Virtual Machines hizmetidir.

Compute Engine API ile otomasyon yazıyorsanız bugüne kadar tek bir sözleşme vardı: /v1. Google bir varsayılanı değiştirmek istediğinde bu herkesin script’ini aynı anda etkiliyordu. Bu yüzden iyileştirmeler ya hiç gelmiyordu ya da yıllara yayılan geçişlerle geliyordu. Yeni modelde davranış değişiklikleri tarihli sürümlere taşınıyor, /v1 olduğu gibi kalıyor.

/v1 yerinde, sürüm seçimi sizde

Header göndermeyen her çağrı /v1’e düşüyor. Elle yazdığınız REST çağrıları ve eski script’ler şu an hiçbir değişiklik gerektirmeden çalışmaya devam ediyor.

Tarihli bir sürüm istediğinizde URL değişmiyor. Yol yine /compute/v1/ olarak kalıyor; sürümü X-Goog-Api-Version header’ı veya $apiVersion query parametresi seçiyor. SelfLink değerleri de aynı kaldığı için bu URI’leri saklayan envanter kayıtlarınıza dokunmanız gerekmiyor.

SDK güncellemesi artık API yükseltmesi

Asıl dikkat edilecek nokta burada. Client library’ler, gcloud ve Terraform bu header’ı sizin yerinize gönderiyor. Her yeni SDK release’i belirli bir tarihli sürüme bağlı geliyor. Gcloud compute paketlenmiş stable sürümü, Terraform’un google provider’ı stable sürümleri, google-beta ise preview sürümleri kullanıyor.

Import yolunuz compute_v1 olarak kalsa da bağımlılığı yükselttiğinizde altta konuşulan sözleşme değişebilir. Dependabot veya Renovate’in açtığı sıradan bir pull request, aggregated list davranışını ve izin denetimlerini birlikte değiştirebilir. Compute client library ve Terraform provider güncellemelerini patch gibi geçirmeyin. Provider sürümünü sabitleyin, release notlarını okuyun, staging’den geçirmeden üretime almayın.

Compute Engine API’de davranışı değişen üç yer

• AggregatedList: /v1’de returnPartialSuccess varsayılan olarak false. Tek bir zone’daki geçici sorun tüm global listeyi düşürebiliyordu. Tarihli sürümlerde kısmi başarı varsayılan olarak açık. İstek artık hata vermeden dönüyor, fakat yanıt bazı zone’ları içermeyebilir. Envanter, maliyet veya temizlik script’iniz listede görünmeyen VM’i silinmiş sayıyorsa yanlış karar verir. Kısmi yanıtın nasıl işaretlendiğini dokümantasyondan kontrol edip bu durumu kodunuzda ayrıca ele alın.
• Hata modeli: Tarihli sürümler AIP-193 uyumlu google.rpc.ErrorInfo payload’ı döndürüyor; reason ve domain alanları yapılandırılmış geliyor. Hata metnini regex ile yakalayan retry mantığınız varsa yükseltmeyle birlikte reason alanına geçirin. Geçersiz sürüm istediğinizde yanıt supported_versions listesini de veriyor.
• IAM: Google, geniş tutulmuş eski izin denetimlerini yeni sürümlerde sıkılaştıracağını söylüyor. Hangi izinlerin değiştiğini duyuruda listelemedi. Dar yetkili service account ile çalışan pipeline’larda yükseltme sonrası yetki hatalarını staging’de izleyin.

Staging’de iki sürümü yan yana çağırın

En hızlı test, aynı isteği header’sız ve tarihli sürümle gönderip yanıtları karşılaştırmak. Proje ve zone adını kendi değerlerinizle değiştirin:

curl -X GET \
  "https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-Api-Version: 2026-09-01"

Son satırı çıkarırsanız /v1 yanıtını alırsınız. Stable sürümler yayımlandıktan sonra breaking change almıyor ve şu an destek bitiş tarihleri yok. Staging’de doğruladığınız tarihi üretimde güvenle sabitleyebilirsiniz.

Preview sürümleri bir yıl yaşıyor

Preview sürümler bir stable sürümden ayrılıyor ve bir yıllık ömürle geliyor. Terraform’da google-beta preview API’lerini kullandığı için üretim modüllerinizde google-beta varsa bu ömür o kaynakları da ilgilendiriyor. Önce hangi modüllerin google-beta kullandığını çıkarın:

grep -rn "google-beta" --include="*.tf" .

Preview özelliklerini denemek için gcloud components update ile CLI’yı güncelleyin ve yeni gcloud preview compute komut grubunu kullanın. Mevcut gcloud compute, beta ve alpha script’leri olduğu gibi çalışıyor.

Stable sürümler çeyrekte bir geliyor. Her yeni Compute Engine API sürümünün release notlarını çeyreklik bakım takviminize ekleyin ve sabitlediğiniz tarihi o takvimle birlikte ilerletin.