自定义目标简介

本文档介绍了自定义目标在 Cloud Deploy 中的运作方式。

Cloud Deploy 内置了对各种运行时环境作为目标的支持。但支持的目标类型列表是有限的。借助自定义目标，您可以部署到受支持的运行时之外的其他系统。

自定义目标是一种目标，表示除 Cloud Deploy 支持的运行时之外的任意输出环境。

创建自定义目标页面介绍了定义自定义目标类型并将其作为目标在交付流水线中实现的过程。

自定义目标包含哪些内容？

每个自定义目标都由以下组件组成：

• 自定义操作（在 skaffold.yaml 中定义）

  这与定义部署钩子的方式类似。在 skaffold.yaml 文件中，您可以定义 customActions，其中每个自定义操作都会标识要使用的容器映像以及要在该容器上运行的命令。

  这样一来，自定义目标只是自定义的操作或一组操作。

  对于任何自定义目标类型，您都需要配置自定义渲染操作和自定义部署操作。这些操作会使用 Cloud Deploy 提供的值，并且必须满足一组必需的输出。

  自定义呈现操作是可选的，但您必须创建一个，除非您的自定义目标在由 skaffold render（Cloud Deploy 的默认值）呈现时可以正常运行。

• 自定义目标类型定义

  CustomTargetType 是 Cloud Deploy 资源，用于标识此类目标使用在版本渲染和发布部署活动中的自定义操作（在 skaffold.yaml 中单独定义）。

• 目标定义

  自定义目标的目标定义与任何目标类型的目标定义相同，但它包含 customTarget 属性，其值为 CustomTargetType 的名称。

这些组件到位后，您就可以像使用任何其他目标一样使用该目标，从交付流水线进度中引用它，并充分利用 Cloud Deploy 功能，例如提升和审批以及回滚。

示例

通过快速入门 定义和使用自定义目标类型，您可以创建一个自定义目标类型，其中包含要在容器映像上运行的简单命令，一个用于渲染，一个用于部署。在本例中，这些命令只会向所需的输出文件添加文本，以进行渲染和部署。

如需查看更多示例，请参阅自定义目标示例。

必需的输入和输出

为 Cloud Deploy 定义的任何自定义目标类型都必须满足渲染和部署的输入和输出要求。本部分列出了所需的输入和输出，以及它们的提供方式。

Cloud Deploy 会将渲染和部署所需的输入作为环境变量提供。以下部分列出了这些输入，以及自定义呈现和部署操作必须返回的输出。

将参数部署为环境变量

除了本部分列出的环境变量之外，Cloud Deploy 还可以将您设置的任何部署参数传递给自定义容器。

了解详情。

用于渲染操作的输入

对于自定义呈现操作，Cloud Deploy 会将以下必需输入作为环境变量提供。对于多阶段发布（Canary 部署），Cloud Deploy 会为每个阶段提供这些变量。

• CLOUD_DEPLOY_PROJECT

  用于创建自定义目标类型的 Google Cloud 项目。

• CLOUD_DEPLOY_LOCATION

  自定义目标类型的 Google Cloud 区域。

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  引用自定义目标类型的 Cloud Deploy 交付流水线的名称。

• CLOUD_DEPLOY_RELEASE

  要调用渲染操作的版本的名称。

• CLOUD_DEPLOY_TARGET

  使用自定义目标类型的 Cloud Deploy 目标的名称。

• CLOUD_DEPLOY_PHASE

  渲染内容对应的发布阶段。

• CLOUD_DEPLOY_REQUEST_TYPE

  对于自定义渲染操作，此值始终为 RENDER。

• CLOUD_DEPLOY_FEATURES

  自定义容器必须支持的 Cloud Deploy 功能的逗号分隔列表。系统会根据您在提交流水线中配置的功能来填充此变量。

  如果您的实现不支持此列表中的功能，我们建议您在呈现期间让其失败。

  对于标准部署，此字段为空。对于 Canary 部署，该值为 CANARY。如果 Cloud Deploy 提供的值为 CANARY，系统会针对 Canary 中的每个阶段调用您的呈现操作。每个阶段的 Canary 百分比在 CLOUD_DEPLOY_PERCENTAGE_DEPLOY 环境变量中提供。

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  与此渲染操作关联的部署百分比。如果 CLOUD_DEPLOY_FEATURES 环境变量设置为 CANARY，系统会针对每个阶段调用您的自定义渲染操作，并将此变量设置为每个阶段的 Canary 版百分比。对于标准部署和已达到 stable 阶段的 Canary 部署，此值为 100。

