ビルド構成ファイルのスキーマ

ビルド構成ファイルには、Cloud Build が指定に基づいてタスクを実行するための指示が記述されています。たとえば、ビルド構成ファイルには、Docker イメージのビルド、パッケージ化、push を行う手順を設定できます。

このページでは、Cloud Build 構成ファイルのスキーマについて説明します。 ビルド構成ファイルの作成と使用方法については、基本的なビルド構成ファイルの作成をご覧ください。

ビルド構成ファイルの構造

ビルド構成ファイルは、Cloud Build API の Build リソースを使用してモデル化されます。

ビルド構成ファイルは YAML または JSON 構文で記述します。curl などのサードパーティの http ツールを使用してビルド リクエストを送信する場合は、JSON 構文を使用します。

注: VS Code または IntelliJ IDE を使用している場合は、Cloud Code を使用して YAML 構成ファイルを作成できます。Cloud Code は Cloud Shell エディタに組み込まれており、設定は必要ありません。詳しくは、Cloud Code for VS Code と Cloud Code for IntelliJ をご覧ください。

ビルド構成ファイルの構造は次のとおりです。

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  allowFailure: boolean
  allowExitCodes: [string (int64 format), string (int64 format), ...]
  dir: string
  id: string
  waitFor: [string, string, ...]
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
  script: string
- name: string
  ...
- name: string
  ...
timeout: string (Duration format)
queueTtl: string (Duration format)
logsBucket: string
options:
 env: [string, string, ...]
 secretEnv: string
 volumes: object(Volume)
 sourceProvenanceHash: enum(HashType)
 machineType: enum(MachineType)
 diskSizeGb: string (int64 format)
 substitutionOption: enum(SubstitutionOption)
 dynamicSubstitutions: boolean
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
 defaultLogsBucketBehavior: enum(DefaultLogsBucketBehavior)
 pool: object(PoolOption)
 requestedVerifyOption: enum(RequestedVerifyOption)
substitutions: map (key: string, value: string)
tags: [string, string, ...]
serviceAccount: string
secrets: object(Secret)
availableSecrets: object(Secrets)
artifacts: object(Artifacts)
  mavenArtifacts: [object(MavenArtifact), ...]
  pythonPackages: [object(PythonPackage), ...]
  npmPackages: [object(npmPackage), ...]
images:
- [string, string, ...]

JSON

{
    "steps": [
    {
        "name": "string",
        "args": [
            "string",
            "string",
            "..."
        ],
        "env": [
            "string",
            "string",
            "..."
        ],
        "allowFailure": "boolean",
        "allowExitCodes: [
            "string (int64 format)",
            "string (int64 format)",
            "..."
        ],
        "dir": "string",
        "id": "string",
        "waitFor": [
            "string",
            "string",
            "..."
        ],
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)",
        "script" : "string"
    },
    {
        "name": "string"
        ...
    },
    {
        "name": "string"
        ...
    }
    ],
    "timeout": "string (Duration format)",
    "queueTtl": "string (Duration format)",
    "logsBucket": "string",
    "options": {
        "sourceProvenanceHash": "enum(HashType)",
        "machineType": "enum(MachineType)",
        "diskSizeGb": "string (int64 format)",
        "substitutionOption": "enum(SubstitutionOption)",
        "dynamicSubstitutions": "boolean",
        "logStreamingOption": "enum(LogStreamingOption)",
        "logging": "enum(LoggingMode)"
        "defaultLogsBucketBehavior": "enum(DefaultLogsBucketBehavior)"
        "env": [
            "string",
            "string",
            "..."
        ],
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "pool": "object(PoolOption)"
        "requestedVerifyOption": "enum(RequestedVerifyOption)"
    },
    "substitutions": "map (key: string, value: string)",
    "tags": [
        "string",
        "string",
        "..."
    ],
    "serviceAccount": "string",
    "secrets": "object(Secret)",
    "availableSecrets": "object(Secrets)",
    "artifacts": "object(Artifacts)",
      "mavenArtifacts": ["object(MavenArtifact)", ...],
      "pythonPackages": ["object(PythonPackage)", ...],
      "npmPackages": ["object(npmPackage)", ...],
    "images": [
        "string",
        "string",
        "..."
    ]
}

