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
,但您可以将以下项创建为 数量不限
本文档的其余部分定义这些组成部分。
流水线定义和进展
除了流水线元数据(例如 name
)之外,主要流水线定义还包括按部署序列顺序列出的对目标的引用列表。也就是说,列出的第一个目标是第一个部署目标。部署到该目标后,提升版本
将部署到列表中的下一个目标。
以下是交付流水线的配置属性,而非 包括目标定义。
metadata.name
name
字段采用的字符串对于每个项目和位置必须是唯一的。
metadata.annotations
和 metadata.labels
交付流水线配置可以包含注释和标签。在注册流水线后,注释和标签会与交付流水线资源一起存储。
如需了解详情,请参阅将标签和注解与 Cloud Deploy 搭配使用。
description
描述此交付流水线的任意字符串。此说明显示在 Google Cloud 控制台中的交付流水线详细信息中。
suspended
布尔值,如果 true
,则暂停交付流水线
使其无法用于创建、提升、回滚或重新部署版本。
此外,如果投放流水线被暂停,您将无法批准或拒绝通过该流水线创建的发布。
默认值为 false
。
serialPipeline
串行进度交付流水线的定义开头。此诗节是必需的。
stages
将此交付流水线配置为要部署到的所有目标的列表。
该列表必须采用所需的交付顺序。例如,如果您具有名为 dev
、staging
和 production
的目标,请按照相同的顺序列出它们,以便您的第一个部署是 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%,最后是完全百分比)。
部署策略按目标进行定义。例如,您可能有一个
Canary 策略是prod
目标,但标准策略(strategy
)。
如需了解详情,请参阅使用部署策略。
strategy
配置
本部分针对每种受支持的 strategy
配置元素
运行时。
标准部署策略
标准策略仅包含以下元素:
strategy:
standard:
verify: true|false
verify
是可选属性。默认值为 false
,表示
为最终发布的版本没有verify阶段。
对于标准,您可以省略 strategy
元素
部署策略
Canary 部署策略
以下部分介绍了 Canary 部署策略, Cloud Deploy 支持的每个运行时。
对于 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 展示了如何配置自定义
或custom-automated
Canary 部署策略特定于运行时的配置,位于
runtimeConfig
部分,自定义 Canary 中省略,但会包含在
自动化和自定义自动化 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
在此示例中,为键提供了两个值,而对于每个值, 有一个标签。该值会应用于具有匹配标签的任何目标的清单。
predeploy
和 postdeploy
作业
通过这些参数,您可以引用自定义操作,
(单独定义,
skaffold.yaml
)在部署作业 (predeploy
) 之前和验证之后运行
招聘信息,如果存在 (postdeploy
)。如果没有验证作业,则部署后作业
在部署作业之后运行
部署钩子在 strategy.standard
下配置,或
strategy.canary
,如下所示:
serialPipeline:
stages:
- targetId:
strategy:
standard:
predeploy:
actions: [ACTION_NAME]
postdeploy:
actions: [ACTION_NAME]
其中,ACTION_NAME 是在 skaffold.yaml
中配置的名称,
customActions.name
。
您可以在任何策略下配置 predeploy
和 postdeploy
作业
(例如 standard
、canary
)。
如需详细了解如何配置和使用部署前钩子和部署后钩子, 请参阅在部署之前和之后运行钩子。
目标定义
交付流水线定义文件可以包含目标定义,或者您可以在单独的文件中指定目标。您可以在项目中重复使用目标名称,但这些名称在交付流水线中必须是唯一的。
您可以在多个交付流水线中重复使用目标。但是,您只能在单个交付流水线的进展中引用目标一次。
另请参阅:自定义目标类型定义
对于 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:
verbose:
metadata.name
此目标的名称。此名称必须是全局唯一的。
“metadata.annotations
”和“metadata.labels
”
目标配置支持 Kubernetes 注释和标签, 但 Cloud Deploy 不需要它们
注释和标签与目标资源一起存储。如需更多信息 请参阅将标签和注释与 Cloud Deploy 搭配使用。
description
此字段采用任意字符串,用于描述此目标的使用。
deployParameters
您可以在任何目标上添加部署参数, 以及值这些值会分配给 并在呈现后创建
deployParameters
诗节采用键值对,如下所示:
deployParameters:
someKey: "someValue"
someOtherKey: "someOtherValue"
如果您在多目标上设置部署参数,系统会将该值分配给该多目标的所有子目标的清单。
multiTarget.targetIds: []
该值是以英文逗号分隔的子目标列表。
子目标配置为常规目标,不包含此 multiTarget
属性。
requireApproval
提升到此目标是否需要手动批准。可以是 true
或 false
。
此为可选属性。默认值为 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
配置多目标时,请省略 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:
verbose:
metadata.name
此目标的名称。每个地区的此名称必须是唯一的。
“metadata.annotations
”和“metadata.labels
”
目标配置支持注释和标签,但 Cloud Deploy 不需要它们。
注释和标签与目标资源一起存储。如需了解详情,请参阅将标签和注释与 Cloud Deploy 搭配使用。
description
此字段采用任意字符串,用于描述此目标的使用。
multiTarget.targetIds: []
该值是以英文逗号分隔的子目标列表。
子目标配置为常规目标,不包含此项
multiTarget
属性。
requireApproval
提升到此目标是否需要手动批准。可以是 true
或 false
。
此为可选属性。默认值为 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
配置 [multi-target] 时,请省略 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
,以及PREDEPLOY
、VERIFY
或POSTDEPLOY
(如果是验证或 在目标上启用部署钩子。 这些信息指明了 perform此目标 执行环境如需指示自定义执行环境将用于部署前钩子、渲染、部署、部署后钩子和验证,请按如下方式进行配置:usages: - RENDER - PREDEPLOY - DEPLOY - VERIFY - POSTDEPLOY
如果在流水线阶段启用了验证, 并且您没有在 Cloud Deploy 的
usages
节中指定VERIFY
使用默认执行环境进行验证。部署前和 部署后 hook 的工作原理相同。不过,如果
RENDER
和DEPLOY
有自定义执行环境,则您必须为VERIFY
、PREDEPLOY
或POSTDEPLOY
(如果它们在提交流水线上配置)指定一个自定义执行环境。VERIFY
PREDEPLOY
,并且POSTDEPLOY
可以与RENDER
或DEPLOY
位于同一usages
中,也可以位于单独的usages
中。您不能指定
usages.VERIFY
、usages.PREDEPLOY
或usages.POSTDEPLOY
除非在相同或单独的自定义属性中指定了RENDER
和DEPLOY
执行环境workerPool
要使用的工作器池的配置。此参数采用标识要为此目标使用的 Cloud Build 工作器池的资源路径。例如:
projects/p123/locations/us-central1/workerPools/wp123
。如需使用默认 Cloud Build 池,请执行以下操作: 请忽略此属性。
一个给定目标可以同时具有两个
workerPool
(一个用于RENDER
,一个用于DEPLOY
)。配置默认池时,您可以指定备用服务账号和/或存储位置。serviceAccount
要用于此操作的服务账号的名称(
RENDER
或DEPLOY
)。artifactStorage
为此目标执行此操作(
RENDER
或DEPLOY
)时要使用的 Cloud Storage 存储桶(而非默认存储桶)。executionTimeout
可选。设置 Cloud Build 为 Cloud Deploy 执行的操作的超时时间(以秒为单位)。默认值为
3600
秒(1 秒) 小时)。
示例:executionTimeout: "5000s"
verbose
可选。如果为
true
,则以下内容的详尽程度设置为debug
工具:Skaffold
--verbosity
设置为debug
。Skaffold 的默认值为warn
。kubectl
--v
已设为4
(调试)。kubectl 的默认值为2
。已设置 Google Cloud CLI
--verbosity
发送至debug
。默认值为warning
。
支持的其他语法
本文档中介绍的 executionConfigs
配置是新配置。通过
仍支持之前的语法:
executionConfigs:
- privatePool:
workerPool:
serviceAccount:
artifactStorage:
usages:
- [RENDER | DEPLOY]
- defaultPool:
serviceAccount:
artifactStorage:
usages:
- [RENDER | DEPLOY]
当您为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]
是自定义呈现操作的名称。该值是
customAction.name
在skaffold.yaml
中定义。[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
。labels
和annotations
是您要与此自动化操作关联的任何标签或注释。[DESCRIPTION]
此自动化操作的说明(可选)。
suspended
true
或false
,表示此自动化操作是处于启用还是暂停状态。如果设为true
,则系统不会使用自动化操作。这对于在不影响交付流水线的情况下测试自动化操作非常有用。[SERVICE_ACCOUNT_ID]
用于执行 自动化。 例如,如果自动化操作使用
promoteReleaseRule
,则以下代码 服务账号执行版本升级,因此需要 所需的权限 来推广一个版本此属性必须提供值。Cloud Deploy 不使用 默认服务账号 自动化操作。
此服务账号必须具有以下权限:
actAs
权限,用于模拟执行服务账号。执行要自动执行的操作的权限,例如使用
clouddeploy.releases.promote
提升版本,或使用clouddeploy.rollouts.advance
推进发布阶段。
[TARGET_ID]
使用此自动化操作的目标的 ID。虽然 都与交付流水线相关联,因此它仅在 一个或多个目标。
您可以将此属性设置为
*
,以选择交付流水线中的所有目标。[LABEL_KEY]:[LABEL_VALUE]
是与目标上定义的键值对进行匹配的键值对。 这会选择与提交流水线相关联且具有相同标签和值的所有目标。
[RULE_TYPE]
用于此自动化操作的自动化规则的名称。可以是
promoteReleaseRule
或advanceRolloutRule
。您可以添加多个 自动化规则,包括多个相同的RULE_TYPE
。对于 例如,您可以在同一条规则中设置多条promoteReleaseRule
规则 自动化。了解详情。[RULE_NAME]
规则的名称。此名称在交付流水线中必须是唯一的。此属性必须提供值。
[RULE-SPECIFIC_CONFIG]
每种支持的自动化操作类型的配置都不同。这些 配置显示在 使用自动化规则。
后续步骤
详细了解 Cloud Deploy 的工作原理。
了解如何为应用设置交付流水线。
了解如何管理清单。
了解流水线实例,以避免您的版本与交付流水线不匹配。