CLI と API を使用してビルドを送信する

このページでは、Google Cloud CLI と Cloud Build API を使用して Cloud Build でビルドを手動で開始する方法について説明します。

始める前に

  • このガイドのコマンドラインの例を使用する場合は、Google Cloud CLI をインストールします。
  • Cloud Build のビルド構成を使用してビルドを行うには、ビルド構成ファイルを作成します。
  • Dockerfile を使用してビルドするには、Dockerfile を準備します。
  • ビルドでソースコードが必要な場合は、ソースコードを準備します。

必要な IAM 権限

IAM ロールを付与する方法については、Cloud Build リソースへのアクセスを構成するをご覧ください。

ビルドの実行

[Build source] フィールドを使用してビルドのソースを指定できます。[Build source] フィールドは、storage_sourcerepo_sourcegit_sourceconnected_repository のいずれかです。

storage_source でビルドを送信する

gcloud

Dockerfile の使用:

Dockerfile には、Cloud Build で Docker イメージをビルドするために必要な情報がすべて記載されています。

Dockerfile を使用してビルド リクエストを実行するには、アプリケーション コード、Dockerfile、その他のアセットが存在するディレクトリから次のコマンドを実行します。

gcloud builds submit --region=us-west2 --tag gcr.io/PROJECT_ID/IMAGE_NAME .

ここで

  • PROJECT_ID は Google Cloud プロジェクトの名前です。
  • IMAGE_NAME は、ビルドするイメージです。
  • . は、ソースコードが現在の作業ディレクトリにあることを指定します。

ビルドするイメージの完全名は gcr.ioPROJECT_ID/IMAGE_NAME です。Container Registry に push されるイメージは、レジストリ名の形式を使用します。

gcloud builds submit コマンド:

  • . で参照される現在のディレクトリ内のアプリケーション コード、Dockerfile、その他のすべてのアセットを圧縮します。
  • ファイルを Cloud Storage バケットにアップロードします。
  • アップロードされたファイルを入力として使用して、ロケーション us-west2 でビルドを開始します。
  • 指定された名前を使用してイメージをタグ付けします
  • ビルドされたイメージを Container Registry に push します。

ビルドの進行中は、出力がシェルまたはターミナル ウィンドウに表示されます。ビルドが完了すると、次のような出力が表示されます。

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

ここで、$BUILD_ID はビルドの一意の識別子です。

Cloud Build のビルド構成ファイルの使用:

ビルド構成を使用してビルドを送信するには、次のコマンドを実行します。

    gcloud builds submit --region=us-west2 --config BUILD_CONFIG SOURCE

ここで

  • BUILD_CONFIG は、ビルド構成ファイルへのパスです。
  • SOURCE は、パスまたは URL のソースコードです。

Google Cloud プロジェクトで初めて gcloud builds submit を実行すると、Cloud Build はそのプロジェクトに [YOUR_PROJECT_NAME]_cloudbuild という名前の Cloud Storage バケットを作成します。Cloud Build はこのバケットを使用して、ビルドに使用するソースコードを保存します。Cloud Build は、このバケット内のコンテンツを自動的に削除しません。ビルドで使用しなくなったオブジェクトを削除するには、バケットでライフサイクル構成を設定するか、手動でオブジェクトを削除します。

次のコマンドは、Cloud Storage バケットに保存されているソースコードを使用して cloudbuild.yaml ビルド リクエストを送信する方法を示しています。

    gcloud builds submit --region=us-west2 --config cloudbuild.yaml \
        gs://BUCKET/SOURCE.tar.gz

ここで

  • BUCKET は、ビルドするソースコードを含む Cloud Storage のバケットの名前です。
  • SOURCE は圧縮されたソースコード ファイルの名前です。

. を使用すると、ソースコードが現在の作業ディレクトリにあることを指定できます。

    gcloud builds submit --region=us-west2 --config=cloudbuild.yaml .

API