ビルド構成ファイルの各セクションに、Cloud Build に実行させるタスクの一部を定義します。

ビルドステップ

ビルドステップには、Cloud Build に実行させるアクションを指定します。ビルドステップごとに、Cloud Build は docker run のインスタンスとして Docker コンテナを実行します。ビルドステップは、スクリプトの中のコマンドによく似ており、ビルドにおいて任意の命令を実行する柔軟性を提供します。ビルドツールをコンテナにパッケージ化することができる場合、Cloud Build はビルドの一部としてそれを実行できます。Cloud Build はデフォルトで、同じマシン上でビルドのすべてのステップを連続して実行します。同時に実行できるステップがある場合は、waitFor オプションを使用します。

構成ファイルには、最大 300 のビルドステップを含めることができます。

ビルド構成ファイルの steps フィールドを使用してビルドステップを指定します。steps フィールドで構成するスニペットは次のとおりです。

YAML

steps:
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/mydepl', 'my-image=gcr.io/my-project/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image"
            "deployment/mydepl"
            "my-image=gcr.io/my-project/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east4-b",
            "CLOUDSDK_CONTAINER_CLUSTER=my-cluster"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

name

ビルドステップの name フィールドは、クラウド ビルダーを指定するために使用します。これは、一般的なツールを実行するコンテナ イメージです。ビルドステップの中でビルダーを使用して、タスクを実行します。

次のスニペットは、bazel、gcloud、docker の各ビルダーを呼び出すビルドステップを示しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/bazel'
...

- name: 'gcr.io/cloud-builders/gcloud'
...

- name: 'gcr.io/cloud-builders/docker'
...

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/bazel"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/gcloud"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/docker"
        ...
    }
    ]
}

args

ビルドステップの args フィールドには、引数のリストが入れられます。引数は、name フィールドによって参照されるビルダーに渡されます。ビルダーに渡された引数は、ビルダーで実行されているツールに渡されます。これにより、ツールでサポートされているどのコマンドも呼び出すことができます。ビルドステップで使用されるビルダーにエントリポイントがある場合、そのエントリポイントへの引数として args が使用されます。ビルダーでエントリポイントが定義されていない場合、args の最初の要素がエントリポイントとして使用され、残りが引数として使用されます。

1 つのステップに最大 100 個の引数を作成できます。引数の最大長は 10,000 文字です。

次のスニペットは、docker build コマンドを呼び出し、Maven の依存関係をインストールします。

YAML

steps:
- name: 'gcr.io/cloud-builders/mvn'
  args: ['install']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/mvn",
        "args": [
            "install"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

env

ビルドステップの env フィールドには、ステップ実行時に使用される環境変数のリストが入れられます。変数の形式は KEY=VALUE です。

次のビルド構成では、ビルドステップの env フィールドは、kubectl の実行前に Compute Engine ゾーンと GKE クラスタを設定します。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/myimage', 'frontend=gcr.io/myproject/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east1-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image",
            "deployment/myimage",
            "frontend=gcr.io/myproject/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east1-b",
            "CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster"
        ]
    }
    ]
}

dir

ビルドステップの dir フィールドは、ステップ実行時に使用する作業ディレクトリを設定するために使用します。dir フィールドをビルドステップに設定すると、作業ディレクトリは /workspace/<dir> に設定されます。この値が相対パスの場合、ビルドの作業ディレクトリを基準とする相対パスになります。この値が絶対パスの場合、ビルドの作業ディレクトリ外の可能性があります。その場合、パスの内容はビルドステップ実行の間に変化する可能性があります（そのパスのボリュームが指定されていない場合）。

次のコード スニペットでは、ビルドステップの作業ディレクトリが /workspace/examples/hello_world として設定されます。

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
  env: ['PROJECT_ROOT=hello']
  dir: 'examples/hello_world'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ],
        "dir": "examples/hello_world"
    }
    ]
}

timeout

ビルドステップの timeout フィールドは、ステップを実行するための制限時間を設定するために使用します。このフィールドを設定しない場合、ステップには制限時間がなく、完了するかビルド自体がタイムアウトするまで実行が許可されます。ビルドステップの timeout フィールドは、ビルドに指定された timeout 値を超えないようにする必要があります。timeout は小数 9 桁まで、「s」で終わる秒単位に指定する必要があります。例: 3.5s

