Échec de Cloud Build avec l'erreur SUBSTITUTIONVARIABLENOT_DEFINED pour les modèles CI et le script de validation de substitution qui a corrigé l'exécution du pipeline

Publié: 2025-11-29

Cloud Build est devenu un outil essentiel dans les workflows d'intégration et de déploiement continus de nombreux développeurs et organisations. Son intégration étroite avec d'autres produits Google Cloud Platform (GCP) et des flux de travail scriptables en fait un favori des équipes souhaitant des pipelines CI/CD personnalisables et évolutifs. Cependant, comme de nombreux outils puissants, Cloud Build n'est pas sans bizarreries, notamment en ce qui concerne les variables et le paramétrage. Un problème frustrant rencontré récemment par de nombreux développeurs est l'erreurSUBSTITUTION_VARIABLE_NOT_DEFINED. Ce problème insaisissable peut arrêter tout un pipeline, affectant la vitesse de développement et augmentant le temps de dépannage.

TL;DR

Si votre pipeline Cloud Build échoue avec une erreurSUBSTITUTION_VARIABLE_NOT_DEFINED, cela signifie probablement qu'une variable de substitution requise est manquante dans votre déclencheur de build ou votre fichier de configuration. Ceci est courant lors de l'utilisation de modèles CI partagés entre les référentiels. Un script de validation de variable personnalisé a résolu ce problème en vérifiant toutes les variables requises au moment de l'exécution, fournissant ainsi des commentaires plus clairs et évitant les constructions défectueuses. La solution de contournement a également amélioré la robustesse globale du pipeline et minimisé les efforts de débogage manuel.

Comprendre l'erreur SUBSTITUTION_VARIABLE_NOT_DEFINED

L'erreurSUBSTITUTION_VARIABLE_NOT_DEFINEDest émise par Cloud Build lorsqu'un processus de build fait référence à une variable de substitution qui n'a pas été définie dans le contexte de cette build. Ces variables de substitution vous permettent de personnaliser les étapes de construction et les modèles sans coder en dur les valeurs directement dans le pipeline YAML, améliorant ainsi la réutilisabilité et la clarté.

Par exemple, un modèle Cloud Build courant peut inclure des étapes de création telles que les suivantes :

mesures:
- nom : 'gcr.io/cloud-builders/docker'
  arguments : ['build', '-t', '${_IMAGE_NAME}', '.']

Ici, ${_IMAGE_NAME} est une variable de substitution définie par l'utilisateur. Si cette variable n'est pas fournie au moment du déclenchement de la build, peut-être via une configuration de déclencheur ou une ligne de commande, Cloud Build échouera immédiatement avec une erreurSUBSTITUTION_VARIABLE_NOT_DEFINED.

Causes profondes dans les implémentations de modèles CI

Ce problème devient particulièrement gênant lorsque les équipes utilisent des modèles partagés ou lorsque différents référentiels s'appuient sur la même logique CI via des configurations YAML centralisées. Souvent, chaque référentiel ou déclencheur de build peut devoir définir différentes variables, mais assurer la cohérence devient un défi. De nombreuses équipes supposent qu'une variable de substitution est facultative ou qu'elle dispose d'une solution de secours par défaut, uniquement pour rencontrer cette erreur lorsque la variable est absente dans un contexte de construction qui l'attend.

Situations dans lesquelles cette erreur est susceptible d'apparaître :

Lorsqu'une valeur par défaut est oubliée dans les paramètres du déclencheur
Lorsqu'un nouveau modèle est ajouté mais que toutes les variables requises ne sont pas documentées ou appliquées
Lorsque les développeurs clonent des modèles dans des environnements (par exemple, transfert, production) mais omettent des définitions de variables spécifiques

Une solution pragmatique : le script de validation de substitution

Pour résoudre ce problème et éviter de futures perturbations, plusieurs équipes ont introduit un mécanisme de pré-validation : unscript de validationintégré qui s'exécute au début du pipeline pour vérifier les variables de substitution requises avant l'exécution de toute étape critique.

Le script analyse l'environnement actuel et tente d'affirmer la présence (et parfois le type ou le modèle) de toutes les variables critiques. S'il en manque, il arrête l'exécution plus tôt et fournit une liste lisible par l'homme des variables absentes.

Voici un exemple simplifié d'un tel script écrit en bash :

#!/bin/bash
définir -e

REQUIRED_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
)

pour VAR dans "${REQUIRED_VARS[@]}"
faire
  si [[ -z "${!VAR}" ]]; alors
    echo "ERREUR : la variable de substitution requise ${VAR} n'est pas définie."
    sortie 1
  fi