を使用してビルド リクエストを送信curlするには:

  1. 次の内容のファイルを request.json という名前で作成します。

    {
        "source": {
            "storageSource": {
                "bucket": "BUCKET",
                "object": "SOURCE.tar.gz"
            }
        },
        "steps": [{
            "name": "gcr.io/cloud-builders/docker",
            "args": [
                "build",
                "-t",
                "gcr.io/PROJECT_ID/IMAGE_NAME",
                "."
            ]
        }],
        "images": [
            "gcr.io/PROJECT_ID/IMAGE_NAME"
        ]
    }
    

    ここで

    • BUCKET は、ビルドするソースコードを含む Cloud Storage バケットの名前です。
    • SOURCE は圧縮されたソースコード ファイルの名前です。
    • IMAGE_NAME は、ビルドされるイメージの名前です

    このビルド リクエストで、Cloud Build は build -t gcr.io/$PROJECT_ID/IMAGE-NAME . 引数を使用して docker ビルドステップを呼び出します。

    ビルドするイメージの完全名は gcr.io/$PROJECT_ID/IMAGE_NAME です。

    Container Registry に push されるイメージは、レジストリ名の形式を使用します。

  2. 次のコマンドを実行します。ここで PROJECT_ID は Google Cloud プロジェクト ID、REGIONサポートされているリージョンのいずれかです。

    curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
        --format='value(credential.access_token)')" \
        https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds
    

    このコマンドでは、curlprojects.builds.create API メソッドの builds エンドポイントに対する POST 呼び出しで request.json を送信します。

    このコマンドは、ビルドの詳細をシェルまたはターミナル ウィンドウに表示します。出力は JSON レスポンスになり、次のように表示されます。

        {
            "name": "operations/build/$PROJECT-ID/NmZhZW...",
            "metadata": {
                "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
                "build": {
                    "id": $BUILD-ID,
                    "status": "QUEUED",
                    "source": {
                        "storageSource": {
                            "bucket": "BUCKET",
                            "object": "SOURCE.tar.gz"
                        }
                    },
                    "createTime": "2017-05-12T18:58:07.341526Z",
                    "steps": [
                    {
                        "name": "gcr.io/cloud-builders/docker",
                        "args": [
                            "build",
                            "-t",
                            "gcr.io/PROJECT_ID/IMAGE_NAME",
                            "."
                        ]
                    }
                    ],
                    "timeout": "600s",
                    "images": [
                        "gcr.io/$PROJECT_ID/IMAGE_NAME"
                    ],
                    "projectId": $PROJECT-ID,
                    "logsBucket": "gs://...",
                    "sourceProvenance": {
                        "resolvedStorageSource": {
                            "bucket": "BUCKET",
                            "object": "SOURCE.tar.gz"
                            "generation": "..."
                        }
                    },
                    "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=$PROJECT_ID"
                }
            }
        }
    

    JSON レスポンスは、Cloud Build API の Operation リソースを使用してモデル化されます。metadata フィールドは、Build リソースを使用してモデル化されます。QUEUED ステータスはビルドが実行を待機している状態であることを示しています。

connected_repository でビルドを送信する

gcloud

第 2 世代のリポジトリ リソースからビルドソースを使用してビルド リクエストを実行するには、次のコマンドを実行します。

gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG --region=us-west2

