変数値の置換

ビルド構成ファイルで substitutions を使用して、ランタイムで特定の変数を置換します。置換はビルド時まで値が不明な変数を設定する場合や、既存のビルド リクエストを別の変数値で再利用する場合に役立ちます。

Cloud Build には組み込みの置換が用意されていますが、独自の置換を定義することもできます。ビルド時に値を解決するには、ビルドの stepsimages フィールドに substitutions フィールドを使用します。

このページでは、デフォルトの置換を使用する方法や独自の substitutions を定義する方法について説明します。

デフォルトの置換の使用

Cloud Build では、次のデフォルトの置換が用意されています。

  • $PROJECT_ID: build.ProjectId
  • $BUILD_ID: build.BuildId
  • $COMMIT_SHA: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha(トリガーされたビルドでのみ使用可能)
  • $SHORT_SHA: COMMIT_SHA の先頭 7 文字(トリガーされたビルドでのみ使用可能)
  • $REPO_NAME: build.Source.RepoSource.RepoName(トリガーされたビルドでのみ使用可能)
  • $BRANCH_NAME: build.Source.RepoSource.Revision.BranchName(トリガーされたビルドでのみ使用可能)
  • $TAG_NAME: build.Source.RepoSource.Revision.TagName(トリガーされたビルドでのみ使用可能)
  • $REVISION_ID: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha(トリガーされたビルドでのみ使用可能)

デフォルトの置換が利用できない場合は(ソースがないビルドや、ストレージ ソースを使用しているビルドなど)、置換されなかった不明な変数が空の文字列に置き換えられます。

gcloud builds submit を使用してビルドを開始するとき、--substitutions 引数を使用して、トリガーされたビルドから通常取得する変数を指定できます。具体的には、次の値を手動で指定できます。

  • $REPO_NAME
  • $BRANCH_NAME
  • $TAG_NAME
  • $REVISION_ID
  • $COMMIT_SHA
  • $SHORT_SHA

たとえば、次のコマンドでは TAG_NAME 置換を使用しています。

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

次の例では、デフォルトの置換 $BUILD_ID$PROJECT_ID$REVISION_ID を使用しています。

YAML

steps:
# Uses the ubuntu build step:
# to run a shell script; and
# set env variables for its execution
- name: 'ubuntu'
  args: ['bash', './myscript.sh']
  env:
  - 'BUILD=$BUILD_ID'
  - 'PROJECT=$PROJECT_ID'
  - 'REV=$REVISION_ID'

# Uses the docker build step to build an image called my-image
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.']

# my-image is pushed to Container Registry
images:
- 'gcr.io/$PROJECT_ID/my-image'

JSON

{
  "steps": [{
      "name": "ubuntu",
      "args": [
        "bash",
        "./myscript.sh"
      ],
      "env": [
        "BUILD=$BUILD_ID",
        "PROJECT=$PROJECT_ID",
        "REV=$REVISION_ID"
      ]
    }, {
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/my-image"
  ]
}

次の例に、docker ビルドステップを使用してイメージを作成し、デフォルトの $PROJECT_ID 置換を使用して Container Registry にイメージを push するビルド リクエストを示します。

この例では、

  • ビルド リクエストのビルドステップは 1 つで、gcr.io/cloud-buildersdocker ビルドステップを使用して Docker イメージをビルドします。
    • ステップ内の args フィールドは docker コマンドに渡す引数を指定します。この場合は、build -t gcr.io/my-project/cb-demo-img . が呼び出されます($PROJECT_ID がプロジェクト ID に置き換えられた後)。
  • images フィールドにはイメージの名前が含まれます。ビルドが成功すると、ビルドされたイメージは Container Registry に push されます。イメージがビルドによって正常に作成されていない場合、ビルドは失敗します。

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
images:
- gcr.io/$PROJECT_ID/cb-demo-img

JSON

{
  "steps": [{
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/cb-demo-img"
  ]
}

ユーザー定義の置換の使用

独自の置換を定義することもできます。ユーザー定義の置換は、次のルールに従う必要があります。

  • 置換はアンダースコア(_)で始まり、大文字と数字のみを使用する必要があります(正規表現 _[A-Z0-9_]+ に従います)。こうすると、組み込み置換と競合しなくなります。
  • テンプレート内に一致しないキーがあると、エラーが発生します(たとえば、ビルド リクエストに $_FOO が含まれていて、置換マップで _FOO が定義されていない場合)。
  • パラメータ リスト内に一致しないキーがあると、エラーが発生します(たとえば、置換マップで _FOO が定義されているものの、ビルド リクエストに $_FOO が含まれていない場合)。
  • パラメータの数は 100 パラメータに制限されています。パラメータキーの長さとパラメータ値の長さは 100 文字に制限されています。

変数は、3 つの方法($_FOO${_FOO}$$_FOO)のいずれかで定義できます。

  • $_FOO${_FOO} はどちらも _FOO の値に評価されます。ただし、${} は空白なしで置換処理を行うため、${_FOO}BAR などの置換が可能です。
  • $$_FOO では、テンプレートにリテラル変数を含めることができます。つまり $$_FOO は、_FOO の値が後に続くリテラル文字 $ に評価されます。

置換を使用するには、gcloud コマンドで --substitutions 引数を使用するか、構成ファイルで置換を指定します。

次の例に、_NODE_VERSION_1_NODE_VERSION_2 という 2 つのユーザー定義の置換があるビルド構成を示します。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_1}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
         '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_2}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}',
         '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

JSON

{
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_1}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
            "."
        ]
    }, {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_2}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}",
            "."
        ]
    }],
    "substitutions": {
        "_NODE_VERSION_1": "v6.9.1"
        "_NODE_VERSION_1": "v6.9.2"
    },
    "images": [
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}"
    ]
}

ビルド構成ファイルで指定した置換値をオーバーライドするには、gcloud builds submit コマンドの --substitutions フラグを使用します。置換は、配列やシーケンスではなく、値への変数のマッピングであることに注意してください。次のコマンドは、上記のビルド構成ファイルで指定されている _NODE_VERSION_1 のデフォルト値をオーバーライドします。

gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .

デフォルトでは、置換変数や置換がない場合、ビルドでエラーが返されます。ただし、ALLOW_LOOSE オプションを設定すると、このチェックをスキップできます。

次のスニペットは「hello world」を出力し、未使用の置換を定義します。ALLOW_LOOSE 置換オプションが設定されているため、置換が欠落していてもビルドは成功します。

YAML

steps:
- name: 'ubuntu'
  args: ['echo', 'hello world']
substitutions:
    _SUB_VALUE: unused
options:
    substitution_option: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "unused"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

次のステップ

フィードバックを送信...