Cloud Build falhando com erro SUBSTITUTIONVARIABLENOT_DEFINED para modelos de CI e o script de validação de substituição executado pelo pipeline fixo

O Cloud Build se tornou uma ferramenta essencial nos fluxos de trabalho contínuos de integração e implantação de muitos desenvolvedores e organizações. Sua forte integração com outros produtos Google Cloud Platform (GCP) e fluxos de trabalho programáveis ​​o tornam o favorito para equipes que desejam pipelines de CI/CD personalizáveis ​​e escalonáveis. No entanto, como acontece com muitas ferramentas poderosas, o Cloud Build tem suas peculiaridades, especialmente quando se trata de variáveis ​​e parametrização. Um problema frustrante enfrentado por muitos desenvolvedores recentemente é o erroSUBSTITUTION_VARIABLE_NOT_DEFINED. Esse problema indescritível pode interromper todo um pipeline, afetando a velocidade de desenvolvimento e aumentando o tempo de solução de problemas.

DR

Se o pipeline do Cloud Build estiver falhando com um erroSUBSTITUTION_VARIABLE_NOT_DEFINED, isso provavelmente significa que uma variável de substituição necessária está faltando no acionador de build ou no arquivo de configuração. Isso é comum ao usar modelos de CI compartilhados entre repositórios. Um script de validação de variável personalizado corrigiu isso verificando todas as variáveis ​​necessárias em tempo de execução, fornecendo feedback mais claro e evitando compilações defeituosas. A solução alternativa também melhorou a robustez geral do pipeline e minimizou os esforços de depuração manual.

Compreendendo o erro SUBSTITUTION_VARIABLE_NOT_DEFINED

O erroSUBSTITUTION_VARIABLE_NOT_DEFINEDé emitido pelo Cloud Build quando um processo de build faz referência a uma variável de substituição que não foi definida no contexto desse build. Essas variáveis ​​de substituição permitem personalizar etapas de construção e modelos sem codificar valores diretamente no YAML do pipeline, melhorando a capacidade de reutilização e a clareza.

Por exemplo, um modelo comum do Cloud Build pode incluir etapas de build como estas:

passos:
- nome: 'gcr.io/cloud-builders/docker'
  args: ['construir', '-t', '${_IMAGE_NAME}', '.']

Aqui, ${_IMAGE_NAME} é uma variável de substituição definida pelo usuário. Se essa variável não for fornecida no momento em que o build for acionado, talvez por meio de uma configuração de gatilho ou linha de comando, o Cloud Build falhará imediatamente com um erroSUBSTITUTION_VARIABLE_NOT_DEFINED.

Causas raiz nas implementações de modelos de CI

Esse problema se torna particularmente problemático quando as equipes usam modelos compartilhados ou quando repositórios diferentes utilizam a mesma lógica de CI por meio de configurações YAML centralizadas. Muitas vezes, cada repositório ou gatilho de construção pode precisar definir variáveis ​​diferentes, mas impor a consistência torna-se um desafio. Muitas equipes assumem que uma variável de substituição é opcional ou que possui um substituto padrão, apenas para encontrar esse erro quando a variável está ausente em um contexto de construção que a espera.

Situações em que é provável que este erro apareça:

• Quando um valor padrão é esquecido nas configurações do gatilho
• Quando um novo modelo é adicionado, mas nem todas as variáveis ​​necessárias são documentadas ou aplicadas
• Quando os desenvolvedores clonam modelos em ambientes (por exemplo, teste, produção), mas omitem definições de variáveis ​​específicas

Uma solução pragmática: o script de validação de substituição

Para resolver esse problema e evitar interrupções futuras, diversas equipes introduziram um mecanismo de pré-validação – umscript de validaçãoincorporado que é executado no início do pipeline para verificar as variáveis ​​de substituição necessárias antes que qualquer etapa crítica seja executada.

O script verifica o ambiente atual e tenta afirmar a presença (e às vezes o tipo ou padrão) de todas as variáveis ​​críticas. Se alguma estiver faltando, ele interrompe a execução antecipadamente e fornece uma lista legível de quais variáveis ​​estavam ausentes.

Aqui está um exemplo simplificado de tal script escrito em bash:

#!/bin/bash
definir -e

REQUIRED_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
)

para VAR em "${REQUIRED_VARS[@]}"
fazer
  se [[ -z "${!VAR}" ]]; então
    echo "ERRO: A variável de substituição necessária ${VAR} não está definida."
    saída 1
  fi
