Cloud Build が CI テンプレートと修正されたパイプラインを実行する置換検証スクリプトのエラー SUBSTITUTIONVARIABLENOT_DEFINED で失敗する

公開: 2025-11-29

Cloud Build は、多くの開発者や組織の継続的な統合とデプロイのワークフローにおいて極めて重要なツールとなっています。他の Google Cloud Platform (GCP) 製品やスクリプト化可能なワークフローと緊密に統合されているため、カスタマイズ可能でスケーラブルな CI/CD パイプラインを必要とするチームに人気があります。ただし、多くの強力なツールと同様、Cloud Build にも、特に変数とパラメータ化に関して、癖がないわけではありません。最近多くの開発者が経験しているイライラする問題の 1 つは、 SUBSTITUTION_VARIABLE_NOT_DEFINEDエラーです。このとらえどころのない問題により、パイプライン全体が停止し、開発速度に影響を与え、トラブルシューティング時間が増加する可能性があります。

TL;DR

Cloud Build パイプラインがSUBSTITUTION_VARIABLE_NOT_DEFINEDエラーで失敗する場合は、ビルドトリガーまたは構成ファイルに必要な置換変数が欠落している可能性があります。これは、リポジトリ間で共有される CI テンプレートを使用する場合によく発生します。カスタム変数検証スクリプトは、実行時に必要なすべての変数をチェックし、より明確なフィードバックを提供し、ビルドの欠陥を防ぐことでこの問題を修正しました。この回避策により、パイプライン全体の堅牢性も向上し、手動によるデバッグ作業が最小限に抑えられました。

SUBSTITUTION_VARIABLE_NOT_DEFINED エラーについて

SUBSTITUTION_VARIABLE_NOT_DEFINEDエラーは、ビルドプロセスがそのビルドのコンテキストで定義されていない置換変数を参照すると、Cloud Build によって生成されます。これらの置換変数を使用すると、値をパイプライン YAML に直接ハードコードせずにビルドステップとテンプレートをカスタマイズできるため、再利用性と明確さが向上します。

たとえば、一般的な Cloud Build テンプレートには次のようなビルドステップが含まれる場合があります。

手順:
- 名前: 'gcr.io/cloud-builders/docker'
  引数: ['ビルド'、'-t'、'${_IMAGE_NAME}'、'.']

ここで、 ${_IMAGE_NAME}はユーザー定義の置換変数です。ビルドのトリガー時にこの変数が指定されていない場合（おそらくトリガー構成またはコマンドラインを介して）、Cloud Build はすぐにSUBSTITUTION_VARIABLE_NOT_DEFINEDエラーで失敗します。

CI テンプレートの実装における根本原因

この問題は、チームが共有テンプレートを使用している場合、または集中 YAML 構成を介して異なるリポジトリが同じ CI ロジックを便乗している場合に特に問題になります。多くの場合、各リポジトリまたはビルドトリガーで異なる変数を定義する必要がありますが、一貫性を確保するのは困難になります。多くのチームは、置換変数がオプションであるか、デフォルトのフォールバックがあると想定していますが、このエラーが発生するのは、それを予期するビルドコンテキストに変数が存在しない場合だけです。

このエラーが発生する可能性がある状況は次のとおりです。

トリガー設定のデフォルト値を忘れた場合
新しいテンプレートが追加されたが、必要な変数のすべてが文書化または強制されていない場合
開発者が複数の環境 (ステージング、運用環境など) にわたってテンプレートのクローンを作成するが、特定の変数定義を省略する場合

実用的な修正: 置換検証スクリプト

この問題を解決し、今後の混乱を防ぐために、いくつかのチームは事前検証メカニズムを導入しました。これは、重要なステップが実行される前に、パイプラインの開始時に実行され、必要な置換変数をチェックする埋め込み検証スクリプトです。

スクリプトは現在の環境をスキャンし、すべての重要な変数の存在 (場合によってはタイプまたはパターン) をアサートしようとします。欠落している変数がある場合は、実行を早期に停止し、欠落している変数の人間が判読できるリストを提供します。

bash で書かれたそのようなスクリプトの簡略化された例を次に示します。

#!/bin/bash
セット -e

REQUIRED_VARS=(
  「_IMAGE_NAME」
  「_SERVICE_NAME」
)