ここで

  • REPOSITORY は、Google Cloud Build の第 2 世代リポジトリの名前(形式は projects/*/locations/*/connections/*repositories/*)です。
  • REVISION は、ブランチ、タグ、commit SHA、または任意の Git 参照などの Git リポジトリから取得するリビジョンです。
  • BUILD_CONFIG は、ビルド構成ファイルへのパスです。

ビルドの進行中は、出力がシェルまたはターミナル ウィンドウに表示されます。ビルドが完了すると、次のような出力が表示されます。

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

ここで、$BUILD_ID はビルドの一意の識別子です。

gcloudignore: 上記のコマンドで、ビルドのソースコードを含めると、指定されたディレクトリにあるすべてのファイルが Google Cloud Platform にアップロードされ、ビルドが実行されます。ディレクトリ内の特定のファイルを除外する場合は、最上位のアップロード ディレクトリに .gcloudignore という名前のファイルを含めることができます。それにより指定されるファイルが無視されます。トップレベルのアップロード ディレクトリに存在するファイルが .gcloudignore ではなく .gitignore の場合は、.gitignore で指定されるファイルに基づく Git 互換の .gcloudignore ファイルが、gcloud CLI によって生成されます。詳細については、gcloudignore のドキュメントをご覧ください。

ビルドに渡すソースコードがない場合は、--no-source フラグを使用します。BUILD_CONFIG はビルド構成ファイルのパスです。

    gcloud builds submit --region=us-west2 --config=BUILD_CONFIG --no-source

API

を使用してビルド リクエストを送信curlするには:

  1. 次の内容のファイルを request.json という名前で作成します。

    {
        "source": {
            "connectedRepository": {
                "repository": "REPOSITORY",
                "revision": "REVISION"
            }
        },
        "steps": [{
            "name": "gcr.io/cloud-builders/docker",
            "args": [
                "build",
                "-t",
                "gcr.io/PROJECT_ID/IMAGE_NAME",
                "."
            ]
        }],
        "images": [
            "gcr.io/PROJECT_ID/IMAGE_NAME"
        ]
    }
    

    ここで

    • REPOSITORY は、Google Cloud Build の第 2 世代リポジトリの名前(形式は projects/*/locations/*/connections/*repositories/*)です。
    • REVISION は、ブランチ、タグ、commit SHA、または任意の Git 参照などの Git リポジトリから取得するリビジョンです。
    • IMAGE_NAME は、ビルドされるイメージの名前です

    このビルド リクエストで、Cloud Build は build -t gcr.io/PROJECT_ID/IMAGE_NAME . 引数を使用して docker ビルドステップを呼び出します。

    ビルドするイメージの完全名は gcr.io/PROJECT_ID/IMAGE_NAME です。 Container Registry に push されるイメージは、レジストリ名の形式を使用します。

  2. 次のコマンドを実行します。ここで PROJECT_ID は Google Cloud プロジェクト ID、REGIONサポートされているリージョンのいずれかです。

    curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
        --format='value(credential.access_token)')" \
        https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds
    

    このコマンドでは、curlprojects.builds.create API メソッドの builds エンドポイントに対する POST 呼び出しで request.json を送信します。

    このコマンドは、ビルドの詳細をシェルまたはターミナル ウィンドウに表示します。出力は JSON レスポンスになり、次のように表示されます。

        {
            "name": "operations/build/$PROJECT-ID/NmZhZW...",
            "metadata": {
                "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
                "build": {
                    "id": $BUILD-ID,
                    "status": "QUEUED",
                    "source": {
                        "connectedRepository": {
                            "repository": "REPOSITORY",
                            "revision": "REVISION"
                        }
                    },
                    "createTime": "2017-05-12T18:58:07.341526Z",
                    "steps": [
                    {
                        "name": "gcr.io/cloud-builders/docker",
                        "args": [
                            "build",
                            "-t",
                            "gcr.io/PROJECT_ID/IMAGE_NAME",
                            "."
                        ]
                    }
                    ],
                    "timeout": "600s",
                    "images": [
                        "gcr.io/PROJECT_ID/IMAGE_NAME"
                    ],
                    "projectId": PROJECT_ID,
                    "logsBucket": "gs://...",
                    "sourceProvenance": {
                        "resolvedConnectedRepository": {
                            "repository": "REPOSITORY",
                            "revision": "REVISION.tar.gz"
                            "generation": "..."
                        }
                    },
                    "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=PROJECT_ID"
                }
            }
        }
    

    JSON レスポンスは、Cloud Build API の Operation リソースを使用してモデル化されます。metadata フィールドは、Build リソースを使用してモデル化されます。QUEUED ステータスはビルドが実行を待機している状態であることを示しています。

次のステップ