向部署传递参数

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

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

本文介绍了如何实现此目的。

为什么要使用部署参数？

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

工作原理

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

  1. 您需要配置部署参数化，如此处所述 。

    这包括以下内容：

    • 将占位符添加到清单，包括每个占位符的默认值。

    • 为这些占位符添加值。

      您可以通过三种方式执行此操作，如此处所述here。

  2. 创建版本时，系统会 渲染清单。

    如果您从模板化清单开始，系统现在会为模板变量应用值。如果您从原始清单开始，则清单保持不变。此 渲染由 Skaffold 完成。

    不过，您的清单中可能包含其他变量，这些变量的值在呈现时不会应用。这些是本文档中所述的部署参数。

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

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

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

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

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

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

传递值的不同方式

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

  • 在交付流水线定义中

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

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

  • 在目标定义中

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

  • 在命令行中创建版本时

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

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

此处更详细地介绍了这些配置 here。

我可以使用多种方法吗？

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

这与清单模板有何不同

如本文中所述，部署参数与 模板化清单中的占位符的区别在于语法。但是，如果您想知道为什么需要部署参数而不是仅使用模板化清单的标准技术，下表显示了不同的用途：

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

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

限制

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

  • 此外，子目标最多可以从其父级多目标继承 50 个参数，目标上的参数总数最多为 200 个，包括在流水线阶段设置的参数。

  • 键名称的长度上限为 63 个字符，并且必须符合以下正则表达式：

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

    但有一种情况例外：当您在自定义目标中使用部署参数作为 环境变量时，必须在 关键字 customTarget 和变量名称 (customTarget/VAR_NAME) 之间使用斜杠。如需了解支持的语法，请参阅 必需的输入和输出 。

  • 前缀 CLOUD_DEPLOY_ 已预留，不能用于键名称。

  • 您不能将两个同名的键应用于同一目标。

  • 值可以为空，但最多包含 512 个字符。

  • 部署参数占位符不能用于 Helm 配置值， 但必须按照惯例传递。

配置部署参数

本部分介绍了如何配置将应用于 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}

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

您还可以在一行中使用多个参数，并将参数用作较长字符串的一部分，例如：

image: my-image # from-param: ${artifactRegion}-docker.pkg.dev/my-project/my-repo/my-image@sha256:${imageSha}

这些参数可以来自多个来源。在前面的示例中，${artifactRegion} 可能会在目标或交付流水线阶段定义，而 ${imageSha} 会在创建版本时从命令行获取。

Helm 图表值的参数

如果您要渲染接受 配置值的 Helm 图表， 并且想要使用部署参数设置这些值，则部署参数 的名称必须与您要设置的 Helm 配置值匹配。 所有部署参数在呈现时都会作为 --set 参数传递给 Helm， 无需修改 skaffold.yaml。

例如，如果您的 skaffold.yaml 安装的 Helm 图表采用 webserver.port 配置参数来指定 Web 服务器将启动的端口，并且您想要通过部署参数动态设置此参数，则需要创建一个名为 webserver.port 的部署参数，并为 Web 服务器端口设置所需的值。

因此，如果您不仅在 skaffold.yaml 中引用 Helm 模板， 还编写 Helm 模板，则可以在 Helm 模板中使用 标准 Helm 变量语法 的 {{ .Values.VAR_NAME }}。

例如，如果我们配置了 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`.

向流水线阶段添加参数

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