配置架构参考文档

一个或多个 Cloud Deploy 配置文件定义交付流水线、要部署到的目标以及这些目标的进度

交付流水线配置文件可以包含目标定义,也可以包含在单独的一个或多个文件中。按照惯例,包含交付流水线配置和目标配置的文件称为 clouddeploy.yaml,不包含目标的流水线配置称为 delivery-pipeline.yaml。但您可以随意为这些文件指定任何名称

分门别类 (What goes where)

Cloud Deploy 使用两个主要配置文件:

它们可以是单独的文件,也可以在同一文件中配置交付流水线和目标。

交付流水线配置文件的结构

以下配置包含目标定义:

# Delivery pipeline config
apiVersion: deploy.cloud.google.com/v1
kind: DeliveryPipeline
metadata:
 name:
 annotations:
 labels:
description:
suspended:
serialPipeline:
 stages:
 - targetId:
   profiles: []
# Deployment strategies
# One of:
#   standard:
#   canary:
# See the strategy section in this document for details.
   strategy:
     standard:
       verify:
       predeploy:
         actions: []
       postdeploy:
         actions: []
   deployParameters:
   - values:
     matchTargetLabels:
 - targetId:
   profiles: []
   strategy:
   deployParameters:
---

# Target config
apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
 name:
 annotations:
 labels:
description:
multiTarget:
 targetIds: []
deployParameters:
requireApproval:
#
# Runtimes
# one of the following runtimes:
gke:
 cluster:
 internalIp:
 proxyUrl:
#
# or:
anthosCluster:
 membership:
#
# or:
run:
 location:
#
# or:
customTarget:
  customTargetType:
#
# (End runtimes. See documentation in this article for more details.)
#
executionConfigs:
- usages:
  - [RENDER | PREDEPLOY | DEPLOY | VERIFY | POSTDEPLOY]
  workerPool:
  serviceAccount:
  artifactStorage:
  executionTimeout:
---

# Custom target type config
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name:
  annotations:
  labels:
description:
customActions:
  renderAction:
  deployAction:
  includeSkaffoldModules:
    - configs:
    # either:
    googleCloudStorage:
      source:
      path:
    # or:
    git:
      repo:
      path:
      ref:
---

# Automation config
apiVersion: deploy.cloud.google.com/v1
kind: Automation
metadata:
  name:
  labels:
  annotations:
description:
suspended:
serviceAccount:
selector:
- target:
    id:
    # or
    labels:
rules:
- [RULE_TYPE]:
  name:
  [RULE-SPECIFIC_CONFIG]

此 YAML 包含三个主要组成部分:

  • 主要交付流水线和进展

    配置文件可以包含任意数量的流水线定义。

  • 目标定义

    为简单起见,此示例仅显示一个目标,但目标可以是任何数量。此外,目标可以在一个或多个单独的文件中定义。

  • 自定义目标类型定义

    自定义目标,需要自定义目标类型定义。与目标和自动化操作一样,自定义目标类型可以在交付流水线所在的同一文件或单独的文件中进行定义。

  • Automation 定义

    您可以在交付流水线和目标所在的同一文件中,或者在单独的一个或多个文件中创建任何部署自动化操作。为简单起见,此处仅显示一个 Automation,但您可以根据需要创建任意数量的 Automation

本文档的其余部分定义这些组成部分。

流水线定义和进展

除了流水线元数据(例如 name)之外,主流水线定义还包含按部署序列顺序的目标引用列表。也就是说,列出的第一个目标是第一个部署目标。部署到该目标后,将版本提升到列表中的下一个目标。

以下是交付流水线的配置属性,不包括目标定义。

metadata.name

name 字段采用的字符串对于每个项目和位置必须是唯一的。

metadata.annotationsmetadata.labels

交付流水线配置可以包含注释和标签。在注册流水线后,注释和标签会与交付流水线资源一起存储。

如需了解详情,请参阅将标签和注解与 Cloud Deploy 搭配使用

