此页面由 Cloud Translation API 翻译。

自定义目标简介

本文档介绍了自定义目标在 Cloud Deploy 中的工作原理。

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

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

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

自定义定位条件包含哪些数据？

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

自定义操作，在 skaffold.yaml 中定义

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

这样，自定义目标就是一种自定义操作或一组操作。

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

自定义渲染操作是可选的，但您必须创建一个，除非自定义目标通过 skaffold render（Cloud Deploy 的默认设置）可以正常工作。
自定义目标类型定义

CustomTargetType 是 Cloud Deploy 资源，用于标识此类目标用于版本渲染和部署部署 activity 的自定义操作（在 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 版中的每个阶段调用渲染操作。每个阶段的 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 执行环境。