次のビルド構成では、500 秒後に ubuntu ステップがタイムアウトします。

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
  timeout: 500s
- name: 'ubuntu'
  args: ['echo', 'hello world, after 600s']

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ],
        "timeout": "500s"
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world, after 600s"
        ]
    }
    ]
}

注: timeout フィールドは、ビルドステップとビルドの両方に対して存在します。ビルドステップの timeout フィールドはビルドステップの実行に許可される時間、ビルドの timeout フィールドはビルドの実行に許可される時間を指定します。

スクリプト

ビルドステップの script フィールドは、ステップで実行するシェル スクリプトを指定するために使用します。ビルドステップで script を指定する場合、同じステップで args や entrypoint を指定することはできません。script フィールドの使用については、bash スクリプトの実行をご覧ください。

id

id フィールドは、ビルドステップに対して一意の識別子を設定するために使用します。id は、ビルドステップの実行順序を構成するために waitFor フィールドとともに使用されます。waitFor と id の使用方法については、ビルドステップの順序の構成をご覧ください。

waitFor

ビルドステップで waitFor フィールドを使用して、そのビルドステップの前に実行する必要のあるステップを指定します。waitFor の値が指定されない場合、ビルドステップは、ビルド リクエスト内の先行するすべてのビルドステップが正常に完了するまで待機した後に実行されます。waitFor と id の使用方法については、ビルドステップの順序の構成をご覧ください。

entrypoint

ビルドステップの entrypoint は、ビルダーのデフォルトのエントリポイントを使用しない場合にエントリポイントを指定するために使用します。このフィールドを設定しない場合、Cloud Build ではビルダーのエントリポイントが使用されます。次のスニペットは、npm ビルドステップのエントリポイントを設定します。

YAML

steps:
- name: 'gcr.io/cloud-builders/npm'
  entrypoint: 'node'
  args: ['--version']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/npm",
        "entrypoint": "node",
        "args": [
            "--version"
        ]
    }
    ]
}

secretEnv

Cloud KMS 暗号鍵を使用して暗号化された環境変数のリスト。ビルドのシークレットでは、これらの値を指定する必要があります。このフィールドの使用方法については、暗号化された変数をビルド リクエストで使用するをご覧ください。

volumes

ボリュームは、ビルドステップにマウントされ、複数のビルドステップを通じてファイルを保持する Docker コンテナのボリュームです。Cloud Build がビルドステップを実行すると、workspace ボリュームが /workspace に自動的にマウントされます。ステップに対して volumes フィールドを使用することにより、ビルドステップのコンテナにマウントするボリュームを追加で指定できます。

たとえば、次のビルド構成ファイルでは、最初のステップでファイルをボリュームに書き込み、2 番目のステップでファイルを読み取ります。これらのステップで /persistent_volume パスが永続ボリュームとして指定されていない場合、最初のステップでそのパスにファイルが書き込まれ、そのファイルは 2 番目のステップの実行前に破棄されます。両方のステップで同じ名前のボリュームを指定すると、最初のステップの /persistent_volume の内容は 2 番目のステップに保持されます。

YAML

steps:
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
        echo "Hello, world!" > /persistent_volume/file
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  args: ['cat', '/persistent_volume/file']

JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "entrypoint": "bash",
        "args": [
          "-c",
          "echo \"Hello, world!\" > /persistent_volume/file\n"
        ]
      },
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "args": [
          "cat",
          "/persistent_volume/file"
        ]
     }
    ]
  }

allowFailure

ビルドステップで allowFailure フィールドの値を true に設定し、ビルドステップが失敗した場合、そのビルド内の他のすべてのビルドステップが成功している限り、ビルドは成功します。

ビルド内のすべてのビルドステップで allowFailure が true に設定されていて、すべてのビルドステップが失敗した場合、ビルドのステータスは引き続き Successful になります。

allowExitCodes はこのフィールドよりも優先されます。

次のコード スニペットで、最初のステップが失敗したときにビルドが成功するようにできます。

YAML

steps:
- name: 'ubuntu'
  args: ['-c', 'exit 1']
  allowFailure: true
steps:
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit -1"
        ],
        "allowFailure": true,
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

allowExitCodes

allowExitCodes フィールドを使って、ビルドステップが特定の終了コードを返すときにそのステップの失敗を無視するように指定します。

