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

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

始める前に

• Cloud Build のビルド構成を使用してビルドを行うには、ビルド構成ファイルを作成します。
• アプリケーションのソースコードと Dockerfile を用意します。
• Artifact Registry にイメージを保存するための Docker リポジトリがあるか、リポジトリを作成します。

必要な IAM 権限

ビルドの送信に必要な権限を取得するには、サービス アカウントに対する次の IAM ロールを付与するよう管理者に依頼します。

• ビルドログをデフォルトのログバケットに保存する: Cloud Build 編集者 （roles/cloudbuild.builds.editor）
• ユーザーが作成したログバケットにビルドログを保存する: Cloud Build 編集者 （roles/cloudbuild.builds.editor）
• プライベート プールを使用する: Cloud Build WorkerPool ユーザー （roles/cloudbuild.workerPoolUser）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ビルドの実行

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

storage_source でビルドを送信する

gcloud

Dockerfile の使用:

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

Dockerfile を使用してビルドするには、ソースコードと Dockerfile が格納されているディレクトリから次のコマンドを実行します。

gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME

ここで

• LOCATION: Artifact Registry の Docker リポジトリのリージョンまたはマルチリージョン ロケーション。
• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• REPOSITORY: Artifact Registry リポジトリの名前
• IMAGE_NAME: ビルドするコンテナ イメージの名前。

ビルドするイメージの完全名は LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME です。Artifact Registry に push されるイメージは、Artifact Registry の命名規則を使用します。

gcloud builds submit コマンド:

• . で参照される現在のディレクトリ内のアプリケーション コード、Dockerfile、その他のすべてのアセットを圧縮します。
• アップロードされたファイルを入力として使用して、ロケーション LOCATION でビルドを開始します。
• 指定された名前を使用してイメージをタグ付けします。
• ビルドされたイメージを Artifact 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 --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 --config cloudbuild.yaml \
        gs://BUCKET/SOURCE.tar.gz

ここで

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

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

    gcloud builds submit --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",
               "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
               "."
           ]
       }],
       "images": [
           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
       ]
   }
   

   ここで

   • BUCKET は、ビルドするソースコードを含む Cloud Storage バケットの名前です。
   • SOURCE は、圧縮されたソースコード ファイルの名前です。
   • IMAGE_NAME は、ビルドされるイメージの名前です
   • LOCATION: Artifact Registry の Docker リポジトリのリージョンまたはマルチリージョン ロケーション。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
   • REPOSITORY: Artifact Registry の Docker リポジトリの名前。
   注: ビルド時に、Cloud Build が自動的に $PROJECT_ID をプロジェクト ID に置き換えます。

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

   ビルドするイメージの完全名は LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY です。

   Artifact Registry に push されるイメージは、Artifact Registry の命名規則を使用します。

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
   

   このコマンドでは、curl が projects.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",
                           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
                           "."
                       ]
                   }
                   ],
                   "timeout": "600s",
                   "images": [
                       "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/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 LOCATION 

ここで

• LOCATION は、Artifact Registry の Docker リポジトリのリージョンまたはマルチリージョンのロケーションです。
• REPOSITORY は、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にアップロードされ、ビルドが実行されます。ディレクトリ内の特定のファイルを除外する場合は、最上位のアップロード ディレクトリに .gcloudignore という名前のファイルを含めることができます。それにより指定されるファイルが無視されます。トップレベルのアップロード ディレクトリに .gcloudignore ファイルが存在せず、.gitignore ファイルが存在する場合、.gitignore で指定されるファイルに基づく Git 互換の .gcloudignore ファイルが、gcloud CLI により生成されます。詳細については、gcloudignore のドキュメントをご覧ください。

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

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

API

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

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

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

   ここで

   • REPOSITORY は、Cloud Build 第 2 世代リポジトリの名前（形式は projects/*/locations/*/connections/*repositories/*）です。
   • REVISION は、ブランチ、タグ、commit SHA、または任意の Git 参照などの Git リポジトリから取得するリビジョンです。
   • IMAGE_NAME は、ビルドされるイメージの名前です
   • LOCATION: Artifact Registry の Docker リポジトリのリージョンまたはマルチリージョン ロケーション。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
   注: ビルド時に、Cloud Build が自動的に $PROJECT_ID をプロジェクト ID に置き換えます。

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

   ビルドするイメージの完全名は LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME です。 Artifact Registry に push されるイメージは、Artifact Registry の命名規則を使用します。

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
   

   このコマンドでは、curl が projects.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",
                           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
                           "."
                       ]
                   }
                   ],
                   "timeout": "600s",
                   "images": [
                       "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/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 ステータスはビルドが実行を待機している状態であることを示しています。

次のステップ

• 手動トリガーの作成方法を学習する。
• ビルド結果を表示する方法を学習する。
• ビルドエラーをトラブルシューティングする方法について学習する。