「${REQUIRED_VARS[@]}」の VAR の場合
する
  if [[ -z "${!VAR}" ]];それから
    echo "エラー: 必要な置換変数 ${VAR} が定義されていません。"
    出口1
  フィ
終わり

echo "必要な置換変数はすべて存在します。"

このステップをビルドパイプラインの先頭に置くことで、チームはエラーを早期に発見し、無駄な計算サイクルを削減し、他の開発者により役立つフィードバックを提供できます。

Cloud Build ワークフローへの統合

実際のワークフローでは、検証シェルスクリプトはインラインコマンドとして含めることも、バージョン管理された GCS バケットなどの安全な場所にある共有スクリプトファイルからインポートすることもできます。これは通常、cloudbuild.yaml ファイルの最初のステップです。

手順:
- 名前: 'gcr.io/cloud-builders/bash'
  エントリポイント: 'bash'
  引数: ['-c', './validate_vars.sh']

これにより、チームは次のことが可能になります。

CI 検証ロジックのバージョンを設定する
予想される変数に対する単一の信頼できる情報源を維持する
トリガー編集の試行錯誤を伴うノイズの多いデバッグサイクルを削減します。

強化された開発者エクスペリエンス

この検証スクリプトの導入はすぐに効果をもたらしました。

気付かない変数の欠落によるパイプラインの失敗が減少します。
不明瞭なログではなく、問題を直接示す、より明確なエラーメッセージ。
予想される変数に関する完全な専門知識を必要とせずに、既存の CI ワークフローを再利用する新しい開発者のオンボーディングが迅速化されます。

時間の経過とともに、一部のチームはバリデーターを拡張してオプションの変数を許可し、フォールバックを設定して、共有テンプレートの柔軟性をさらに高めました。他の人は、これを YAML スキーマ検証と組み合わせて、実行時に Cloudbuild.yaml パイプライン全体をリントしました。

新しいプロジェクトでのエラーの防止

今後のプロジェクトでこの問題が発生しないようにするには、次のベストプラクティスに従うことをお勧めします。

リポジトリの README または CI ガイドに必要な置換変数をすべて文書化します。
CI/CD ワークフローに追加されるすべての新しいテンプレートで検証スクリプトを使用します。
明確な命名規則を定義します(例: _ で始まる変数はカスタム置換が必要であることを意味します)。
必要に応じてビルドでデフォルト値を設定するか、スクリプトを通じてオプションの変数ロジックを提供します。

最終的な考え

SUBSTITUTION_VARIABLE_NOT_DEFINEDエラーは一見無害に見えるかもしれませんが、CI/CD の健全性と構成管理におけるより広範な問題を表しています。変数の検証をパイプラインのファーストクラスのコンポーネントとして扱うことで、自動化の実践が強化され、ビルドの失敗が減り、開発者の満足度が高まります。シンプルな検証スクリプトを導入することで、多くのチームがパイプラインのワークフローを合理化し、ダウンタイムとデバッグの労力を大幅に削減することができました。

FAQ: Cloud Build の置換変数と検証

Q: Cloud Build の置換変数とは何ですか?
置換変数は、cloudbuild.yaml ファイル内のプレースホルダーで、ビルドがトリガーされたときに実際の値に置き換えられます。これらの変数は、さまざまな環境または構成に合わせてビルドをカスタマイズするために使用されます。
Q: SUBSTITUTION_VARIABLE_NOT_DEFINED エラーが表示されるのはなぜですか?
このエラーは通常、YAML ファイル内で参照されている変数がビルドトリガーまたは環境を介して渡されず、実行時に未定義になっている場合に発生します。
Q: ビルドをトリガーするときに置換変数を提供するにはどうすればよいですか?
置換変数は、トリガーの設定時に Google Cloud Console 経由で渡すことも、 --substitutionsフラグを使用して gcloud CLI 経由で渡すこともできます。
Q: 置換変数のデフォルト値を設定できますか?
Cloud Build は YAML でのデフォルト値を直接サポートしていませんが、未定義の変数を処理するロジックをスクリプト化し、bash または Python スクリプトでプログラム的にフォールバックを割り当てることができます。
Q: 複数のプロジェクトにわたって変数の存在を強制する最善の方法は何ですか?
すべてのcloudbuild.yamlテンプレートの先頭で共有検証スクリプトを使用して、一貫性を確保し、ビルドジョブを続行する前に入力を検証します。