自定义目标简介

本文档介绍了自定义目标在 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。引用 deploy 参数作为环境变量，请使用以下语法：

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。如果 为 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。

  • 渲染的配置文件

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

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

      有效值为 SUCCEEDED 和 FAILED。

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

    • 所呈现配置文件的 Cloud Storage 路径或 文件。

      所有呈现的配置文件的路径为完整 URI。您 使用 CLOUD_DEPLOY_OUTPUT_GCS_PATH 的值部分填充 由 Cloud Deploy 提供。

      您必须提供所呈现的配置文件，即使该文件为空也是如此。通过 文件内容可以是任意格式， 可供自定义部署操作使用的资源。我们建议将此文件设置为真人 这样您和您组织中的其他用户就可以 文件（位于发布检查器中）。

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

      此元数据由您的自定义目标创建。这些元数据存储在 发布在 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

    部署阶段 相应的 Deployment

  • 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_DEPLOY_OUTPUT_GCS_PATH)。

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

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

    有效状态如下：

  • （可选）部署工件文件的列表，格式为 Cloud Storage 路径

    路径是完整的 URI。您可以使用 CLOUD_DEPLOY_OUTPUT_GCS_PATH 提供者 Cloud Deploy。

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

  • （可选）如果自定义部署操作失败，则显示失败消息 （返回 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 文件。但您也可以 Git 代码库或 Cloud Storage 存储桶中的 Skaffold 配置，以及 从您的自定义目标类型定义中引用它们。 这样，您就可以使用在单个共享 而无需将自定义操作添加到每个版本的 skaffold.yaml 文件。

自定义目标和部署策略

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

Cloud Deploy 支持 Canary 部署，只要 自定义渲染程序和部署者支持 Canary 功能。

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

自定义目标和部署参数

您可以将部署参数与自定义目标搭配使用。 您可以在交付流水线中设置它们 阶段，针对使用 自定义目标类型，还是在 发布。

部署参数会传递到您的自定义渲染和部署容器，如 环境变量以及 已经提供的模型。

自定义目标示例

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

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

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

这些示例不是受支持的 Google Cloud 产品， 在 Google Cloud 支持合同涵盖范围内。报告错误或提出请求 功能，请联系 Google Cloud 联系。

后续步骤