通过 CLI 和 API 提交 build

本页面介绍了如何使用 Google Cloud CLI 和 Cloud Build API 在 Cloud Build 中手动启动构建。

准备工作

  • 如果您要使用本指南中的命令行示例,请安装 Google Cloud CLI
  • 要使用 Cloud Build 构建配置进行构建,请创建构建配置文件
  • 如需使用 Dockerfile 进行构建,请准备好 Dockerfile
  • 如果您的构建需要源代码,请准备好源代码。

必需的 IAM 权限

有关授予 IAM 角色的说明,请参阅配置对 Cloud Build 资源的访问权限

运行构建

您可以使用构建来源字段指定构建的源代码。“build 来源”字段是以下值之一:storage_sourcerepo_sourcegit_sourceconnected_repository

使用 storage_source 提交 build

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 的映像使用注册表名称格式

gcloud builds submit 命令:

  • 压缩当前目录中的应用代码、Dockerfile 以及任何其他资源(用 . 表示);
  • 将文件上传至 Cloud Storage 存储分区;
  • 使用上传的文件作为输入,在 us-west2 位置启动构建;
  • 使用提供的名称标记映像
  • 将构建的映像推送到 Container Registry。

随着构建的进行,会在 shell 或终端窗口中显示其输出。构建完成后,您应该看到类似于以下内容的输出:

    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 是源代码的路径或网址。

当您在 Google Cloud 项目中首次运行 gcloud builds submit 时,Cloud Build 会在该项目中创建一个名为 [YOUR_PROJECT_NAME]_cloudbuild 的 Cloud Storage 存储桶。Cloud Build 使用此存储分区来存储您用于构建的任何源代码。Cloud Build 不会自动删除此存储分区中的内容。如需删除不再用于构建的对象,您可以在存储分区上设置生命周期配置,也可以手动删除对象

以下命令演示了如何提交 cloudbuild.yaml 构建请求 使用存储在 Cloud Storage 存储桶中的源代码。

    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 的映像使用注册表名称格式

  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 发送到 builds 端点以获取 projects.builds.create API 方法。

    该命令在 shell 或终端窗口中显示有关构建的详细信息。输出是 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 提交 build

gcloud

如需使用第 2 代代码库资源中的构建源运行构建请求,请运行以下命令:

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

其中:

  • REPOSITORY 是 Google Cloud Build 第 2 代代码库的名称,格式为 projects/*/locations/*/connections/*repositories/*
  • REVISION 是要从 Git 代码库中提取的修订版本,例如分支、标记、提交 SHA 或任何 Git 引用。
  • BUILD_CONFIG 是构建配置文件的路径。

随着构建的进行,会在 shell 或终端窗口中显示其输出。构建完成后,您应该看到类似于以下内容的输出:

    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 文件, gcloud CLI 将生成一个与 Git 兼容的 .gcloudignore 文件, 遵循 .gitignore 编辑的文件。有关详情,请参阅 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 是从 Git 代码库提取的修订版本,例如分支、标记、提交 SHA 或任何 Git 引用。
    • IMAGE_NAME 是要构建的映像的名称。

    在此构建请求中,Cloud Build 会调用 docker 构建步骤 参数 build -t gcr.io/PROJECT_ID/IMAGE_NAME .

    要构建的映像的全名是 gcr.io/PROJECT_ID/IMAGE_NAME。推送到 Container 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 将 POST 调用中的 request.json 发送到 builds 端点以获取 projects.builds.create API 方法。

    该命令在 shell 或终端窗口中显示有关构建的详细信息。输出是 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 状态表示构建正在等待执行。

后续步骤