description

描述此交付流水线的任意字符串。此说明会显示在 Google Cloud 控制台的交付流水线详细信息中。

suspended

一个布尔值,如果为 true,则会暂停交付流水线,使其无法用于创建、提升、回滚或重新部署版本。此外,如果交付流水线被暂停,您无法批准或拒绝从该流水线创建的发布。

默认值为 false

serialPipeline

串行进度交付流水线定义的开头。必须提供此节。

stages

将此交付流水线配置为要部署到的所有目标的列表。

该列表必须采用所需的交付顺序。例如,如果您具有名为 devstagingproduction 的目标,请按照相同的顺序列出它们,以便您的第一个部署是 dev,最后一个部署是 production

使用相应的目标定义中 metadata.name 字段的值填充每个 stages.targetId 字段。并且在 targetId 下方,包括 profiles

serialPipeline:
 stages:
 - targetId:
   profiles: []
   strategy:
     standard:
       verify:

targetId

标识要用于交付流水线此阶段的特定目标。该值是目标定义中的 metadata.name 属性。

如果将 strategy.standard.verify 设置为 true,则会对目标启用部署验证。如果未指定部署策略,则使用 standard 部署策略,并将验证设置为 false

profiles

skaffold.yaml 中获取零个或零个以上 Skaffold 配置文件名称的列表。创建版本时,Cloud Deploy 会将配置文件与 skaffold render 搭配使用。借助 Skaffold 配置文件,您可以在使用单个配置文件时更改目标之间的配置。

strategy

包含用于指定部署策略的属性。支持以下策略:

  • standard:

    应用已完全部署到指定目标。

    这是默认的部署策略。如果省略 strategy,Cloud Deploy 将使用 standard 部署策略。

  • canary:

    Canary 部署中,您可以逐步部署应用的新版本,按基于百分比的增量替换已在运行的版本(例如,先 25%,然后是 50%,然后是 75%,最后是完全)。

部署策略是按目标定义的。例如,您可能有一个针对 prod 目标的 Canary 策略,但针对其他目标有一个标准策略(未指定 strategy)。

如需了解详情,请参阅使用部署策略

strategy 配置

本部分介绍了每个受支持的运行时的 strategy 配置元素。

标准部署策略

标准策略仅包含以下要素:

strategy:
  standard:
    verify: true|false

verify 是可选属性。默认值为 false,这意味着最终发布不存在验证阶段。

对于标准部署策略,您可以省略 strategy 元素。

Canary 部署策略

以下部分介绍了 Cloud Deploy 支持的每个运行时的 Canary 部署策略的配置。

对于 Cloud Run 目标
strategy:
  canary:
    runtimeConfig:
      cloudRun:
        automaticTrafficControl: true | false
    canaryDeployment:
      percentages: [PERCENTAGES]
      verify: true | false
对于 GKE 和 GKE Enterprise 目标

以下 YAML 展示了如何使用基于服务的网络为 GKE 或 GKE Enterprise 目标配置部署策略:

      canary:
        runtimeConfig:
          kubernetes:
            serviceNetworking:
              service: "SERVICE_NAME"
              deployment: "DEPLOYMENT_NAME"
              disablePodOverprovisioning: true | false
        canaryDeployment:
          percentages: [PERCENTAGES]
          verify: true | false

以下 YAML 展示了如何使用 Gateway API 为 GKE 或 GKE Enterprise 目标配置部署策略:

      canary:
        runtimeConfig:
          kubernetes:
            gatewayServiceMesh:
              httpRoute: "HTTP_ROUTE_NAME"
              service: "SERVICE_NAME"
              deployment: "DEPLOYMENT_NAME"
              routeUpdateWaitTime: "WAIT_TIME"
        canaryDeployment:
          percentages: ["PERCENTAGES"]
          verify: true | false

