Cloud Build falla con el error SUBSTITUTIONVARIABLENOT_DEFINED para las plantillas de CI y el script de validación de sustitución que corrigió la canalización

Cloud Build se ha convertido en una herramienta fundamental en los flujos de trabajo de implementación e integración continua de muchos desarrolladores y organizaciones. Su estrecha integración con otros productos de Google Cloud Platform (GCP) y flujos de trabajo programables lo convierten en el favorito de los equipos que desean canales de CI/CD escalables y personalizables. Sin embargo, como ocurre con muchas herramientas poderosas, Cloud Build no está exento de peculiaridades, especialmente cuando se trata de variables y parametrización. Un problema frustrante que han experimentado muchos desarrolladores recientemente es el errorSUBSTITUTION_VARIABLE_NOT_DEFINED. Este problema esquivo puede detener todo un proceso, lo que afecta la velocidad de desarrollo y aumenta el tiempo de resolución de problemas.

TL;DR

Si su canalización de Cloud Build falla con un errorSUBSTITUTION_VARIABLE_NOT_DEFINED, probablemente significa que falta una variable de sustitución requerida en su activador de compilación o archivo de configuración. Esto es común cuando se utilizan plantillas de CI compartidas entre repositorios. Un script de validación de variables personalizado solucionó este problema al verificar todas las variables requeridas en tiempo de ejecución, brindando comentarios más claros y evitando compilaciones defectuosas. La solución alternativa también mejoró la solidez general de la canalización y minimizó los esfuerzos de depuración manual.

Comprender el error SUBSTITUTION_VARIABLE_NOT_DEFINED

Cloud Build emite el errorSUBSTITUTION_VARIABLE_NOT_DEFINEDcuando un proceso de compilación hace referencia a una variable de sustitución que no se ha definido en el contexto de esa compilación. Estas variables de sustitución le permiten personalizar los pasos de compilación y las plantillas sin codificar valores directamente en el YAML de canalización, lo que mejora la reutilización y la claridad.

Por ejemplo, una plantilla de Cloud Build común podría incluir pasos de compilación como los siguientes:

pasos:
- nombre: 'gcr.io/cloud-builders/docker'
  argumentos: ['build', '-t', '${_IMAGE_NAME}', '.']

Aquí, ${_IMAGE_NAME} es una variable de sustitución definida por el usuario. Si esta variable no se proporciona en el momento en que se activa la compilación, tal vez a través de una configuración de activación o una línea de comando, Cloud Build fallará inmediatamente con un errorSUBSTITUTION_VARIABLE_NOT_DEFINED.

Causas fundamentales en las implementaciones de plantillas de CI

Este problema se vuelve particularmente problemático cuando los equipos usan plantillas compartidas o cuando diferentes repositorios utilizan la misma lógica de CI a través de configuraciones YAML centralizadas. A menudo, es posible que cada repositorio o activador de compilación necesite definir diferentes variables, pero hacer cumplir la coherencia se convierte en un desafío. Muchos equipos asumen que una variable de sustitución es opcional o que tiene un respaldo predeterminado, solo para encontrar este error cuando la variable está ausente en un contexto de compilación que lo espera.

Situaciones en las que es probable que aparezca este error:

• Cuando se olvida un valor predeterminado en la configuración del disparador
• Cuando se agrega una nueva plantilla pero no todas las variables requeridas están documentadas o aplicadas
• Cuando los desarrolladores clonan plantillas en distintos entornos (p. ej., preparación, producción) pero omiten definiciones de variables específicas

Una solución pragmática: el script de validación de sustitución

Para resolver este problema y evitar futuras interrupciones, varios equipos introdujeron un mecanismo de validación previa: unscript de validaciónintegrado que se ejecuta al inicio del proceso para verificar las variables de sustitución requeridas antes de ejecutar cualquier paso crítico.

El script escanea el entorno actual e intenta afirmar la presencia (y a veces el tipo o patrón) de todas las variables críticas. Si falta alguna, detiene la ejecución antes de tiempo y proporciona una lista legible por humanos de las variables que faltaban.

Aquí hay un ejemplo simplificado de un script escrito en bash:

#!/bin/bash
conjunto -e

REQUIRED_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
)

para VAR en "${REQUIRED_VARS[@]}"
hacer
  si [[ -z "${!VAR}" ]]; entonces
    echo "ERROR: La variable de sustitución requerida ${VAR} no está definida."
    salida 1
  fi