• CLOUD_DEPLOY_STORAGE_TYPE

  存储空间服务。始终为 GCS。

• CLOUD_DEPLOY_INPUT_GCS_PATH

  创建版本时写入的渲染文件归档的 Cloud Storage 路径。

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  自定义渲染容器预计要上传要用于部署的工件的 Cloud Storage 路径。请注意，渲染操作必须上传一个名为 results.json 的文件，其中包含此渲染操作的结果。如需了解详情，请参阅渲染操作的输出。

渲染操作的输出

您的自定义呈现操作必须提供本部分中所述的信息。这些信息必须包含在名为 results.json 的结果文件中，该文件位于 Cloud Deploy 提供的 Cloud Storage 存储桶中。

• 渲染的配置文件

• 一个 results.json 文件，其中包含以下信息：

  • 指示自定义操作的成功或失败状态。

    有效值为 SUCCEEDED 和 FAILED。

  • （可选）自定义操作生成的任何错误消息。

  • 渲染的配置文件的 Cloud Storage 路径。

    所有呈现的配置文件的路径都是完整 URI。您可以使用 Cloud Deploy 提供的 CLOUD_DEPLOY_OUTPUT_GCS_PATH 值来部分填充该字段。

    您必须提供渲染的配置文件，即使该文件为空也是如此。文件内容可以是任何内容，采用任何格式，只要您的自定义部署操作可以使用该内容即可。我们建议此文件应采用人类可读的格式，以便您和贵组织中的其他用户可以在版本检查器中查看此文件。

  • （可选）您要包含的所有元数据的映射

    您的自定义目标会创建此元数据。此元数据存储在版本的 custom_metadata 字段中。

如果您需要检查 results.json 文件（例如进行调试），可以在 Cloud Build 日志中找到其 Cloud Storage URI。

渲染结果文件示例

以下是自定义渲染操作的 results.json 文件输出示例：

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

部署操作的输入

对于自定义部署操作，Cloud Deploy 会以环境变量的形式提供以下必需输入：

• CLOUD_DEPLOY_PROJECT

  用于创建自定义目标的 Google Cloud 项目。

• CLOUD_DEPLOY_LOCATION

  自定义目标类型的 Google Cloud 区域。

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  引用使用自定义目标类型的目标的 Cloud Deploy 交付流水线的名称。

• CLOUD_DEPLOY_RELEASE

  要为其调用部署操作的版本的名称。

• CLOUD_DEPLOY_ROLLOUT

  此部署所针对的 Cloud Deploy 发布作业的名称。

• CLOUD_DEPLOY_TARGET

  使用自定义目标类型的 Cloud Deploy 目标的名称。

• CLOUD_DEPLOY_PHASE

  相应部署的发布阶段。

• CLOUD_DEPLOY_REQUEST_TYPE

  对于自定义部署操作，此值始终为 DEPLOY。

• CLOUD_DEPLOY_FEATURES

  自定义容器必须支持的 Cloud Deploy 功能的逗号分隔列表。系统会根据您在提交流水线中配置的功能来填充此变量。

  如果您的实现不支持此列表中的功能，我们建议您在呈现期间让其失败。

  对于标准部署，此字段为空。对于 Canary 部署，该值为 CANARY。如果 Cloud Deploy 提供的值为 CANARY，系统会针对 Canary 中的每个阶段调用您的呈现操作。每个阶段的 Canary 百分比在 CLOUD_DEPLOY_PERCENTAGE_DEPLOY 环境变量中提供。

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  与此部署操作关联的部署百分比。如果 CLOUD_DEPLOY_FEATURES 环境变量设置为 CANARY，系统会针对每个阶段调用您的自定义部署操作，并将此变量设置为每个阶段的 Canary 版百分比。您的部署操作必须针对每个阶段运行。

