Cloud Build non riesce con errore SUBSTITUTIONVARIABLENOT_DEFINED per i modelli CI e lo script di convalida della sostituzione che corregge le esecuzioni della pipeline

Cloud Build è diventato uno strumento fondamentale nei flussi di lavoro di integrazione e distribuzione continui di molti sviluppatori e organizzazioni. La sua stretta integrazione con altri prodotti Google Cloud Platform (GCP) e flussi di lavoro programmabili lo rendono uno dei preferiti per i team che desiderano pipeline CI/CD personalizzabili e scalabili. Tuttavia, come molti strumenti potenti, Cloud Build non è privo di peculiarità, soprattutto quando si tratta di variabili e parametrizzazione. Un problema frustrante riscontrato recentemente da molti sviluppatori è l'erroreSUBSTITUTION_VARIABLE_NOT_DEFINED. Questo problema sfuggente può bloccare un’intera pipeline, influenzando la velocità di sviluppo e aumentando i tempi di risoluzione dei problemi.

TL;DR

Se la pipeline Cloud Build non funziona con un erroreSUBSTITUTION_VARIABLE_NOT_DEFINED, probabilmente significa che manca una variabile di sostituzione obbligatoria nel trigger di build o nel file di configurazione. Questo è comune quando si utilizzano modelli CI condivisi tra repository. Uno script di convalida delle variabili personalizzate ha risolto questo problema controllando tutte le variabili richieste in fase di esecuzione, fornendo un feedback più chiaro e prevenendo build difettose. La soluzione alternativa ha inoltre migliorato la robustezza complessiva della pipeline e ridotto al minimo gli sforzi di debug manuale.

Comprensione dell'errore SUBSTITUTION_VARIABLE_NOT_DEFINED

L'erroreSUBSTITUTION_VARIABLE_NOT_DEFINEDviene emesso da Cloud Build quando un processo di build fa riferimento a una variabile di sostituzione che non è stata definita nel contesto di quella build. Queste variabili di sostituzione ti consentono di personalizzare i passaggi e i modelli di creazione senza codificare i valori direttamente nel file YAML della pipeline, migliorando la riusabilità e la chiarezza.

Ad esempio, un modello Cloud Build comune potrebbe includere passaggi di creazione come i seguenti:

passaggi:
- nome: 'gcr.io/cloud-builders/docker'
  argomenti: ['build', '-t', '${_IMAGE_NAME}', '.']

Qui, ${_IMAGE_NAME} è una variabile di sostituzione definita dall'utente. Se questa variabile non viene fornita al momento dell'attivazione della build, magari tramite una configurazione di trigger o una riga di comando, Cloud Build fallirà immediatamente con un erroreSUBSTITUTION_VARIABLE_NOT_DEFINED.

Cause principali nelle implementazioni dei modelli CI

Questo problema diventa particolarmente problematico quando i team utilizzano modelli condivisi o quando diversi repository supportano la stessa logica CI tramite configurazioni YAML centralizzate. Spesso, ogni repository o trigger di build potrebbe dover definire variabili diverse, ma garantire la coerenza diventa difficile. Molti team presumono che una variabile di sostituzione sia facoltativa o che abbia un fallback predefinito, solo per riscontrare questo errore quando la variabile è assente in un contesto di compilazione che la prevede.

Situazioni in cui è probabile che venga visualizzato questo errore:

• Quando un valore predefinito viene dimenticato nelle impostazioni del trigger
• Quando viene aggiunto un nuovo modello ma non tutte le variabili richieste sono documentate o applicate
• Quando gli sviluppatori clonano modelli tra ambienti (ad esempio, staging, produzione) ma omettono definizioni di variabili specifiche

Una soluzione pragmatica: lo script di convalida della sostituzione

Per risolvere questo problema e prevenire future interruzioni, diversi team hanno introdotto un meccanismo di pre-convalida: unoscript di convalidaincorporato che viene eseguito all'inizio della pipeline per verificare le variabili di sostituzione richieste prima che venga eseguito qualsiasi passaggio critico.

Lo script analizza l'ambiente corrente e tenta di affermare la presenza (e talvolta il tipo o il modello) di tutte le variabili critiche. Se ne manca qualcuno, interrompe anticipatamente l'esecuzione e fornisce un elenco leggibile dall'uomo delle variabili assenti.

Ecco un esempio semplificato di tale script scritto in bash:

#!/bin/bash
impostare -e

RICHIESTE_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
)

