配置架构参考文档

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:
#
# 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,但您可以根据需要创建任意多个。

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

流水线定义和进展

除了流水线元数据(例如 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 属性。

设置为 truestrategy.standard.verify 会为目标启用部署验证。如果未指定部署策略,则会使用 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) 之前以及验证作业(如果存在)之后 (postdeploy) 运行的自定义操作(单独定义,具体定义请参见 skaffold.yaml)。如果没有验证作业,则部署后作业会在部署作业之后运行。

部署钩子在 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:

     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

对于 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]

    每种支持的自动出价类型都有不同的配置。如需了解这些配置,请参阅使用自动化规则

后续步骤