ビルドステップが allowExitCodes で指定した値と一致する終了コードで失敗すると、Cloud Build ではこのビルドステップが失敗になりますが、ビルド全体が失敗することはありません。

ビルドステップがすべて失敗しても、すべてのステップが allowExitCodes フィールドで指定したコードで終了した場合、ビルドは依然として成功しています。

ただし、ビルドステップが失敗して、別の終了コードが生成された場合（指定した値と一致しないコードが allowExitCodes にある場合）、ビルド全体が失敗します。

ビルドに関連する終了コードは、ソフトウェアによって異なります。たとえば、「1」は Linux での一般的な終了コードです。スクリプトで独自の終了コードを定義することもできます。allowExitCodes フィールドには、最大 255 までの数値を指定できます。

このフィールドは allowFailure よりも優先されます。

次のコード スニペットで、最初のステップが指定したいずれかの終了コードで失敗したときに、ビルドが成功するようにできます。

YAML

steps:
- name: 'ubuntu'
  args: ['-c', 'exit 1']
  allowExitCodes: [1]
steps:
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit 1"
        ],
        "allowExitCodes": [1],
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

timeout

ビルドの timeout フィールドは、このビルドの実行が許可される時間を、秒単位で指定するために使用します。この時間が経過すると、ビルドの処理が停止し、ビルドのステータスは TIMEOUT になります。timeout が設定されていない場合、ビルドには 60 分のデフォルト timeout が適用されます。timeout に適用できる最大値は 24 時間です。timeout は小数 9 桁まで、「s」で終わる秒単位に指定する必要があります。例: 3.5s

次のスニペットでは、sleep が原因でビルドがタイムアウトにならないようにするため、timeout を 660 秒に設定しています。

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
timeout: 660s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ]
    }
    ],
    "timeout": "660s"
}

注: timeout フィールドは、ビルドステップとビルドの両方に対して存在します。ビルドステップの timeout フィールドはビルドステップの実行に許可される時間、ビルドの timeout フィールドはビルドの実行に許可される時間を指定します。

queueTtl

queueTtl フィールドを使用して、ビルドをキューに入れられる時間を指定します。ビルドが queueTtl に設定された値よりも長くキューに入っている場合、ビルドは有効期限切れになり、ビルド ステータスは EXPIRED に設定されます。値が指定されていない場合、Cloud Build はデフォルト値である 3600s（1 時間）を使用します。queueTtl は createTime から時間の計測を開始します。queueTtl は小数 9 桁まで、「s」で終わる秒単位に指定する必要があります（例: 3.5s）。

次のスニペットでは、timeout が 20s に、queueTtl が 10s に設定されています。 queueTtl は、ビルドがリクエストされた時刻である createTime に時間の計測を開始します。timeout はビルドが開始される startTime に時間の計測を開始します。したがって、ビルドが開始されない限り、queueTtl は createTime + 10s で期限切れになります。

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '5']
timeout: 20s
queueTtl: 10s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "5"
        ]
    }
    ],
    "timeout": "20s",
    "queueTtl": "10s"
}

logsBucket

ビルドの logsBucket フィールドは、ログを書き込む必要がある Cloud Storage バケットを指定する場合に設定します。このフィールドを設定しない場合、Cloud Build では、ビルドログを保存するためにデフォルトのバケットが使用されます。

次のスニペットは、ビルドログを格納するログバケットを設定します。

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
logsBucket: 'gs://mybucket'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "logsBucket": "gs://mybucket"
}

options

フィールドは、ビルドに次のoptionsオプションの引数を指定するために使用します。

env: このビルドのすべてのビルドステップに存在するグローバル環境変数定義のリスト。変数がグローバルとビルドステップの両方で定義されている場合、変数はビルドステップ値を使用します。VALUE の値が与えられている環境変数 KEY の場合、要素の形式は KEY=VALUE です。

secretEnv: Cloud Key Management Service の暗号鍵を使用して暗号化されたグローバル環境変数のリスト。リストは、このビルドのすべてのビルドステップで使用できます。ビルドの Secret では、これらの値を指定する必要があります。

