本頁說明如何使用 Google Cloud CLI 和 Cloud Build API，在 Cloud Build 中手動啟動建構作業。
事前準備
- 如要使用 Cloud Build 建構設定進行建構，請建立建構設定檔。
- 準備好應用程式原始碼和
Dockerfile。 - 您必須擁有 Docker 存放區，才能在 Artifact Registry 中儲存映像檔，或者建立存放區。
必要的 IAM 權限
如要取得提交版本所需的權限，請要求管理員為您的服務帳戶授予下列 IAM 角色：
-
將建構記錄儲存在預設記錄值區中：
Cloud Build 編輯器 (
roles/cloudbuild.builds.editor) -
將建構記錄檔儲存在使用者建立的記錄值區中：
Cloud Build 編輯器 (
roles/cloudbuild.builds.editor) -
使用私人集區：
Cloud Build WorkerPool User (
roles/cloudbuild.workerPoolUser)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。
執行建構
您可以使用「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 的映像檔會使用 Artifact Registry 命名慣例。
gcloud builds submit 指令：
- 如
.所指示，在目前目錄中壓縮您的應用程式程式碼Dockerfile及其他任何資產 - 在
LOCATION位置使用上傳的檔案做為輸入，啟動建構作業； - 使用提供的名稱標記映像檔；
- 將建構的映像檔推送至 Artifact Registry。
建構進行時，其輸出會顯示在您的殼層或終端機視窗中。建構完成後，畫面會顯示類似以下的輸出：
DONE
---------------------------------------------------------------------------------
ID CREATE_TIME DURATION STATUS
$BUILD_ID 2023-10-28T15:21:18+00:00 12S SUCCESS
其中 $BUILD_ID 是建構的不重複 ID。
使用 Cloud Build 建構設定檔：
若要使用建構設定提交建構，請執行下列指令：
gcloud builds submit --config BUILD_CONFIG SOURCE
其中：
- BUILD_CONFIG 是建構設定檔的路徑。
- SOURCE 是路徑或網址原始碼。
在 Google Cloud 專案中首次執行 gcloud builds submit 時，Cloud Build 會在該專案中建立名為 [YOUR_PROJECT_NAME]_cloudbuild 的 Cloud Storage 值區。Cloud Build 會使用這個值區儲存您可能用於建構作業的任何原始碼。Cloud Build 不會自動刪除這個 bucket 中的內容。如要刪除不再用於建構的物件，您可以在值區中設定生命週期設定，或手動刪除物件。
下列指令示範如何使用儲存在 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 提交建構要求：
建立名為
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 會使用
build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY .引數呼叫docker建構步驟。要建構的映像檔完整名稱為
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY。推送至 Artifact Registry 的映像檔會使用 Artifact Registry 命名慣例。
執行下列指令，其中
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會將 POST 呼叫中的request.json傳送到 projects.builds.create API 方法的builds端點。此指令會在您的殼層或終端機視窗中顯示有關您的建構的詳細資料。輸出結果為 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" } } }使用 Cloud Build API 中的
Operation資源建構 JSON 回應。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 是從 Git 存放區擷取的修訂版本，例如分支版本、標記、修訂版本 SHA 或任何 Git 參照。
- BUILD_CONFIG 是建構設定檔的路徑。
建構進行時，其輸出會顯示在您的殼層或終端機視窗中。建構完成後，畫面會顯示類似以下的輸出：
DONE
---------------------------------------------------------------------------------
ID CREATE_TIME DURATION STATUS
$BUILD_ID 2023-10-28T15:21:18+00:00 12S SUCCESS
其中 $BUILD_ID 是建構的不重複 ID。
gcloudignore：包含建構的原始碼時，前述指令會將指定目錄中的所有檔案上傳至 Google Cloud進行建構。如果您要排除目錄中的特定檔案，可以在頂層上傳目錄中加入名為 .gcloudignore 的檔案；此檔案中指定的檔案將會遭到忽略。如果頂層上傳目錄中沒有 .gcloudignore，但有 .gitignore 檔案，gcloud CLI 會產生與 Git 相容的 .gcloudignore 檔案，遵循您的 .gitignore 檔案。詳情請參閱 gcloudignore 說明文件。
如果您沒有要傳送給建構的原始碼，請使用 --no-source 標記，其中 BUILD_CONFIG 是建構設定檔的路徑：
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
API
使用 curl 提交建構要求：
建立名為
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 是從 Git 存放區擷取的修訂版本，例如分支版本、標記、修訂版本 SHA 或任何 Git 參照。
- IMAGE_NAME 是您要建構的映像檔名稱。
- LOCATION：Artifact Registry 中 Docker 存放區的區域或多區域位置。
- PROJECT_ID：您的 Google Cloud 專案 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 的映像檔會使用 Artifact Registry 命名慣例。- REPOSITORY 是 Cloud Build 第 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會將 POST 呼叫中的request.json傳送到 projects.builds.create API 方法的builds端點。此指令會在您的殼層或終端機視窗中顯示有關您的建構的詳細資料。輸出結果為 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" } } }使用 Cloud Build API 中的
Operation資源建構 JSON 回應。metadata欄位會使用Build資源建立模型。QUEUED狀態指示建構作業正在等待執行。