创建自定义目标

本文档介绍如何创建自定义 Cloud Deploy 目标类型，并将该自定义目标类型用作 Cloud Deploy 交付流水线中的目标。

下面概要介绍了创建自定义目标类型并将其用于交付流水线的流程：

  1. 创建一个容器化应用，这些应用包含部署到自定义目标的功能，并且满足 Cloud Deploy 对自定义目标类型的要求。

  2. 在 skaffold.yaml 中定义一个自定义操作，用于引用该容器并指定要在其上运行的一个或多个命令。

  3. 创建 CustomTargetType 定义，并引用上一步中的自定义操作，并将其注册为 Cloud Deploy 资源。

  4. 使用 customTarget 属性定义新目标，该属性用于标识新的自定义目标类型。

  5. 从交付流水线进度中引用该目标。

  6. 创建发布版本。

本文档其余部分将详细介绍其中的每个步骤。

创建容器化应用

部署到自定义目标的功能在容器化应用中定义，您可以通过从 skaffold.yaml 文件引用它们向 Cloud Deploy 提供容器化应用。如果您的交付流水线包含使用自定义目标类型的目标，Cloud Deploy 会在 Skaffold 中调用为该自定义目标类型定义的自定义操作容器，以执行您定义的渲染和部署操作。

应用的行为由您决定。但是，它必须使用 Cloud Deploy 提供的输入环境变量，并且必须返回所需的输出。

在大多数情况下，您需要为创建的每个自定义目标类型创建一个容器，为渲染操作创建一个容器，为部署操作创建一个容器。渲染操作是可选的，但如果您未提供渲染操作，Cloud Deploy 将使用默认 skaffold render。

在 Skaffold 中定义自定义操作

准备好一个或多个自定义操作容器映像后，您可以从 skaffold.yaml 配置文件中引用它们。

您可以在 customActions 节中为自定义目标配置每个自定义操作。对于任何自定义目标类型，您都需要在 Skaffold 中创建一个用于渲染的自定义操作，以及一个用于部署的自定义操作。CustomTargetType 定义可识别哪个自定义操作用于渲染，哪些自定义操作用于部署。

以下是 skaffold.yaml 中自定义渲染和部署操作的配置：

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

在此 Skaffold 配置中：

  • customActions.name

    是自定义渲染或部署操作的任意名称。CustomTargetType 定义在 renderAction 属性或 deployAction 属性中引用此名称。

  • containers 节包含您的引用以及运行该容器的命令。

    containers 节允许多个容器，但 Google 建议您仅使用一个。

  • customActions.containers.name

    是用于此操作的特定容器的任意名称。 最佳做法是，此容器名称应始终符合 SHA 规范。

  • image

    是容器映像的路径。

  • command

    要在容器上运行的一个或多个命令。

  • args

    是 command 的参数集合。

如需详细了解 customActions 中使用的配置属性，请参阅 Skaffold YAML 参考文档。

指定您的自定义目标类型

要定义自定义目标，首先需要使用 CustomTargetType 配置创建自定义目标类型。您可以在交付流水线定义所在的文件中、使用目标定义或单独的文件中创建 CustomTargetType。

CustomTargetType 定义如下：

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

地点

  • CUSTOM_TARGET_TYPE_NAME

    您为此自定义目标类型定义指定的任意名称。使用您所定义的自定义目标类型的任何目标的目标定义中都会引用此名称。

  • RENDER_ACTION_NAME

    是自定义呈现操作的名称。此值是在 skaffold.yaml 中为渲染操作定义的 customAction.name。

  • DEPLOY_ACTION_NAME

    是自定义部署操作的名称。此值是在 skaffold.yaml 中为deploy操作定义的 customAction.name。

  • includeSkaffoldModules

    如果您使用的是远程 Skaffold 配置，可以选择使用以下 stanza。使用远程 Skaffold 配置部分显示了此节中的属性。

使用远程 Skaffold 配置

您可以将 Skaffold 配置存储在公共 Git 代码库、Cloud Storage 存储桶或 Cloud Build 第 2 代代码库中，并从自定义目标类型定义中引用这些配置。

使用远程 Skaffold 配置意味着您在发布时提供的 skaffold.yaml 不需要定义自定义操作。这允许在整个组织内共享自定义操作。