per VAR in "${REQUIRED_VARS[@]}"
Fare
  if [[ -z "${!VAR}" ]]; Poi
    echo "ERRORE: la variabile di sostituzione richiesta ${VAR} non è definita."
    uscita 1
  fi
Fatto

echo "Tutte le variabili di sostituzione richieste sono presenti."

Ponendo questo passaggio in cima alla pipeline di creazione, i team possono individuare tempestivamente gli errori, ridurre i cicli di calcolo sprecati e fornire feedback più utili ad altri sviluppatori.

Integrazione nei flussi di lavoro Cloud Build

Nei flussi di lavoro pratici, lo script della shell di convalida può essere incluso come comando in linea o importato da un file di script condiviso in una posizione sicura, come un bucket GCS con versione. In genere è il primo passaggio nel file cloudbuild.yaml:

passaggi:
- nome: 'gcr.io/cloud-builders/bash'
  punto di ingresso: 'bash'
  argomenti: ['-c', './validate_vars.sh']

Ciò offre ai team la possibilità di:

• Versione della logica di convalida CI
• Mantenere un'unica fonte di verità per le variabili attese
• Riduci i cicli di debug rumorosi che comportano la modifica dei trigger per tentativi ed errori

Esperienza degli sviluppatori migliorata

L'introduzione di questo script di validazione ha avuto effetti immediati:

• Meno guasti alla pipelinedovuti a variabili mancanti inosservate.
• Messaggi di errore più chiariche puntavano direttamente al problema anziché a registri oscuri.
• Onboarding più rapidodi nuovi sviluppatori che hanno riutilizzato i flussi di lavoro CI esistenti senza bisogno di una conoscenza tribale completa delle variabili previste.

Nel corso del tempo, alcuni team hanno esteso il validatore per consentire variabilifacoltativee impostare fallback, offrendo ancora più flessibilità ai modelli condivisi. Altri lo hanno abbinato alla convalida dello schema YAML per integrare l'intera pipeline cloudbuild.yaml in fase di runtime.

Prevenire l'errore nei nuovi progetti

Per mantenere i progetti futuri liberi da questo problema, si consiglia di seguire queste migliori pratiche:

• Documentare tutte le variabili di sostituzione richiestenel README o nella guida CI per il repository.
• Utilizza uno script di convalidain ogni nuovo modello aggiunto ai flussi di lavoro CI/CD.
• Definire convenzioni di denominazione chiare(ad esempio, le variabili che iniziano con _ implicano sostituzioni personalizzate richieste).
• Imposta i valori predefinitinelle build, ove appropriato, o fornisci una logica variabile opzionale tramite script.

Considerazioni finali

Sebbene l'erroreSUBSTITUTION_VARIABLE_NOT_DEFINEDpossa sembrare innocuo a prima vista, rappresenta un problema più ampio nell'igiene CI/CD e nella gestione della configurazione. Trattare la convalida delle variabili come un componente di prima classe della pipeline garantisce pratiche di automazione più efficaci, meno build interrotte e sviluppatori più felici. Introducendo un semplice script di convalida, molti team sono stati in grado di semplificare i flussi di lavoro della pipeline e ridurre significativamente i tempi di inattività e gli sforzi di debug.

Domande frequenti: variabili di sostituzione e convalida di Cloud Build

• D: Cos'è una variabile di sostituzione in Cloud Build?
  Una variabile di sostituzione è un segnaposto nel file cloudbuild.yaml che viene sostituito con valori effettivi quando viene attivata la build. Queste variabili vengono utilizzate per personalizzare le build per ambienti o configurazioni diversi.
• D: Perché visualizzo errori SUBSTITUTION_VARIABLE_NOT_DEFINED?
  Questo errore si verifica in genere quando una variabile a cui si fa riferimento nel file YAML non viene passata attraverso il trigger di compilazione o l'ambiente, rendendola indefinita in fase di runtime.
• D: Come posso fornire variabili di sostituzione quando si attiva una build?
  Puoi passare le variabili di sostituzione tramite Google Cloud Console durante la configurazione del trigger o tramite la CLI gcloud utilizzando il flag --substitutions .
• D: Posso impostare valori predefiniti per le variabili di sostituzione?
  Cloud Build non supporta i valori predefiniti direttamente nel file YAML, ma puoi creare script di logica per gestire variabili non definite e assegnare fallback a livello di codice negli script bash o Python.
• D: Qual è il modo migliore per applicare la presenza variabile su più progetti?
  Utilizza uno script di convalida condiviso all'inizio di tutti i modelli cloudbuild.yaml per garantire la coerenza e convalidare gli input prima di procedere con il processo di compilazione.