• CLOUD_DEPLOY_STORAGE_TYPE

  存储空间服务。始终为 GCS。

• CLOUD_DEPLOY_INPUT_GCS_PATH

  自定义渲染程序写入渲染配置文件的 Cloud Storage 路径。

• CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

  渲染的 Skaffold 配置的 Cloud Storage 路径。

• CLOUD_DEPLOY_MANIFEST_GCS_PATH

  呈现的清单文件的 Cloud Storage 路径。

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  自定义部署容器预计要上传部署工件的 Cloud Storage 目录的路径。如需了解详情，请参阅部署操作的输出。

部署操作的输出

您的自定义部署操作必须写入 results.json 输出文件。此文件必须位于 Cloud Deploy 提供的 Cloud Storage 存储桶 (CLOUD_DEPLOY_OUTPUT_GCS_PATH) 中。

该文件必须包含以下内容：

• 指示自定义部署操作的成功或失败状态。

  以下是有效的状态：

  • SUCCEEDED

  • FAILED

  • SKIPPED（对于跳过 Canary 阶段直接进入 stable 的 Canary 部署）。

• （可选）部署工件文件列表，采用 Cloud Storage 路径的形式

  路径是完整的 URI。您可以使用 Cloud Deploy 提供的 CLOUD_DEPLOY_OUTPUT_GCS_PATH 的值来部分填充该字段。

  此处列出的文件会作为部署工件填充到作业运行资源中。

• （可选）自定义部署操作失败（返回 FAILED 状态）时的失败消息

  此消息用于在作业运行期间为此部署操作填充 failure_message。

• （可选）跳过消息，用于在操作返回 SKIPPED 状态时提供更多信息。

• （可选）您要包含的任何元数据的映射

  您的自定义目标会创建此元数据。这些元数据存储在作业运行和发布版本的 custom_metadata 字段中。

如果您需要检查 results.json 文件（例如进行调试），可以在 Cloud Build 版本渲染日志中找到其 Cloud Storage URI。

部署结果文件示例

以下是自定义部署操作的 results.json 文件输出示例：

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

有关自定义操作的更多信息

在设置和使用自定义目标类型时，请注意以下事项。

执行自定义操作

您的自定义渲染和部署操作会在 Cloud Deploy 执行环境中运行。您无法将自定义操作配置为在 Google Kubernetes Engine 集群上运行。

使用可重复使用的远程 Skaffold 配置

如本文档中所述，您可以在创建版本时提供的 skaffold.yaml 文件中配置自定义操作。不过，您也可以将 Skaffold 配置存储在 Git 代码库或 Cloud Storage 存储桶中，并从自定义目标类型定义中引用它们。这样，您就可以使用在单个共享位置定义并存储的自定义操作，而无需在每个版本的 skaffold.yaml 文件中添加自定义操作。

自定义目标和部署策略

标准部署完全支持自定义目标。

只要自定义呈现程序和部署程序支持 Canary 功能，Cloud Deploy 就支持 Canary 部署。

您必须使用自定义 Canary 配置。不支持自动和自定义自动化 Canary 版本。

自定义目标和部署参数

您可以将部署参数与自定义目标搭配使用。您可以在提交流水线阶段、使用自定义目标类型的目标上或版本上设置这些属性。

除了已提供的参数之外，部署参数还会作为环境变量传递给自定义渲染和部署容器。

自定义目标示例

cloud-deploy-samples 代码库包含一组自定义目标实现示例。可用的示例如下：

• GitOps

• Vertex AI

• Terraform

• Infrastructure Manager

• Helm

每个示例都包含一个快速入门。

这些示例不是受支持的 Google Cloud 产品，也不在 Google Cloud 支持合同的涵盖范围内。如需报告 Google Cloud 产品中的 bug 或申请添加功能，请与 Google Cloud 支持团队联系。

后续步骤

• 现在，您已经了解了自定义目标，接下来了解如何配置和使用它们。

• 不妨试试快速入门：定义和使用自定义目标类型。

• 详细了解如何配置 Cloud Deploy 目标。

• 了解 Cloud Deploy 执行环境。