本文档介绍了 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 会以环境变量的形式提供以下输入。对于多阶段发布（灰度发布），Cloud Deploy 会为每个阶段提供以下变量。
CLOUD_DEPLOY_PROJECT创建自定义目标的项目的 Google Cloud 项目编号。
CLOUD_DEPLOY_PROJECT_ID项目的 Google Cloud 项目 ID。
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_PROJECT_ID项目的 Google Cloud 项目 ID。
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) 中。
该文件必须包含以下内容：
自定义部署操作的成功或失败状态的指示。
以下是有效状态：
SUCCEEDEDFAILEDSKIPPED
此参数适用于跳过 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 执行环境。