请注意,在此示例中为 routeUpdateWaitTime。之所以将其包含在内,是因为 Gateway API 使用 HTTPRoute 资源拆分流量,而有时在传播对 HTTPRoute 所做的更改时会出现延迟。在这种情况下,请求可能会被丢弃,因为流量会被发送到不可用的资源。如果您观察到此延迟,可以使用 routeUpdateWaitTime 使 Cloud Deploy 在应用 HTTPRoute 更改后等待。

以下 YAML 展示了如何配置自定义自定义自动 Canary 部署策略。自定义 Canary 中省略了 runtimeConfig 部分中的运行时专用配置,但自动和自定义自动 Canary 配置中会包含这些配置。

strategy:
       canary:
         # Runtime configs are configured as shown in the
         # Canary Deployment Strategy section of this document.
         runtimeConfig:

         # Manual configuration for each canary phase
         customCanaryDeployment:
           - name: "PHASE1_NAME"
             percent: PERCENTAGE1
             profiles: [ "PROFILE1_NAME" ]
             verify: true | false
           - …
           - name: "stable"
             percent: 100
             profiles: [ "LAST_PROFILE_NAME" ]
             verify: true|false

verify

可选布尔值,指示此目标是否支持部署验证。默认值为 false

启用部署验证还需要 skaffold.yaml 中的 verify。如果您不提供此属性,验证作业将失败。

deployParameters

允许您指定在使用部署参数时,以将值传递给清单以实现标签匹配的目标的键值对。

您也可以将其添加到目标中。

在交付流水线上设置的部署参数使用标签来匹配目标:

deployParameters:
- values:
    someKey: "value1"
  matchTargetLabels:
    label1: firstLabel
- values:
    someKey: "value2"
  matchTargetLabels:
    label2: secondLabel

在此示例中,为键提供了两个值,并且每个值都有一个标签。该值将应用于具有匹配标签的任何目标的清单。

predeploypostdeploy 作业

通过这些变量,您可以引用要在部署作业 (predeploy) 之前和验证作业之后运行的自定义操作(skaffold.yaml 中单独定义)和验证作业(如果存在)(postdeploy) 运行。如果没有验证作业,则部署后作业将在部署作业之后运行。

部署钩子在 strategy.standardstrategy.canary 下配置,如下所示:

serialPipeline:
  stages:
  - targetId: 
    strategy:
      standard:
        predeploy:
          actions: [ACTION_NAME]
        postdeploy:
          actions: [ACTION_NAME]

其中 ACTION_NAME 是在 skaffold.yaml 中为 customActions.name 配置的名称。

您可以在任何策略(例如 standardcanary)下配置 predeploypostdeploy 作业。

如需详细了解如何配置和使用部署前钩子和部署后钩子,请参阅部署前后运行钩子

目标定义

交付流水线定义文件可以包含目标定义,或者您可以在单独的文件中指定目标。您可以在项目中重复使用目标名称,但这些名称在交付流水线中必须是唯一的。

您可以在多个交付流水线中重复使用目标。但是,您只能在单个交付流水线的进展中引用目标一次。

另请参阅:自定义目标类型定义

对于 GKE 目标

以下 YAML 展示了如何配置部署到 GKE 集群的目标:

     apiVersion: deploy.cloud.google.com/v1
     kind: Target
     metadata:
      name:
      annotations:
      labels:
     description:
     deployParameters:
     multiTarget:
      targetIds: []

     requireApproval:
     gke:
      cluster: projects/[project_name]/locations/[location]/clusters/[cluster_name]
      internalIp:
      proxyUrl:

     executionConfigs:
     - usages:
       - [RENDER | PREDEPLOY | DEPLOY | VERIFY | POSTDEPLOY]
       workerPool:
       serviceAccount:
       artifactStorage:
       executionTimeout:

metadata.name

此目标的名称。此名称必须是全局唯一的。

metadata.annotationsmetadata.labels

目标配置支持 Kubernetes 注释标签,但 Cloud Deploy 不需要它们。

注释和标签与目标资源一起存储。如需了解详情,请参阅将标签和注释与 Cloud Deploy 搭配使用