fait

echo "Toutes les variables de substitution requises sont présentes."

En plaçant cette étape en haut du pipeline de construction, les équipes peuvent détecter les erreurs plus tôt, réduire les cycles de calcul inutiles et fournir des commentaires plus utiles aux autres développeurs.

Intégration dans les workflows Cloud Build

Dans les flux de travail pratiques, le script shell de validation peut être inclus sous forme de commande en ligne ou importé à partir d'un fichier de script partagé dans un emplacement sécurisé, tel qu'un compartiment GCS versionné. Il s'agit généralement de la première étape du fichier cloudbuild.yaml :

mesures:
- nom : 'gcr.io/cloud-builders/bash'
  point d'entrée : 'bash'
  arguments : ['-c', './validate_vars.sh']

Cela donne aux équipes la possibilité de :

Versionner leur logique de validation CI
Maintenir une source unique de vérité pour les variables attendues
Réduisez les cycles de débogage bruyants impliquant une édition de déclencheurs par essais et erreurs

Expérience de développeur améliorée

L'introduction de ce script de validation a eu des effets immédiats :

Moins de pannes de pipelinedues à des variables manquantes inaperçues.
Message d'erreur plus clairqui pointait directement vers le problème au lieu de journaux obscurs.
Intégration plus rapidedes nouveaux développeurs qui ont réutilisé les flux de travail CI existants sans avoir besoin d'une connaissance tribale complète des variables attendues.

Au fil du temps, certaines équipes ont étendu le validateur pour autoriser des variablesfacultativeset définir des solutions de secours, donnant encore plus de flexibilité aux modèles partagés. D'autres l'ont associé à la validation de schéma YAML pour pelucher l'intégralité de leur pipeline cloudbuild.yaml au moment de l'exécution.

Prévenir l'erreur dans les nouveaux projets

Pour que les projets futurs ne soient pas confrontés à ce problème, il est recommandé de suivre ces bonnes pratiques :

Documentez toutes les variables de substitution requisesdans le guide README ou CI du dépôt.
Utilisez un script de validationdans chaque nouveau modèle ajouté à vos flux de travail CI/CD.
Définissez des conventions de dénomination claires(par exemple, les variables commençant par _ impliquent des substitutions personnalisées requises).
Définissez les valeurs par défautdans les builds, le cas échéant, ou fournissez une logique de variable facultative via des scripts.

Pensées finales

Bien que l'erreurSUBSTITUTION_VARIABLE_NOT_DEFINEDpuisse sembler anodine à première vue, elle représente un problème plus large en matière d'hygiène CI/CD et de gestion de la configuration. Traiter la validation des variables comme un composant de premier ordre de votre pipeline garantit des pratiques d'automatisation plus solides, moins de builds interrompues et des développeurs plus satisfaits. En introduisant un simple script de validation, de nombreuses équipes ont pu rationaliser leurs flux de travail de pipeline et réduire considérablement les temps d'arrêt et les efforts de débogage.

FAQ : Variables de substitution et validation de Cloud Build

Q : Qu'est-ce qu'une variable de substitution dans Cloud Build ?
Une variable de substitution est un espace réservé dans votre fichier cloudbuild.yaml qui est remplacé par des valeurs réelles lorsque la build est déclenchée. Ces variables sont utilisées pour personnaliser les builds pour différents environnements ou configurations.
Q : Pourquoi est-ce que je vois des erreurs SUBSTITUTION_VARIABLE_NOT_DEFINED ?
Cette erreur se produit généralement lorsqu'une variable référencée dans le fichier YAML n'est pas transmise via le déclencheur de build ou l'environnement, ce qui la rend indéfinie au moment de l'exécution.
Q : Comment puis-je fournir des variables de substitution lors du déclenchement d'une build ?
Vous pouvez transmettre des variables de substitution via Google Cloud Console lors de la configuration du déclencheur ou via gcloud CLI à l'aide de l'indicateur --substitutions .
Q : Puis-je définir des valeurs par défaut pour les variables de substitution ?
Cloud Build ne prend pas en charge les valeurs par défaut directement dans YAML, mais vous pouvez créer une logique de script pour gérer des variables non définies et attribuer des solutions de secours par programmation dans des scripts bash ou Python.
Q : Quelle est la meilleure façon d’imposer une présence variable sur plusieurs projets ?
Utilisez un script de validation partagé au début de tous les modèles cloudbuild.yaml pour assurer la cohérence et valider les entrées avant de poursuivre la tâche de build.