hecho

echo "Todas las variables de sustitución requeridas están presentes."

Al colocar este paso en la parte superior del proceso de compilación, los equipos pueden detectar errores temprano, reducir los ciclos de computación desperdiciados y brindar comentarios más útiles a otros desarrolladores.

Integración en flujos de trabajo de compilación en la nube

En flujos de trabajo prácticos, el script de shell de validación puede incluirse como un comando en línea o importarse desde un archivo de script compartido en una ubicación segura, como un depósito de GCS versionado. Normalmente es el primer paso del archivo cloudbuild.yaml:

pasos:
- nombre: 'gcr.io/cloud-builders/bash'
  punto de entrada: 'bash'
  argumentos: ['-c', './validate_vars.sh']

Esto les da a los equipos la capacidad de:

• Versione su lógica de validación de CI
• Mantener una única fuente de verdad para las variables esperadas.
• Reduzca los ruidosos ciclos de depuración que implican la edición de activadores de prueba y error

Experiencia de desarrollador mejorada

La introducción de este script de validación tuvo efectos inmediatos:

• Menos fallas en la tuberíadebido a variables faltantes inadvertidas.
• Mensajes de error más clarosque apuntaban directamente al problema en lugar de registros oscuros.
• Incorporación más rápidade nuevos desarrolladores que reutilizaron flujos de trabajo de CI existentes sin necesidad de un conocimiento tribal completo de las variables esperadas.

Con el tiempo, algunos equipos ampliaron el validador para permitir variablesopcionalesy establecer alternativas, brindando aún más flexibilidad a las plantillas compartidas. Otros lo combinaron con la validación del esquema YAML para modificar toda su canalización cloudbuild.yaml en tiempo de ejecución.

Prevenir el error en nuevos proyectos

Para mantener los proyectos futuros libres de este problema, se recomienda seguir estas mejores prácticas:

• Documente todas las variables de sustitución requeridasen el README o la guía CI del repositorio.
• Utilice un script de validaciónen cada nueva plantilla agregada a sus flujos de trabajo de CI/CD.
• Defina convenciones de nomenclatura claras(por ejemplo, las variables que comienzan con _ implican sustituciones personalizadas requeridas).
• Establezca valores predeterminadosen las compilaciones cuando corresponda o proporcione lógica de variables opcional a través de secuencias de comandos.

Pensamientos finales

Aunque el errorSUBSTITUTION_VARIABLE_NOT_DEFINEDpuede parecer inofensivo a primera vista, representa un problema más amplio en la gestión de configuración e higiene de CI/CD. Tratar la validación de variables como un componente de primera clase de su canalización garantiza prácticas de automatización más sólidas, menos compilaciones fallidas y desarrolladores más felices. Al introducir un script de validación simple, muchos equipos pudieron optimizar sus flujos de trabajo y reducir significativamente el tiempo de inactividad y el esfuerzo de depuración.

Preguntas frecuentes: variables de sustitución y validación de Cloud Build

• P: ¿Qué es una variable de sustitución en Cloud Build?
  Una variable de sustitución es un marcador de posición en su archivo cloudbuild.yaml que se reemplaza con valores reales cuando se activa la compilación. Estas variables se utilizan para personalizar compilaciones para diferentes entornos o configuraciones.
• P: ¿Por qué veo errores SUBSTITUTION_VARIABLE_NOT_DEFINED?
  Este error suele ocurrir cuando una variable a la que se hace referencia en el archivo YAML no pasa a través del entorno o activador de compilación, lo que la hace indefinida en tiempo de ejecución.
• P: ¿Cómo puedo proporcionar variables de sustitución al activar una compilación?
  Puedes pasar variables de sustitución a través de Google Cloud Console al configurar el activador o mediante la CLI de gcloud usando el indicador --substitutions .
• P: ¿Puedo establecer valores predeterminados para las variables de sustitución?
  Cloud Build no admite valores predeterminados directamente en YAML, pero puede programar la lógica para manejar variables no definidas y asignar alternativas mediante programación en scripts de bash o Python.
• P: ¿Cuál es la mejor manera de imponer la presencia variable en múltiples proyectos?
  Utilice un script de validación compartido al principio de todas las plantillas de cloudbuild.yaml para reforzar la coherencia y validar las entradas antes de continuar con el trabajo de compilación.