将参数传递给部署

使用 Cloud Deploy，您可以传递版本的参数，这些值会先提供给一个或多个清单，然后再将这些清单应用于各自的目标。此替换在清单渲染之后完成，这是 Cloud Deploy 渲染操作中的最后一步。系统会向 skaffold.yaml 文件中标识的包含相应占位符的所有清单提供值。

您只需在清单中添加占位符，然后在 Cloud Deploy 交付流水线或目标配置中或在创建版本时设置这些占位符的值即可。

本文介绍了如何实现该目标。

为何使用部署参数？

其典型用途是将不同的值应用于并行部署中不同目标的清单。但是，您可以将部署参数用于任何需要在清单中进行渲染后键值对替换的任何内容。

运作方式

以下步骤介绍了配置部署参数并提供值的一般流程：

  1. 您可以按照此处所述的方法配置部署参数化。

    其中包括以下内容：

    • 将占位符添加到您的清单中。

    • 为这些占位符添加值。

      有三种方法可以执行此操作，请点击此处查看。

  2. 当您创建版本时，系统会呈现您的清单。

    如果您从模板化清单开始，现在将对模板变量应用值。如果您从原始清单开始，它保持不变。此渲染由 Skaffold 完成。

    不过，您的清单中还可以包含一些其他变量，这些变量的值不会在渲染时应用。以下是本文档中介绍的部署参数。

    在创建版本时，所有部署参数都会被编译到一个字典中，该字典用于在应用清单之前替换值。

  3. 渲染后，Cloud Deploy 会将部署参数的值替换为部署参数的值。

    这些值是您在第一步中配置的值。

    渲染流程已将值应用于清单模板，替换一些值，并添加特定于 Cloud Deploy 的标签。但是，这些部署参数的值会在渲染后被替换。如需了解清单模板和部署参数之间的区别，请点击此处。

  4. 该清单将应用于目标运行时，以部署应用。

    这包括在渲染时替换的值，以及任何部署参数的值

传递值的不同方法

您可以通过以下三种方式提供参数和参数值：

  • 在交付流水线定义中

    您需要在交付流水线进展中的某个阶段的定义中提供参数及其值。该参数会传递给该阶段所表示的目标。如果该阶段引用多目标，则此处设置的值将用于所有子目标。

    通过此方法，您可以替换给定流水线中所有受影响目标的所有版本的值。为阶段定义的参数用于标识标签，并且该阶段的相应目标必须具有匹配的标签。

  • 在目标定义中

    您可以在目标本身的定义中配置参数及其值。通过此方法，您可以为所有版本替换该目标的值。

  • 创建版本时，可以使用命令行

    您可以在 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 渲染程序与 Skaffold 搭配使用，请在 Helm 模板中使用以下语法添加占位符：

[PROPERTY]:  {{ .Values.VAR_NAME }}

向流水线阶段添加参数

您可以向交付流水线进度中的某个阶段添加键值对。 这对于并行部署非常有用，可区分子目标。

  1. 按照此处所述，将占位符添加到您的 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

  2. 配置交付流水线以包含适用于适用流水线阶段的 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，每个节都有以下内容：

    • 变量名称，与您在清单中设置的变量名称相同

    • 该变量的值

    • 要与目标特定标签匹配的一个或多个标签（可选）

      如果未指定标签，则在 matchTargetLabels 节中，该值将用于该阶段中的所有目标。

  3. 如果您添加了 matchTargetLabels，则还必须包含目标上的标签才能匹配它们。通过这种方式，您可以确定要将哪个值分配给哪个子目标。

    目标必须与 values 节中设置的所有标签匹配。

    如果省略 matchTargetLabels，则您在流水线上设置的 values 会应用于所有子目标。但是，如果您为同一参数设置了多个值，则发布将会失败。

呈现每个清单后，Cloud Deploy 会将每个变量的值添加到呈现的清单中。

向目标配置添加参数

您可以向目标添加键值对。如果您使用部署参数来区分多个子目标，请在这些子目标上而不是多目标上进行配置。

  1. 使用参数（代替您想要在部署时设置的值）来配置 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。

  2. 配置目标以包含 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 会将这些值添加到这些清单中。

在创建版本时传递参数

如需将参数和值传递给版本，请按以下步骤操作：

  1. 使用参数（而不是您想要在部署时设置的值）来配置 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}。

  2. 创建版本时，请在 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) 中。

  1. 在 Cloud Deploy 主页面中，点击包含要查看的版本的交付流水线。

  2. 在版本详情页面上，选择工件标签页。

为此版本设置的所有部署参数都显示在表中，其中一列为变量名称和值，另一列为受影响的目标。

部署 Google Cloud 控制台中显示的参数和值

后续步骤