description

此字段采用任意字符串,用于描述此目标的使用。

deployParameters

您可以在任何目标上添加部署参数以及值。这些值会在呈现后分配给清单中的相应键。

deployParameters 节接受键值对,如下所示:

deployParameters:
  someKey: "someValue"
  someOtherKey: "someOtherValue"

如果您在multi-target上设置部署参数,系统会将该值分配给该多目标的所有子目标的清单。

multiTarget.targetIds: []

此属性是可选的,用于配置要用于并行部署multi-target

该值是以英文逗号分隔的子目标列表。子目标配置为常规目标,并且不包含此 multiTarget 属性。

requireApproval

提升到此目标是否需要手动批准。可以是 truefalse

此为可选属性。默认值为 false

配置并行部署时,您可以仅要求批准多目标,而不是子目标。

gke

(仅适用于 GKE 集群)用于标识将在其中部署应用的集群的资源路径:

gke:
  cluster: projects/[project_name]/locations/[location]/clusters/[cluster_name]
  • project_name

    集群所在的 Google Cloud 项目。

  • location

    集群所在的位置。例如 us-central1。该集群也可以是可用区级 (us-central1-c)。

  • cluster_name

    集群的名称,它显示在 Google Cloud 控制台的集群列表中。

示例如下:

gke:
  cluster: projects/cd-demo-01/locations/us-central1/clusters/prod

配置multi-target时省略 gke 属性。而是在相应的子目标内配置 GKE 集群。

如需了解执行环境属性的说明,请参阅本文中的 executionConfigs

internalIp

指定的 GKE 集群是否使用专用 IP 地址。此为可选属性。默认情况下,Cloud Deploy 使用集群的公共 IP 地址。如果存在专用 IP 地址并且您想使用它,请将此设置为 true

proxyUrl

如果您通过代理访问集群,请在此处提供 proxyUrl 属性。该值是代理 GKE 集群的网址,系统会在连接到您的集群时传递给 kubectl

对于 Cloud Run 目标

以下 YAML 展示了如何配置部署到 Cloud Run 服务的目标:

     apiVersion: deploy.cloud.google.com/v1
     kind: Target
     metadata:
      name:
      annotations:
      labels:
     description:
     multiTarget:
      targetIds: []

     requireApproval:
     run:
      location: projects/[project_name]/locations/[location]

     executionConfigs:
     - usages:
       - [RENDER | PREDEPLOY|  DEPLOY | VERIFY | POSTDEPLOY]
       workerPool:
       serviceAccount:
       artifactStorage:
       executionTimeout:

metadata.name

此目标的名称。此名称在每个区域必须是唯一的。

metadata.annotationsmetadata.labels

目标配置支持注释和标签,但 Cloud Deploy 不需要它们。

注释和标签与目标资源一起存储。如需了解详情,请参阅将标签和注释与 Cloud Deploy 搭配使用

description

此字段采用任意字符串,用于描述此目标的使用。

multiTarget.targetIds: []

此属性是可选的,用于配置要用于并行部署multi-target

该值是以英文逗号分隔的子目标列表。子目标配置为常规目标,并且不包含此 multiTarget 属性。

requireApproval

提升到此目标是否需要手动批准。可以是 truefalse

此为可选属性。默认值为 false

配置并行部署时,您可以仅要求批准多目标,而不是子目标。

run

将创建服务的位置(仅适用于 Cloud Run 服务):

run:
  location: projects/[project_name]/locations/[location]
  • project_name

    服务所在的 Google Cloud 项目。

  • location

    服务所在的位置。例如 us-central1

配置 [多目标] 时省略 run 属性。而是在相应的子目标内配置 Cloud Run 服务的位置。

如需了解执行环境属性的说明,请参阅本文中的 executionConfigs

对于 GKE Enterprise 目标

部署到 GKE 集群的目标配置与为 GKE 目标配置目标类似,只不过属性是 anthosCluster.membership,而不是 gke.cluster,资源路径不同,并且 internalIp 不适用。