volumes: すべてのビルドステップでグローバルにマウントするボリュームのリスト。各ボリュームは、ビルドプロセスを開始する前に空のボリュームとして作成されます。ビルドが完了すると、ボリュームとその内容は破棄されます。グローバル ボリューム名とパスは、ビルドステップで定義したボリュームと競合できません。1 つのステップのみのビルドでグローバル ボリュームを使用すると、誤った構成でビルド リクエストが発生するため無効です。

sourceProvenanceHash: sourceProvenanceHash オプションには、ソースの場所に関するハッシュ アルゴリズムを指定します。次のスニペットは、ハッシュ アルゴリズムが SHA256 であることを示しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
    sourceProvenanceHash: ['SHA256']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "sourceProvenanceHash": ["SHA256"]
    }
}

machineType: Cloud Build には、ビルドを実行する 4 つの高 CPU 仮想マシンタイプが用意されています（CPU が 8 個のマシンタイプが 2 つ、CPU が 32 個のマシンタイプが 2 つ）。Cloud Build には、ビルドを実行する仮想マシンタイプがさらに 2 つ用意されています（CPU が 1 個のマシンタイプと CPU が 2 個のマシンタイプ）。デフォルトのマシンタイプは 2 個の CPU を備えた e2-standard-2 です。高 CPU 仮想マシンをリクエストすると、ビルドの起動時間が長くなる可能性があります。より高い CPU の仮想マシンをリクエストするには、machineType オプションを追加します。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 machineType: 'E2_HIGHCPU_8'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    ],
    "options": {
        "machineType": "E2_HIGHCPU_8"
    }
}

machineType オプションの使用方法について詳しくは、ビルドの高速化をご覧ください。

diskSizeGb: diskSizeGb オプションは、ビルドのカスタム ディスクサイズをリクエストする場合に使用します。リクエストできる最大サイズは 2,000 GB です。

次のスニペットでは、200 GB のディスクサイズをリクエストしています。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 diskSizeGb: '200'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "diskSizeGb": '200'
    }
}

logStreamingOption: ビルドログを Cloud Storage にストリーミングする場合、このオプションを使用します。デフォルトの場合、Cloud Build はビルド完了時にビルドログを収集します。このオプションには、ビルドプロセス全体をとおしてリアルタイムでビルドログをストリーミングするかどうかを指定します。次のスニペットは、ビルドログが Cloud Storage にストリーミングされることを示しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
options:
 logStreamingOption: STREAM_ON

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "options": {
        "logStreamingOption": "STREAM_ON"
    }
}

logging: Cloud Logging または Cloud Storage にログを保存するかどうかを指定します。このオプションを設定しない場合、Cloud Build は Cloud Logging と Cloud Storage の両方にログを保存します。logging オプションを GCS_ONLY に設定すると、Cloud Storage にのみログを保存できます。次のスニペットは、ログが Cloud Storage に保存されることを示しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 logging: GCS_ONLY

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "logging": "GCS_ONLY"
    }
}

defaultLogsBucketBehavior: defaultLogsBucketBehavior オプションを使用すると、ビルドと同じリージョンに独自のプロジェクト内にデフォルトのログバケットを作成するように Cloud Build を構成できます。詳細については、ユーザー所有のリージョン化されたバケットへのビルドログの保存をご覧ください。

次のビルド構成では、defaultLogsBucketBehavior フィールドを値 REGIONAL_USER_OWNED_BUCKET に設定しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
options:
  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
        "."
      ]
    }
    ],
    "options": {
      "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
    }
}

dynamic_substitutions: このオプションを使用して、置換で bash パラメータの拡張を明示的に有効または無効にします。トリガーによってビルドが呼び出された場合、dynamic_substitutions フィールドは常に true に設定され、ビルド構成ファイルで指定する必要はありません。ビルドを手動で呼び出す場合、ビルドの実行時に bash パラメータの拡張が解釈されるようにするには、dynamic_substitutions フィールドを true に設定する必要があります。

substitutionOption: このオプションは、置換チェックにエラーがある場合の動作を指定するために、下記の substitutions フィールドとともに設定します。

pool: このフィールドの値は、ビルドを実行するプライベート プールのリソース名に設定します。プライベート プールでビルドを実行する手順については、プライベート プールでのビルドの実行をご覧ください。

