Cloud Build, CI şablonları ve sabit ardışık düzenin çalıştırdığı ikame doğrulama komut dosyası için SUBSTITUTIONVARIABLENOT_DEFINED hatası nedeniyle başarısız oluyor

Yayınlanan: 2025-11-29

Cloud Build, birçok geliştiricinin ve kuruluşun sürekli entegrasyon ve dağıtım iş akışlarında önemli bir araç haline geldi. Diğer Google Cloud Platform (GCP) ürünleri ve komut dosyası oluşturulabilir iş akışlarıyla sıkı entegrasyonu, onu özelleştirilebilir ve ölçeklenebilir CI/CD ardışık düzenleri isteyen ekiplerin favorisi haline getiriyor. Ancak pek çok güçlü araçta olduğu gibi Cloud Build'in de tuhaflıkları var; özellikle konu değişkenler ve parametrelendirme olduğunda. Son zamanlarda birçok geliştiricinin yaşadığı sinir bozucu sorunlardan biriSUBSTITUTION_VARIABLE_NOT_DEFINEDhatasıdır. Bu anlaşılması zor sorun, geliştirme hızını etkileyerek sorun giderme süresini uzatarak tüm hattın durma noktasına gelmesine neden olabilir.

TL;DR

Cloud Build ardışık düzeninizSUBSTITUTION_VARIABLE_NOT_DEFINEDhatasıyla başarısız oluyorsa bu, muhtemelen derleme tetikleyicinizde veya yapılandırma dosyanızda gerekli bir ikame değişkeninin eksik olduğu anlamına gelir. Bu, veri havuzları arasında paylaşılan CI şablonlarını kullanırken yaygındır. Özel bir değişken doğrulama komut dosyası, çalışma zamanında gerekli tüm değişkenleri kontrol ederek, daha net geri bildirim sağlayarak ve hatalı yapıları önleyerek bu sorunu çözdü. Geçici çözüm ayrıca genel işlem hattı sağlamlığını iyileştirdi ve manuel hata ayıklama çabalarını en aza indirdi.

SUBSTITUTION_VARIABLE_NOT_DEFINED Hatasını Anlamak

SUBSTITUTION_VARIABLE_NOT_DEFINEDhatası, bir derleme işlemi söz konusu derleme bağlamında tanımlanmamış bir ikame değişkenine referans verdiğinde Cloud Build tarafından verilir. Bu ikame değişkenleri, değerleri doğrudan ardışık düzen YAML'ye kodlamadan derleme adımlarını ve şablonlarını özelleştirmenize olanak tanıyarak yeniden kullanılabilirliği ve netliği artırır.

Örneğin, ortak bir Cloud Build şablonu aşağıdaki gibi derleme adımlarını içerebilir:

adımlar:
- ad: 'gcr.io/cloud-builders/docker'
  args: ['derleme', '-t', '${_IMAGE_NAME}', '.']

Burada ${_IMAGE_NAME} kullanıcı tanımlı bir ikame değişkenidir. Bu değişken, derlemenin tetiklendiği sırada (belki de bir tetikleyici yapılandırması veya komut satırı aracılığıyla) sağlanmazsa Cloud Build,SUBSTITUTION_VARIABLE_NOT_DEFINEDhatasıyla hemen başarısız olur.

CI Şablonu Uygulamalarındaki Temel Nedenler

Bu sorun, ekipler paylaşılan şablonlar kullandığında veya farklı depolar merkezi YAML yapılandırmaları aracılığıyla aynı CI mantığını kullandığında özellikle sorun yaratır. Çoğu zaman, her bir deponun veya derleme tetikleyicisinin farklı değişkenleri tanımlaması gerekebilir, ancak tutarlılığı sağlamak zorlayıcı hale gelir. Pek çok ekip, bir ikame değişkenin isteğe bağlı olduğunu veya varsayılan bir geri dönüşe sahip olduğunu varsayar, ancak değişken onu bekleyen bir yapı bağlamında bulunmadığında bu hatayla karşılaşır.

Bu hatanın ortaya çıkma ihtimali olan durumlar:

Tetikleyici ayarlarında varsayılan bir değer unutulduğunda
Yeni bir şablon eklendiğinde ancak gerekli tüm değişkenler belgelenmediğinde veya uygulanmadığında
Geliştiricilerin şablonları ortamlar arasında (ör. hazırlama, üretim) klonlaması ancak belirli değişken tanımlarını atlaması

Pragmatik Bir Düzeltme: İkame Doğrulama Komut Dosyası

Bu sorunu çözmek ve gelecekteki kesintileri önlemek için birkaç ekip, herhangi bir kritik adım yürütülmeden önce gerekli ikame değişkenlerini kontrol etmek için işlem hattının başlangıcında çalışan yerleşik birdoğrulama komut dosyasıolan bir ön doğrulama mekanizması başlattı.

Komut dosyası mevcut ortamı tarar ve tüm kritik değişkenlerin varlığını (ve bazen türünü veya modelini) belirlemeye çalışır. Herhangi biri eksikse, yürütmeyi erken durdurur ve eksik olan değişkenlerin insan tarafından okunabilir bir listesini sağlar.

İşte bash ile yazılmış böyle bir betiğin basitleştirilmiş bir örneği:

#!/bin/bash
-e'yi ayarla

GEREKLİ_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
)