anthosCluster:
  membership: projects/[project_name]/locations/global/memberships/[membership_name]
  • project_name

    GKE Enterprise 集群所在的 Google Cloud 项目。

  • /location/global/

    注册集群的位置。global

  • membership_name

    GKE Enterprise 集群成员资格的名称。

示例如下:

anthosCluster:
  membership: projects/cd-demo-01/locations/global/memberships/prod

配置 [多目标] 时省略 anthosCluster 属性。而是在相应的子目标内配置 GKE Enterprise 集群。

如需详细了解如何部署到 GKE 集群,请参阅部署到 Anthos 用户集群

对于自定义目标

自定义目标的配置与所有其他目标类型类似,只是它不包含 gke 节、run 节和 anthosCluster 节。

相反,自定义目标包括一个 customTarget 节:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

其中,CUSTOM_TARGET_TYPE_NAME 是您在自定义目标类型定义中使用的名称。

示例如下:

apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
  name: sample-env
customTarget:
  customTargetType: basic-custom-target

executionConfigs

用于为此目标指定非默认执行环境的一组字段。

  • usages

    RENDER 和/或 DEPLOY,以及 PREDEPLOYVERIFYPOSTDEPLOY(如果在目标上启用验证部署钩子)。它们指示使用此执行环境针对此目标执行其中哪些操作。如需指示将自定义执行环境用于部署前钩子、渲染、部署、部署后钩子和验证,请按如下方式配置执行环境:

    usages:
    - RENDER
    - PREDEPLOY
    - DEPLOY
    - VERIFY
    - POSTDEPLOY
    

    如果在流水线阶段启用了验证,并且您未在 usages 节中指定 VERIFY,则 Cloud Deploy 使用默认执行环境进行验证。部署前和部署后钩子的工作原理相同。

    但是,如果 RENDERDEPLOY 有自定义执行环境,则必须VERIFYPREDEPLOYPOSTDEPLOY 指定一个环境(如果在交付流水线中配置了这些环境)。VERIFYPREDEPLOYPOSTDEPLOY 可以与 RENDERDEPLOY 位于同一 usages 中,也可以位于单独的 usages 中。

    除非在相同或不同的自定义执行环境中指定了 RENDERDEPLOY,否则您不能指定 usages.VERIFYusages.PREDEPLOYusages.POSTDEPLOY

  • workerPool

    要使用的工作器池的配置。该操作需要一个资源路径来标识要用于此目标的 Cloud Build 工作器池。例如:

    projects/p123/locations/us-central1/workerPools/wp123.

    如需使用默认 Cloud Build 池,请忽略此属性。

    给定目标可以有两个 workerPool(一个用于 RENDER,一个用于 DEPLOY)。配置默认池时,您可以指定备用服务帐号和/或存储位置。

  • serviceAccount

    用于对此目标执行此操作的服务帐号的名称(RENDERDEPLOY)。

  • artifactStorage

    用于对此目标执行此操作的 Cloud Storage 存储桶(RENDERDEPLOY),而不是默认存储桶。

  • executionTimeout

    可选。为 Cloud Build 对 Cloud Deploy 执行的操作设置超时时间(以秒为单位)。默认为 3600 秒(1 小时)。
    示例:executionTimeout: "5000s"

支持的备用语法

本文档中介绍的 executionConfigs 配置是新配置。旧版语法仍受支持:

executionConfigs:
- privatePool:
    workerPool:
    serviceAccount:
    artifactStorage:
  usages:
  - [RENDER | DEPLOY]
- defaultPool:
    serviceAccount:
    artifactStorage:
  usages:
  - [RENDER | DEPLOY]

在为multi-target配置 executionConfigs 节时,每个子目标都可以从该多目标继承该执行环境

自定义目标类型定义

本部分介绍了用于定义自定义目标类型的字段

与标准目标和自动化操作一样,CustomTargetType 定义可包含在交付流水线定义中,也可以包含在单独的一个或多个文件中。