如需使用远程 Skaffold 配置，请执行以下操作：

  1. 使用您的自定义操作创建 Skaffold 配置。

  2. 将配置存储在 Git 代码库或 Cloud Storage 存储桶中。

  3. 在您的自定义目标类型定义中，添加一个 customActions.includeSkaffoldModules 节。

  4. 在 includeSkaffoldModules 下，指定以下内容：

    • （可选）一个或多个 configs 元素：

      - configs: ["name1", "name2"]

      configs 的值是与要包含的每个 Skaffold 配置上的 metadata.name 属性匹配的字符串列表。如果省略此属性，Cloud Deploy 将采用指定路径中的所有配置。

    • googleCloudStorage、git 或 googleCloudBuildRepo 节。

      对于 Cloud Storage：

      googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME

      对于 Git：

      git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      对于 Cloud Build 代码库（第 2 代）：

       googleCloudBuildRepo:
  repository: PATH_TO_GCB_REPO
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      其中：

      PATH_TO_GCS_BUCKET 是 Cloud Storage 目录的路径，以 /* 结尾，其中存储了 Skaffold 配置。Skaffold 会下载此目录中的所有文件，然后根据配置的相对路径查找包含相应配置的相关 Skaffold 文件。

      PATH_TO_GCB_REPO 是存储 Skaffold 配置的 Cloud Build 第 2 代代码库的路径。路径采用以下形式：projects/{project}/locations/{location}/connections/{connection}/repositories/{repository}。Skaffold 会下载此目录中的所有文件，然后根据配置的相对路径查找 Skaffold 文件。

      FILENAME 是包含 Skaffold 配置的文件的名称。此 path: 属性是可选的；如果您不指定该属性，Cloud Deploy 会假定 skaffold.yaml。如果没有 skaffold.yaml，或者没有您指定的文件名，则版本创建失败。

      REPO_URL 是 Git 代码库的网址。

      PATH_TO_FILE 是该代码库中包含 Skaffold 配置的文件的路径。

      BRANCH_NAME 是从中获取 Skaffold 配置的分支的名称（例如 main）。

示例

以下自定义目标类型 YAML 是一个带有 includeSkaffoldModules 节的 customActions 节，指向存储在 Cloud Storage 存储桶中的 Skaffold 配置：

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

以下 YAML 是所显示的自定义操作引用的 Skaffold 配置：

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

注册您的自定义目标类型

配置 CustomTargetType 后，请运行 gcloud deploy apply 命令以在 Google Cloud 项目中注册 CustomTargetType 资源：

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

其中：

FILE 是您在其中定义了此自定义目标类型的文件的名称。

PROJECT 是要在其中创建此资源的 Google Cloud 项目。CustomTargetType 必须与引用它的 Target 资源位于同一项目中。如果您已将该项目设置为 Google Cloud CLI 的默认项目，则无需指定该项目。

REGION 是要在其中创建此资源的区域（例如 us-centra1）。CustomTargetType 必须与引用它的 Target 资源位于同一区域。如果您已将该区域设置为 gcloud CLI 的默认区域，则无需指定该区域。

现在将 CustomTargetType 创建为 Cloud Deploy 资源，您可以在 Target 定义中使用它来创建自定义目标。

如需详细了解 CustomTargetType 定义，请参阅 Cloud Deploy 配置架构参考文档。

设定目标

受支持目标类型的目标定义与自定义目标定义之间的唯一区别在于，自定义目标定义包含一个 customTarget 节。customTarget 的语法如下：

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

其中 CUSTOM_TARGET_TYPE_NAME 是自定义目标类型配置中定义的 name 属性的值。

将目标添加到交付流水线

您可以在交付流水线中使用自定义目标，就像使用受支持的目标类型一样。也就是说，支持的目标类型的目标与自定义目标之间的交付流水线进度没有差异。

交付流水线中的所有目标必须使用相同的目标类型。例如，交付流水线中不能同时存在一些部署到 Google Kubernetes Engine 的目标和一些自定义目标。

与受支持的目标类型一样，您可以在流水线阶段中添加部署参数。

创建版本

完全定义自定义目标类型，并为使用该类型创建目标后，您现在可以通过常规方式创建版本：

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

创建版本后，系统会为交付流水线中的每个目标执行自定义渲染操作，包括处理版本、目标或交付流水线中配置的部署参数。Cloud Deploy 将部署参数作为输入提供给自定义渲染容器。

查看自定义目标的输出

如果自定义操作满足自定义目标的要求，您可以使用 Google Cloud 控制台查看渲染的工件。

如需查看自定义呈现操作的输出，请按以下步骤操作。

  1. 在 Google Cloud 控制台中，导航到 Cloud Deploy 交付流水线页面以查看交付流水线。

    打开“交付流水线”页面

  2. 点击交付流水线的名称。

    流水线可视化图表会显示应用的部署状态，并且您的版本会列在交付流水线详细信息下的版本标签页中。

  3. 点击发布版本名称。

    随即会显示发布版本详情页面。

  4. 点击工件标签页。

  5. 在目标制品下，点击查看制品旁边的箭头。

    系统会列出呈现的工件，包括呈现的 skaffold.yaml 和自定义呈现器生成的已呈现的清单文件。您可以点击每个文件旁边的存储位置链接，转到 Cloud Storage 存储桶以查看这些文件。

    您也可以点击查看工件链接，使用版本检查器按版本、目标或阶段查看这些文件。

后续步骤