requestedVerifyOption: 証明書と来歴メタデータの世代を検証するには、requestedVerifyOption の値を VERIFIED に設定します。このオプションでは、リージョン ビルドとプライベート プール内のビルドの証明書と来歴メタデータも有効になります。requestedVerifyOption: VERIFIED を追加しない場合、Cloud Build はグローバル ビルドでのみ来歴を生成します。

substitutions

substitutions は、ビルド時に特定の変数を置き換える場合にビルド構成ファイルの中で使用します。置換はビルド時まで値が不明な変数を設定する場合や、既存のビルド リクエストを別の変数値で再利用する場合に役立ちます。デフォルトでは、置換変数や置換がない場合、ビルドでエラーが返されます。ただし、ALLOW_LOOSE オプションを使用すると、このチェックをスキップできます。

次のスニペットでは、「hello world」を出力するために置換が使用されています。ALLOW_LOOSE 置換オプションが設定されているため、置換変数や置換がない場合でも、ビルドでエラーが返されません。

YAML

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

JSON

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

注: ビルドがトリガーによって呼び出される場合は、デフォルトで ALLOW_LOOSE オプションが設定されます。この場合、置換変数または置換が欠落しているとビルドはエラーを返しません。トリガーによって呼び出されたビルドの ALLOW_LOOSE オプションをオーバーライドすることはできません。

substitutions の使用に関する追加の手順については、変数値の置換をご覧ください。

tags

tags フィールドは、複数のビルドをグループにまとめたり、ビルドをフィルタリングしたりする場合に使用します。次の構成では、mytag1 と mytag2 という名前の 2 つのタグを設定しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  ...
- name: 'ubuntu'
  ...
tags: ['mytag1', 'mytag2']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker"
    },
    {
        "name": "ubuntu"
    }
    ],
    "tags": [
        "mytag1",
        "mytag2"
    ]
}

availableSecrets

このフィールドを使用して、Cloud Build で Secret Manager のシークレットを使用します。詳細については、シークレットの使用をご覧ください。

secrets

シークレットは、値の復号に使用するため、暗号化された値を含むシークレット環境変数のセットと Cloud KMS 鍵とをペアにします。

注: secrets ではなく availableSecrets を使用します。詳細については、シークレットの使用と暗号化された認証情報の使用をご覧ください。

serviceAccount

このフィールドを使用して、ビルドで使用する IAM サービス アカウントを指定します。詳細については、ユーザー指定のサービス アカウントの構成をご覧ください。

images

ビルド構成ファイルの images フィールドには、Cloud Build が Artifact Registry または Container Registry（非推奨） に push する 1 つ以上の Linux Docker イメージを指定します。Linux Docker イメージを生成せずにタスクを実行するビルドがあるかもしれませんが、イメージをビルドしてレジストリにプッシュしない場合、イメージはビルド完了時に破棄されます。指定されたイメージがビルド時に生成されない場合、ビルドは失敗します。 イメージの保存について詳しくは、Artifact Registry にアーティファクトを保存するをご覧ください。

次のビルド構成では、ビルドされたイメージを保存するための images フィールドを設定しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
images: ['gcr.io/myproject/myimage']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "images": [
        "gcr.io/myproject/myimage"
    ]
}

artifacts

ビルド構成ファイルの artifacts フィールドには、Cloud Storage に保存する 1 つ以上のコンテナ以外のアーティファクトを指定します。コンテナ以外のアーティファクトを保存する詳細については、Cloud Storage へのビルド アーティファクトの保存をご覧ください。

次のビルド構成では、ビルドされた Go パッケージを gs://mybucket/ に保存するための artifacts フィールドを設定しています。

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['build', 'my-package']
artifacts:
  objects:
    location: 'gs://mybucket/'
    paths: ['my-package']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "build",
            "my-package"
        ]
    }
    ],
    "artifacts": {
      "objects": {
        "location": "gs://mybucket/",
        "paths": [
            "my-package"
        ]
      }
    }
}

mavenArtifacts

mavenArtifacts フィールドを使用すると、コンテナ以外の Java アーティファクトを Artifact Registry 内の Maven リポジトリにアップロードできます。詳細については、Java アプリケーションのビルドとテストをご覧ください。