以下 YAML 展示了如何配置自定义目标类型:

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:
    - configs:
    # either:
    googleCloudStorage:
      source:
      path:
    # or:
    git:
      repo:
      path:
      ref:

其中:

  • [CUSTOM_TARGET_TYPE_NAME]

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

  • [RENDER_ACTION_NAME]

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

  • [DEPLOY_ACTION_NAME]

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

  • 对于 includeSkaffoldModules,请参阅使用远程 Skaffold 配置

Automation 定义

本部分介绍用于定义 Cloud Deploy 自动化资源的字段。

与目标一样,Automation 定义可以包含在交付流水线定义中,也可以包含在单独的一个或多个文件中。

如需详细了解 Cloud Deploy 中的自动化,请参阅自动化文档

以下 YAML 展示了如何配置自动化操作。请注意,自动化规则的具体情况因规则而异。(有关可用自动化规则类型的配置请参阅使用自动化规则文档。)

apiVersion: deploy.cloud.google.com/v1
kind: Automation
metadata:
  name: [PIPELINE_NAME]/[PURPOSE]
  labels:
  annotations:
description: [DESCRIPTION]
suspended: true | false
serviceAccount: [SERVICE_ACCOUNT_ID]
selector:
  targets:
    -  id: [TARGET_ID]
       labels:
         [LABEL_KEY]:[LABEL_VALUE]

rules:
- [RULE_TYPE]:
    name:[RULE_NAME]
  [RULE-SPECIFIC_CONFIG]

其中:

  • [PIPELINE_NAME]

    与使用此自动化功能的交付流水线中的 metadata.name 值相同。所有自动化操作都仅适用于创建它们的交付流水线。也就是说,您不能跨多个交付流水线共享自动化操作。

  • [PURPOSE]

    此自动化操作的任何其他描述性名称。通常情况下,这是系统自动执行的操作例如 my-app-pipeline/promote

  • labelsannotations 是您要与此自动化操作关联的任何标签或注解。

  • [DESCRIPTION]

    此自动化操作的说明(可选)。

  • suspended

    truefalse,用于指明这项自动化操作是处于启用还是已暂停状态。 如果设为 true,则系统不会使用自动化操作。这对于在不影响交付流水线的情况下测试自动化非常有用。

  • [SERVICE_ACCOUNT_ID]

    是用于执行自动化的服务帐号的 ID。例如,如果自动化操作使用 promoteReleaseRule,则此服务帐号会执行版本提升,因此需要提升版本提升所需的权限

    需要为此属性指定一个值。Cloud Deploy 不使用默认服务帐号来实现自动化。

    此服务帐号必须具有以下权限:

    • actAs 权限,用于模拟执行服务帐号。

    • 权限来执行自动化操作,例如,使用 clouddeploy.releases.promote 升级版本,或使用 clouddeploy.rollouts.advance 推进发布阶段。

  • [TARGET_ID]

    使用此自动化操作的目标的 ID。虽然自动化操作与交付流水线相关联,但它仅对指定的一个或多个目标执行。

    您可以将此属性设置为 *,以选择交付流水线中的所有目标。

  • [LABEL_KEY]:[LABEL_VALUE]

    是与目标上定义的键值对进行匹配的键值对。 这将选择与交付流水线关联的所有具有相同标签和值的目标。

  • [RULE_TYPE]

    用于此自动化操作的自动化规则的名称。可为 promoteReleaseRuleadvanceRolloutRule。您可以在自动化操作中添加多条规则,包括多条相同的 RULE_TYPE。例如,在同一项自动化操作中,可以有多条 promoteReleaseRule 规则。了解详情

  • [RULE_NAME]

    规则的名称。此名称在交付流水线中必须是唯一的。需要为此属性指定一个值。

  • [RULE-SPECIFIC_CONFIG]

    配置因每种受支持的自动化操作类型而异。如需了解这些配置,请参阅使用自动规则

后续步骤