使用 Cloud Deploy,您可以为版本传递参数,并将这些值提供给一个或多个清单,然后再将这些清单应用到相应的目标。此替换在清单渲染后完成,这是 Cloud Deploy 渲染操作中的最后一步。值将提供给 skaffold.yaml
文件中标识的所有包含相应占位符的清单。
您只需在清单中添加占位符,并在 Cloud Deploy 交付流水线或目标配置中,或者在创建版本时设置这些占位符的值。
本文介绍了如何实现这一点。
为什么要使用部署参数?
此操作的一个典型用途是,在并行部署中对不同目标的清单应用不同的值。但是,您可以将部署参数用于需要在清单中替换渲染后键值对的任何项目。
工作原理
以下步骤介绍了配置部署参数并提供值的一般过程:
您可以按照此处的说明配置部署参数化。
其中包括以下内容:
将占位符添加到清单中。
为这些占位符添加值。
为此,您可以采用三种方法(详见此处)。
-
如果您从模板化清单着手,值现在会应用于模板变量。如果您从原始清单开始,它保持不变。此渲染由 Skaffold 完成。
不过,清单中可以包含其他变量,对于这些变量,渲染时未对其应用值。这些是本文档中介绍的部署参数。
在创建版本时,所有部署参数都会编译到一个字典中,该字典用于在应用清单之前替换值。
渲染后,Cloud Deploy 会替换部署参数的值。
这些值是您在第一步中配置的值。
渲染过程已将值应用于清单模板,替换了一些值,并添加了特定于 Cloud Deploy 的标签。但这些部署参数的值将在渲染后替换。如需了解清单模板和部署参数之间的区别,请点击此处。
该清单会应用于目标运行时,以部署您的应用。
这包括渲染时替换的值,以及任何部署参数的值
传递值的不同方式
您可以通过以下三种方式为这些参数提供参数和值:
-
您可以在交付流水线进度中某个阶段的定义中提供该参数及其值。该参数会传递给该阶段表示的目标。如果该阶段引用多目标,则此处设置的值将用于所有子目标。
通过此方法,您可以为给定流水线中所有受影响的目标替换所有版本的值。为阶段定义的参数用于标识标签,并且该阶段的相应目标必须具有匹配的标签。
-
您可以在目标本身的定义中配置该参数及其值。通过此方法,您可以为所有版本替换该目标的值。
在命令行上创建版本时
您可以在
gcloud deploy releases create
命令中使用--deploy-parameters
标志添加该参数及其值。通过此方法,您可以在创建版本时替换某个值,将该值应用于所有受影响目标的清单中。
此处详细介绍了这些对象的配置。
我可以使用上述多种方法吗?
可以,您可以在流水线阶段、目标配置和命令行中添加部署参数。结果就是,系统会接受所有参数并将其添加到字典中。但是,如果在多个位置传递了具有不同值的特定参数,则 gcloud deploy releases
create
命令会失败并显示错误。
使用自定义目标部署参数
您可以将任何部署参数用作自定义目标中的环境变量。在执行此操作时,请使用为自定义目标指定的syntax。
这与清单模板有何不同
本文中所述的部署参数通过语法syntax与模板化清单中的占位符区分开来。但是,如果您想知道为什么需要部署参数,而不是仅使用模板化清单的标准技术,请参阅下表显示了不同的用途:
分析法 | 替换时间 | 适用对象 |
---|---|---|
清单模板 | 渲染阶段 | 特定版本;特定目标 |
在命令行上 | 呈现后 | 特定版本;所有目标 |
在交付流水线上 | 呈现后 | 所有版本;特定目标(按标签) |
符合目标 | 呈现后 | 所有版本;具体目标 |
本文档仅介绍了部署参数(针对命令行、流水线和目标),而不是模板化清单。
限制
对于每种参数类型,您最多可以创建 25 个参数。
此外,子目标还可以从其父多目标继承最多 25 个参数,目标最多包含 100 个参数,包括在流水线阶段设置的参数。
键名称不得超过 63 个字符,且包含以下正则表达式:
^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$
一种例外情况是,在自定义目标中将部署参数用作环境变量时,必须在关键字
customTarget
和变量名称 (customTarget/VAR_NAME
) 之间使用斜杠。如需了解受支持的语法,请参阅必需的输入和输出。前缀
CLOUD_DEPLOY_
已预留,不能用于键名。不能将两个同名的键应用于同一目标。
该值可以为空,但最多包含 512 个字符。
配置部署参数
本部分介绍如何配置将应用于 Kubernetes 清单、Cloud Run 服务或 Helm 模板的部署参数值。
除了配置这些键值对之外,您还需要向清单中添加一个或多个占位符,如本部分所述。
向清单中添加占位符
在 Kubernetes 清单(对于 GKE)或服务 YAML(对于 Cloud Run)中,为要在渲染后替换的任何值添加占位符。
语法
对于未将 Helm 渲染程序与 Skaffold 搭配使用的版本,请使用以下语法作为占位符:
[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}
在此行中...
PROPERTY:
是 Kubernetes 清单或 Cloud Run 服务 YAML 中的配置属性。
DEFAULT_VALUE
如果没有在命令行、流水线或目标配置中为此属性提供任何值,则使用该值。
# from-param:
使用注释字符触发 Cloud Deploy
deploy-parameters
指令,from-param:
会告知 Cloud Deploy 跟在deploy-parameters
占位符。${VAR_NAME}
要替换的占位符。此键值对必须与交付流水线或目标配置中提供的或创建版本时提供的键值对的键匹配。
Helm 图表值的参数
如果您要渲染接受配置值的 Helm 图表,并且想要使用部署参数设置这些值,则部署参数的名称必须与您要设置的 Helm 配置值一致。
所有部署参数会在渲染时作为 --set
参数传递给 Helm,无需修改 skaffold.yaml
。
例如,如果您的 skaffold.yaml
要安装一个 Helm 图表,该图表使用 webserver.port
配置参数指定 Web 服务器启动的端口,并且您希望通过部署参数动态设置此设置,则需要创建一个名为 webserver.port
的部署参数,该参数具有您想要用于 Web 服务器端口的值。
因此,如果您不仅在 skaffold.yaml
中引用 Helm 模板,而且还要编写这些模板,那么您可以在 Helm 模板中使用 {{ .Values.VAR_NAME }}
的标准 Helm 变量语法。
例如,如果我们配置了 webserver.port
的部署参数,则可以这样使用:
apiVersion: apps/v1
kind: Deployment
metadata:
name: webserver
spec:
replicas: 3
selector:
matchLabels:
app: webserver
template:
metadata:
labels:
app: webserver
spec:
containers:
- name: webserver
image: gcr.io/example/webserver:latest
ports:
- containerPort: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
name: web
env:
- name: WEBSERVER_PORT
value: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
向流水线阶段添加参数
您可以将键值对添加到交付流水线进程中的某个阶段。这对于并行部署非常有用,有助于区分子目标。
按照此处的说明,将占位符添加到您的 Kubernetes 清单或 Cloud Run 服务。
示例如下:
apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: replicas: 1 # from-param: ${deploy_replicas} selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.14.2 ports: - containerPort: 80
将交付流水线配置为包含适用的流水线阶段的
deployParameters
。以下 YAML 是目标为多目标(在本例中有两个子目标)的流水线阶段的配置:
serialPipeline: stages: - targetId: dev profiles: [] - targetId: prod # multi-target profiles: [] deployParameters: - values: deploy_replicas: 1 log_level: "NOTICE" matchTargetLabels: # optional, applies to all resources if unspecified; AND'd my-app: "post-render-config-1" - values: deploy_replicas: 2 log_level: "WARNING" matchTargetLabels: # optional, applies to all resources if unspecified; AND'd my-app: "post-render-config-2"
在此交付流水线配置中,
deployParameters
节包含两个values
,每个values
均包含以下内容:变量名称,与您在清单中设置的变量相同
该变量的值
用于与目标专用标签匹配的一个或多个标签(可选)
如果未指定标签,则在
matchTargetLabels
节中,该值将用于阶段中的所有目标。
如果您添加了
matchTargetLabels
,则还必须为目标添加标签以匹配这些目标。这样,您就可以确定要为哪个子目标分配哪个值。目标必须与
values
节中设置的所有标签匹配。如果省略
matchTargetLabels
,则您在流水线中设置的values
将应用于所有子目标。但是,如果您为同一参数设置了多个值,则发布会失败。
在每个清单呈现后,Cloud Deploy 会将每个变量的值添加到呈现的清单中。
向目标配置添加参数
您可以向目标添加键值对。如果您使用部署参数区分多个子目标,请在这些子目标(而不是多目标)上配置这些参数。
使用参数代替您想要在部署时设置的值来配置 Kubernetes 清单或 Cloud Run 服务定义。
示例如下:
apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.14.2 env: - name: envvar1 value: example1 # from-param: ${application_env1} - name: envvar2 value: example2 # from-param: ${application_env2}
在此清单中,参数
envvar1
设置为默认值example1
,envvar2
设置为默认值example2
。将目标配置为包含
deployParameters
。对于要添加的每个参数,都要标识以下内容:
键名称,即您在清单中设置的键(变量)的名称。
该键的值。如果您未提供值,系统将使用清单中设置的默认值。
以下 YAML 是两个目标的配置。每个目标都包含一个用于设置值的
deployParameters
节。每个目标还包含一个标签,该标签将与在流水线阶段上配置的部署参数匹配。apiVersion: deploy.cloud.google.com/v1beta1 kind: Target metadata: name: prod1 labels: my-app: "post-render-config-1" description: development cluster deployParameters: application_env1: "newValue1" --- apiVersion: deploy.cloud.google.com/v1beta1 kind: target metadata: name: prod2 labels: my-app: "post-render-config-2" description: development cluster deployParameters: application_env1: "newValue2"
在创建版本后,在呈现清单后,Cloud Deploy 会将这些值添加到呈现的清单中(如果它们包含关联的键)。
在创建版本时传递参数
请按照以下步骤将参数和值传递给版本:
使用参数代替您要在部署时设置的值来配置 Kubernetes 清单或 Cloud Run 服务定义。
示例如下:
apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: selector: matchLabels: app: nginx template: metadata: labels: app: nginx annotations: commit: defaultShaValue # from-param: ${git-sha} spec: containers: - name: nginx image: nginx:1.14.2
在此示例中,提交 SHA 被设置为名为
${git-sha}
的变量。此值会在创建版本时使用--deploy-parameters=
选项传递,如下一步所示。此变量的语法是
$
加上变量名称(放在大括号中)。在此示例中,它是${git-sha}
。创建版本时,请在
gcloud deploy releases create
命令中添加--deploy-parameters
选项。--deploy-parameters
接受以英文逗号分隔的键值对列表,其中键是您添加到清单中的占位符。该命令将如下所示:
gcloud deploy releases create test-release-001 \ --project=my-example-project \ --region=us-central1 \ --delivery-pipeline=my-params-demo-app-1 \ --images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa \ --deploy-parameters="git-sha=f787cac"
创建版本后,在清单渲染后,Cloud Deploy 会向渲染的清单提供值(如果它们包含关联的键)。
查看版本的所有参数
您可以查看为指定版本设置的参数。它们显示在版本详情页面上的表格中,以及命令行 (gcloud deploy releases describe
) 上。
在 Cloud Deploy 主页面上,点击包含要查看的版本的交付流水线。
在版本详情页面上,选择软件工件标签页。
已为此版本设置的所有部署参数都显示在表中,其中一列为变量名称和值,另一列中为一个或多个受影响的目标。
后续步骤
尝试阅读《快速入门:使用部署参数》。
详细了解如何使用并行部署。