"${REQUIRED_VARS[@]}" içindeki VAR için
Yapmak
  if [[ -z "${!VAR}" ]]; Daha sonra
    echo "HATA: Gerekli ikame değişkeni ${VAR} tanımlı değil."
    çıkış 1
  fi
Tamamlandı

echo "Gerekli tüm ikame değişkenleri mevcut."

Ekipler, bu adımı derleme sürecinin en üstüne yerleştirerek hataları erken yakalayabilir, boşa giden bilgi işlem döngülerini azaltabilir ve diğer geliştiricilere daha yararlı geri bildirim sağlayabilir.

Cloud Build İş Akışlarına Entegrasyon

Pratik iş akışlarında doğrulama kabuğu komut dosyası, satır içi bir komut olarak dahil edilebilir veya sürümlendirilmiş bir GCS paketi gibi güvenli bir konumdaki paylaşılan bir komut dosyasından içe aktarılabilir. Bu genellikle cloudbuild.yaml dosyasındaki ilk adımdır:

adımlar:
- ad: 'gcr.io/cloud-builders/bash'
  giriş noktası: 'bash'
  args: ['-c', './validate_vars.sh']

Bu, takımlara şunları yapma olanağı sağlar:

CI doğrulama mantıklarını sürümlendirin
Beklenen değişkenler için tek bir doğruluk kaynağı sağlayın
Deneme yanılma tetikleyici düzenlemesini içeren gürültülü hata ayıklama döngülerini azaltın

Gelişmiş Geliştirici Deneyimi

Bu doğrulama komut dosyasının kullanıma sunulmasının hemen etkileri oldu:

Fark edilmeyen eksik değişkenler nedeniyledaha az işlem hattı hatası.
Belirsiz günlükler yerine doğrudan soruna işaret edendaha net hata mesajları.
Beklenen değişkenler hakkında tam bilgiye ihtiyaç duymadan mevcut CI iş akışlarını yeniden kullanan yeni geliştiricilerindaha hızlı katılımı.

Zamanla bazı ekipler, doğrulayıcıyıisteğe bağlıdeğişkenlere izin verecek ve geri dönüşleri ayarlayacak şekilde genişleterek paylaşılan şablonlara daha fazla esneklik kazandırdı. Diğerleri çalışma zamanında cloudbuild.yaml işlem hattının tamamını kaplamak için bunu YAML şema doğrulamasıyla eşleştirdi.

Yeni Projelerde Hatanın Önlenmesi

Gelecekteki projeleri bu sorundan uzak tutmak için aşağıdaki en iyi uygulamaların takip edilmesi önerilir:

Gerekli tüm ikame değişkenlerini deponun README veya CI kılavuzunda belgeleyin.
CI/CD iş akışlarınıza eklenen her yeni şablondabir doğrulama komut dosyası kullanın.
Açık adlandırma kurallarını tanımlayın(örneğin, _ ile başlayan değişkenler gerekli özel değişiklikleri belirtir).
Uygun olduğunda yapılardavarsayılan değerleri ayarlayınveya komut dosyası oluşturma yoluyla isteğe bağlı değişken mantığı sağlayın.

Son Düşünceler

SUBSTITUTION_VARIABLE_NOT_DEFINEDhatası ilk bakışta zararsız gibi görünse de CI/CD hijyeni ve yapılandırma yönetiminde daha geniş bir sorunu temsil eder. Değişken doğrulamayı işlem hattınızın birinci sınıf bir bileşeni olarak ele almak, daha güçlü otomasyon uygulamaları, daha az bozuk yapı ve daha mutlu geliştiriciler sağlar. Birçok ekip, basit bir doğrulama komut dosyası sunarak ardışık düzen iş akışlarını kolaylaştırabildi ve kesinti süresini ve hata ayıklama çabasını önemli ölçüde azaltabildi.

SSS: Cloud Build Değiştirme Değişkenleri ve Doğrulama

S: Cloud Build'te ikame değişkeni nedir?
Değiştirme değişkeni, cloudbuild.yaml dosyanızdaki, derleme tetiklendiğinde gerçek değerlerle değiştirilen bir yer tutucudur. Bu değişkenler, yapıları farklı ortamlar veya yapılandırmalar için özelleştirmek için kullanılır.
S: Neden SUBSTITUTION_VARIABLE_NOT_DEFINED hataları görüyorum?
Bu hata genellikle YAML dosyasında başvurulan bir değişkenin derleme tetikleyicisinden veya ortamından geçirilmemesi ve çalışma zamanında tanımsız hale gelmesi durumunda ortaya çıkar.
S: Bir yapıyı tetiklerken ikame değişkenlerini nasıl sağlayabilirim?
Tetikleyiciyi ayarlarken ikame değişkenlerini Google Cloud Console aracılığıyla veya --substitutions işaretini kullanarak gcloud CLI aracılığıyla iletebilirsiniz.
S: Değiştirme değişkenleri için varsayılan değerleri ayarlayabilir miyim?
Cloud Build, varsayılan değerleri doğrudan YAML'de desteklemez ancak tanımsız değişkenleri işlemek için mantık komut dosyası oluşturabilir ve bash veya Python komut dosyalarında programlı olarak yedekler atayabilirsiniz.
S: Birden fazla projede değişken varlığı zorunlu kılmanın en iyi yolu nedir?
Derleme işine devam etmeden önce tutarlılığı sağlamak ve girişleri doğrulamak için tüm cloudbuild.yaml şablonlarının başında paylaşılan bir doğrulama komut dosyası kullanın.