自定义目标简介

本文档介绍了自定义目标在 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。如果 为 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。如果 为 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) 中。

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

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

    以下是有效的状态：

  • （可选）部署工件文件的列表，格式为 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 支持团队联系。

后续步骤