自定义目标简介

本文档介绍自定义目标在 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 还可以将您设置的任何部署参数传递给自定义容器。

用作自定义目标输入的部署参数必须以 customTarget/ 开头，例如 customTarget/vertexAIModel。将部署参数引用为环境变量时，请使用以下语法：

CLOUD_DEPLOY_customTarget_[VAR_NAME]

其中，VAR_NAME 是部署参数名称中斜杠后的名称。例如，如果您定义名为 customTarget/vertexAIModel 的部署参数，请将其引用为 CLOUD_DEPLOY_customTarget_vertexAIModel。

用于呈现操作的输入

对于自定义渲染操作，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 中的每个阶段调用渲染操作。CLOUD_DEPLOY_PERCENTAGE_DEPLOY 环境变量中提供了每个阶段的 Canary 百分比。
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 的值来填充该配置文件。
  
  您必须提供呈现的配置文件，即使该文件为空也是如此。该文件的内容可以是任何内容，可以采用任何格式，只要您的自定义部署操作可以使用该文件。我们建议您将此文件设为人类可读懂，以便您和组织中的其他用户可以在版本检查器中查看此文件。

如果您需要检查 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: ""
}

输入以部署操作

对于自定义部署操作，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 中的每个阶段调用渲染操作。CLOUD_DEPLOY_PERCENTAGE_DEPLOY 环境变量中提供了每个阶段的 Canary 百分比。
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 状态时提供更多信息。

如果您需要检查 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: ""
}

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

以下是设置和使用自定义目标类型时需要注意的事项。

执行自定义操作

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

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

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

自定义目标和部署策略

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

Cloud Deploy 支持 Canary 部署，前提是自定义渲染程序和部署者支持 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 执行环境。