ビルド構成の概要

このページでは、Cloud Build ビルド構成ファイルの構造について説明します。

Dockerfile とビルド構成ファイル

Cloud Build で、gcloud コマンドライン ツールまたはビルドトリガーを使用して非 Docker ビルドを実行する場合、ビルド構成ファイルを用意する必要があります。ビルド構成ファイルには、Cloud Build が指定に基づいてタスクを実行するための指示が記述されています。たとえば、ビルド構成ファイルには、Docker イメージのビルド、パッケージ化、push を行う手順を設定できます。

Docker ビルドを実行する場合、gcloud ツールまたはビルドトリガーを使用する場合は、Dockerfile またはビルド構成ファイルを使用してイメージをビルドできます。Dockerfile を使用して Docker イメージをビルドする手順については、Docker のクイックスタートをご覧ください。

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

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

ビルド構成ファイルは YAML または JSON 構文で記述します。curl などのサードパーティの http ツールを使用してビルド リクエストを送信する場合は、JSON 構文を使用します。ビルド構成ファイルはプロジェクトのルート ディレクトリに作成する必要があり、Cloud Build がビルドを開始するたびに読み込まれます。

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

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  dir: string
  id: string
  waitFor: string
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
- name: string
  ...
- name: string
  ...
timeout: 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)
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
substitutions: map (key: string, value: string)
tags: [string, string, ...]
secrets: object(Secret)
images:
- [string, string, ...]
artifacts: object (Artifacts)

JSON

{
    "steps": [
    {
        "name": "string",
        "args": [
        [
            "string",
            "string",
            "..."
        ]
        ],
        "env": [
        [
            "string",
            "string",
            "..."
        ]
        ],
        "dir": "string",
        "id": "string",
        "waitFor": "string",
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)"
    },
    {
        "name": "string"
        ...
    },
    {
        "name": "string"
        ...
    }
    ],
    "timeout": "string (Duration format)",
    "logsBucket": "string",
    "options": {
        "sourceProvenanceHash": "enum(HashType)",
        "machineType": "enum(MachineType)",
        "diskSizeGb": "string (int64 format)",
        "substitutionOption": "enum(SubstitutionOption)",
        "logStreamingOption": "enum(LogStreamingOption)",
        "logging": "enum(LoggingMode)"
        "env": [
        [
            "string",
            "string",
            "..."
        ]
        ],
        "secretEnv": "string",
        "volumes": "object(Volume)",
    },
    "substitutions": "map (key: string, value: string)",
    "tags": [
    [
        "string",
        "string",
        "..."
    ]
    ],
    "secrets": "object(Secret)",
    "images": [
    [
        "string",
        "string",
        "..."
    ]
    ],
    "artifacts": "object(Artifacts)"
}

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

ビルドステップ

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

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

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

YAML

steps:
- name: 'gcr.io/cloud-builders/git'
  args: ['clone', 'https://github.com/GoogleCloudPlatform/cloud-builders']
  env: ['PROJECT_ROOT=hello']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/git",
        "args": [
            "clone",
            "https://github.com/GoogleCloudPlatform/cloud-builders"
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

name

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

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

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 の最初の要素がエントリポイントとして使用され、残りが引数として使用されます。

次のスニペットは、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 フィールドは、ステップ実行時に使用する作業ディレクトリを設定するために使用します。デフォルトの場合、Cloud Build では /workspace という名前のディレクトリが作業ディレクトリとして使用されます。構成ファイルに複数のビルドステップが含まれる場合は、あるステップで生成されたアセットを /workspace ディレクトリの持続性を介して次のステップに渡すことができます。これにより、アセットを共有するビルドステップのパイプラインを設定できます。dir フィールドをビルドステップに設定すると、作業ディレクトリは /workspace/<dir> に設定されます。この値が相対パスの場合、ビルドの作業ディレクトリを基準とする相対パスになります。この値が絶対パスの場合、ビルドの作業ディレクトリ外の可能性があります。その場合、パスの内容はビルドステップ実行の間に変化する可能性があります(そのパスのボリュームが指定されていない場合)。

次のスニペットは、作業ディレクトリを 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 は小数 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"
        ]
    }
    ]
}

id

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

waitFor

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

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"
        ]
     }
    ]
  }

timeout

ビルドの timeout フィールドは、このビルドの実行が許可される時間を、秒単位で指定するために使用します。この時間が経過すると、ビルドの処理が停止し、ビルドのステータスTIMEOUT になります。timeout が設定されていない場合、ビルドには 10 分のデフォルト 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"
}

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 には、ビルドを実行する 2 つの高 CPU 仮想マシンタイプ(CPU 8 個、および CPU 32 個)が用意されています。デフォルトのマシンタイプは 1 CPU です。高 CPU 仮想マシンをリクエストすると、ビルドの起動時間が長くなる可能性があります。より高い CPU の仮想マシンをリクエストするには、machineType オプションを追加します。

YAML

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

JSON

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

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

diskSizeGb: diskSizeGb オプションは、ビルドのカスタム ディスクサイズをリクエストする場合に使用します。リクエストできる最大サイズは 1,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: このオプションを使用して、ログを Stackdriver Logging と Cloud Storage のどちらに保存するかを指定できます。このオプションを設定しない場合、Cloud Build は Stackdriver 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"
    }
}

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

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"
    }
}

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

tags

tags フィールドは、複数のビルドをグループにまとめたり、ビルドをフィルタリングしたりする場合に使用します。次の構成では、mytag1mytag2 という名前の 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"
    ]
}

secrets

シークレットは、値の復号に使用するため、暗号化された値を含むシークレット環境変数のセットと Cloud KMS 鍵とをペアにします。secrets フィールドは、Cloud KMS を使用して復号するシークレットを定義します。このフィールドの使用例については、暗号化されたシークレットと認証情報の使用をご覧ください。

イメージ

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

次のビルド構成では、ビルドされたイメージを保存するための 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 つ以上のコンテナ以外のアーティファクトを指定します。コンテナ以外のアーティファクトの保存について詳しくは、イメージとアーティファクトの保存をご覧ください。

次のビルド構成では、ビルドされた 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"
        ]
      }
    }
}

次のステップ

このページは役立ちましたか?評価をお願いいたします。

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

Cloud Build のドキュメント