将参数传递给部署

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

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

本文介绍了如何实现这一点。

为何使用部署参数？

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

运作方式

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

  1. 您可以按照此处的说明配置部署参数化。

    这包括以下内容：

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

    • 请为这些占位符添加值。

      有 3 种方法可以执行此操作，详见此处。

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

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

    不过，您可以在清单中添加其他变量，这些变量的值在呈现时不会应用。这些是本文档中介绍的部署参数。

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

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

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

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

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

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

传递值的不同方式

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

  • 在交付流水线定义中

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

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

  • 在目标定义中

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

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

    您可以在 gcloud deploy releases create 命令中使用 --deploy-parameters 标志添加参数及其值。

    通过此方法，您可以在创建版本时替换某个值，并将该值应用于所有受影响目标的清单。

如需详细了解这些类型的配置，请点击此处。

我可以使用多种方法吗？

可以，您可以在流水线阶段、目标配置和命令行中添加部署参数。结果是所有参数都被接受并将其添加到字典中。但是，如果将某个特定参数传递到多个位置，但传递的值不同，则 gcloud deploy releases create 命令会失败并返回错误。

这与清单模板有何不同

本文中所述的部署参数与模板化清单中的占位符按语法syntax区分开来。但是，如果您想了解为什么需要部署参数，而不是对模板化清单使用标准方法，下表介绍了不同的用途：

方法 换货时间 适用对象
清单模板 渲染阶段 特定版本；特定目标
在命令行上 后渲染 特定版本；所有目标
在交付流水线上 后渲染 所有版本；特定目标（按标签）
在目标区间内 后渲染 所有版本；特定目标

本文仅介绍了部署参数（针对命令行、流水线和目标），而不是模板化清单。

限制

  • 对于每种参数类型，您最多可以创建 25 个参数。

  • 子目标还可以从其父级多目标中继承最多 25 个参数，在目标上最多可以继承 100 个参数（包括在流水线阶段设置的参数）。

  • 键名称不得超过 512 个字符，以及以下正则表达式：

    /^[a-zA-Z0-9][-A-Za-z0-9_.]{0,61}[a-zA-Z0-9]$/

  • 您不能将两个同名的键应用于同一定位条件。

  • 前缀 CLOUD_DEPLOY_ 已预留，无法用作键名。

配置部署参数

本部分介绍如何配置部署参数值，这些值将应用于 Kubernetes 清单或 Cloud Run 服务。

除了配置这些键值对之外，您还需要将占位符添加到清单中，如本部分中所述。

向清单添加占位符

在 Kubernetes 清单（对于 GKE）或服务 YAML（对于 Cloud Run）中，您可以为要在渲染后替换的任何值添加占位符。

语法

这些占位符使用以下语法：

[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

    是要替换的占位符。此键必须与交付流水线或目标配置中提供的键值对的键匹配，或者在创建版本时匹配。

向流水线阶段添加参数

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

  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 stanza 中，该值将用于该阶段中的所有目标。

  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

    在此示例中，部署中副本数设置为变量 $deploy_replicas。

    此变量的语法为 $ 加上变量名称。在此示例中为 $deploy_replicas。

  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 控制台中显示的部署参数和值

后续步骤