次のビルド構成では、パッケージ化されたファイル my-app-1.0-SNAPSHOT.jar を Artifact Registry リポジトリ https://us-central1-maven.pkg.dev/my-project-id/my-java-repo にアップロードするための mavenArtifacts フィールドを設定しています。

YAML

artifacts:
  mavenArtifacts:
    - repository: 'https://us-central1-maven.pkg.dev/my-project-id/my-java-repo'
      path: '/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar'
      artifactId: 'my-app-1'
      groupId: 'com.mycompany.app'
      version: '1.0.0'

JSON

{
  "artifacts": {
    "mavenArtifacts": [
      {
        "repository": "https://us-central1-maven.pkg.dev/my-project-id/my-java-repo",
        "path": "/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar",
        "artifactId": "my-app-1",
        "groupId": "com.mycompany.app",
        "version": "1.0.0"
      }
    ]
  }
}

pythonPackages

pythonPackages フィールドを使用すると、Artifact Registry に Python パッケージをアップロードできます。詳細については、Python アプリケーションのビルドとテストをご覧ください。

次のビルド構成では、Python パッケージ dist/my-pkg.whl を Artifact Registry リポジトリ https://us-east1-python.pkg.dev/my-project/my-repo にアップロードするための pythonPackages フィールドを設定しています。

YAML

artifacts:
  pythonPackages:
   - repository: 'https://us-east1-python.pkg.dev/my-project/my-repo'
     paths: ['dist/my-pkg.whl']

JSON

{
  "artifacts": {
    "pythonPackages": [
      {
        "repository": "https://us-east1-python.pkg.dev/my-project/my-repo",
        "paths": ["dist/my-pkg.whl"]
      }
    ]
  }
}

npmPackages

npmPackages フィールドを使用して、ビルドした npm パッケージを Artifact Registry のサポートされているリポジトリにアップロードするように Cloud Build を構成します。repository と packagePath の値を指定する必要があります。

repository フィールドには、パッケージを保存する Artifact Registry リポジトリを指定します。packagePath フィールドには、アップロードする npm パッケージを含むローカル ディレクトリを指定します。このディレクトリには package.json ファイルが含まれている必要があります。

packagePath の値には絶対パスを使用することをおすすめします。. を使用して現在の作業ディレクトリを参照できますが、このフィールドは省略したり空のままにしたりすることはできません。npmPackages の使用の詳細については、Node.js アプリケーションのビルドとテストをご覧ください。

次のビルド構成では、/workspace/my-pkg ディレクトリ内の npm パッケージを Artifact Registry リポジトリ https://us-east1-npm.pkg.dev/my-project/my-repo にアップロードするように npmPackages フィールドを設定しています。

YAML

artifacts:
  npmPackages:
   - repository: 'https://us-east1-npm.pkg.dev/my-project/my-repo'
     packagePath: '/workspace/my-pkg'

JSON

{
  "artifacts": {
    "npmPackages": [
      {
        "repository": "https://us-east1-npm.pkg.dev/my-project/my-repo",
        "packagePath": "/workspace/my-pkg"
      }
    ]
  }
}

Dockerfile の使用

Cloud Build で gcloud CLI やビルドトリガーを使用して Docker ビルドを実行する場合は、個別のビルド構成ファイルなしで Dockerfile を使用します。Docker ビルドをさらに調整する場合は、Dockerfile の他にビルド構成ファイルを指定できます。Dockerfile を使用して Docker イメージをビルドする手順については、クイックスタート: ビルドをご覧ください。

Cloud Build ネットワーク

Cloud Build は、各ビルドステップを実行するときに、ステップのコンテナをローカルの Docker ネットワーク cloudbuild に接続します。cloudbuild ネットワークは、アプリケーションのデフォルト認証情報（ADC）をホストします。Google Cloud サービスは、この ADC を使用してユーザーの認証情報を自動的に検出します。ネストされた Docker コンテナを実行していて基になるコンテナに ADC を公開する場合、あるいは docker ステップで gsutil または gcloud を使用している場合は、Docker build ステップで --network フラグを使用します。

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '--network=cloudbuild', '.']

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "--network=cloudbuild",
        "."
      ]
   }
  ]
}

次のステップ

• Cloud Build のビルドを構成する基本的なビルド構成ファイルの作成方法を学習する。
• 手動でのビルドの開始を読み、Cloud Build でビルドを実行する方法を確認する。