feito

echo "Todas as variáveis ​​de substituição necessárias estão presentes."

Ao colocar esta etapa no topo do pipeline de construção, as equipes podem detectar erros antecipadamente, reduzir ciclos de computação desperdiçados e fornecer feedback mais útil a outros desenvolvedores.

Integração em fluxos de trabalho do Cloud Build

Em fluxos de trabalho práticos, o script de shell de validação pode ser incluído como um comando embutido ou importado de um arquivo de script compartilhado em um local seguro, como um bucket do GCS com versão. Normalmente é a primeira etapa no arquivo cloudbuild.yaml:

passos:
- nome: 'gcr.io/cloud-builders/bash'
  ponto de entrada: 'bash'
  args: ['-c', './validate_vars.sh']

Isso dá às equipes a capacidade de:

• Versão da lógica de validação de CI
• Mantenha uma única fonte de verdade para variáveis ​​esperadas
• Reduza ciclos de depuração barulhentos envolvendo edição de gatilho de tentativa e erro

Experiência aprimorada do desenvolvedor

A introdução deste script de validação teve efeitos imediatos:

• Menos falhas de pipelinedevido a variáveis ​​ausentes despercebidas.
• Mensagens de erro mais clarasque apontavam diretamente para o problema em vez de logs obscuros.
• Integração mais rápidade novos desenvolvedores que reutilizaram fluxos de trabalho de CI existentes sem a necessidade de conhecimento tribal completo das variáveis ​​esperadas.

Com o tempo, algumas equipes ampliaram o validador para permitir variáveis​​opcionaise definir substitutos, dando ainda mais flexibilidade aos modelos compartilhados. Outros o combinaram com a validação do esquema YAML para limpar todo o pipeline cloudbuild.yaml em tempo de execução.

Prevenindo o erro em novos projetos

Para manter projetos futuros livres desse problema, é recomendável seguir estas práticas recomendadas:

• Documente todas as variáveis ​​de substituição necessáriasno guia README ou CI do repositório.
• Use um script de validaçãoem cada novo modelo adicionado aos seus fluxos de trabalho de CI/CD.
• Defina convenções de nomenclatura claras(por exemplo, variáveis ​​começando com _ implicam substituições personalizadas necessárias).
• Defina valores padrãoem compilações quando apropriado ou forneça lógica variável opcional por meio de scripts.

Considerações Finais

Embora o erroSUBSTITUTION_VARIABLE_NOT_DEFINEDpossa parecer inócuo à primeira vista, ele representa um problema mais amplo na higiene de CI/CD e no gerenciamento de configuração. Tratar a validação de variáveis ​​como um componente de primeira classe do seu pipeline garante práticas de automação mais fortes, menos construções quebradas e desenvolvedores mais satisfeitos. Ao introduzir um script de validação simples, muitas equipes conseguiram simplificar seus fluxos de trabalho de pipeline e reduzir significativamente o tempo de inatividade e o esforço de depuração.

Perguntas frequentes: variáveis ​​de substituição e validação do Cloud Build

• P: O que é uma variável de substituição no Cloud Build?
  Uma variável de substituição é um espaço reservado em seu arquivo cloudbuild.yaml que é substituído por valores reais quando o build é acionado. Essas variáveis ​​são usadas para customizar compilações para diferentes ambientes ou configurações.
• P: Por que estou vendo erros SUBSTITUTION_VARIABLE_NOT_DEFINED?
  Esse erro normalmente ocorre quando uma variável referenciada no arquivo YAML não é passada pelo gatilho de build ou ambiente, tornando-a indefinida em tempo de execução.
• P: Como posso fornecer variáveis ​​de substituição ao acionar um build?
  Você pode transmitir variáveis ​​de substituição por meio do Console do Google Cloud ao configurar o gatilho ou por meio da CLI gcloud usando a sinalização --substitutions .
• P: Posso definir valores padrão para variáveis ​​de substituição?
  O Cloud Build não oferece suporte a valores padrão diretamente no YAML, mas você pode criar scripts de lógica para lidar com variáveis ​​indefinidas e atribuir substitutos programaticamente em scripts Bash ou Python.
• P: Qual é a melhor maneira de impor a presença variável em vários projetos?
  Use um script de validação compartilhado no início de todos os modelos cloudbuild.yaml para impor consistência e validar entradas antes de prosseguir com o trabalho de construção.