向部署传递参数

使用 Cloud Deploy,您可以为发布版本传递参数,这些值会在清单应用到各自的目标之前提供给清单。此替换操作是在清单rendered之后执行的,是 Cloud Deploy 呈现操作的最后一步。系统会为 skaffold.yaml 文件中包含相应占位符的所有已识别清单提供值。

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

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

为什么要使用部署参数?

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

工作原理

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

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

    这包括以下内容:

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

    • 为这些占位符添加值。

      您可以通过三种方法实现此目的,详情请参阅此处

  2. 创建发布版本时,系统会rendered清单。

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

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

    在创建发布版本时,所有部署参数都会编译成一个字典,用于在应用清单之前替换值。

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

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

    渲染过程已将值应用于清单模板,替换了一些值,并添加了 Cloud Deploy 特有的标签。但这些部署形参的值会在渲染后替换。有关清单模板与部署参数之间的差异,请参见此处

  4. 系统会将清单应用到目标运行时,以部署您的应用。

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

传递值的不同方式

您可以通过以下三种方式提供参数以及这些参数的值:

  • 在交付流水线定义中

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

    此方法可让您替换给定流水线中所有发布版本的值,以用于所有受影响的目标平台。为阶段定义的参数用于标识标签,相应阶段的目标必须具有匹配的标签。

  • 在目标定义中

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

  • 在命令行中创建发布版本时

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

    此方法可让您在创建发布版本时替换某个值,并将该值应用于所有受影响目标的相应清单。

如需详细了解这些配置,请点击此处

我可以同时使用多种方法吗?

可以,您可以在流水线阶段、目标配置命令行中添加部署参数。结果是,所有参数都被接受并添加到字典中。不过,如果某个特定形参在多个位置传递,但具有不同的值,则 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 模板中使用 {{ .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`.

向流水线阶段添加参数

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

  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 stanza 包含两个 values,每个 values 具有以下属性:

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

    • 相应变量的值

    • 一个或多个标签(可选),用于与特定于目标的标签进行匹配

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

  3. 如果您添加了 matchTargetLabels,还必须在目标上添加标签,以便匹配它们。这样,您就可以确定要为哪个子目标分配哪个值。

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

    如果您省略 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 的默认值设置为 example1envvar2 的默认值设置为 example2

  2. 配置目标以包含 deployParameters

    对于您要添加的每个形参,请确定以下内容:

    • 键名称,与您在清单中设置的键(变量)名称相同。

    • 相应键的值。如果您未提供值,系统会使用清单中设置的默认值。

    以下 YAML 是两个目标的配置。每个目标都包含一个用于设置值的 deployParameters stanza。每个目标还包含一个标签,用于与在流水线阶段配置的部署参数相匹配。

    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= 选项传递,如后续步骤所示。

    此变量的语法为 $ 加上大括号中的变量名称。在此示例中,该 IP 地址为 ${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 会将值提供给这些清单。

部署具有自定义目标的参数

您可以在自定义目标中使用任何部署参数作为环境变量。执行此操作时,请使用为自定义目标指定的语法

旨在作为自定义目标输入的部署参数可以以 customTarget/ 开头,例如 customTarget/vertexAIModel。如果您使用此前缀,请在将部署参数作为环境变量引用时使用以下语法:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

其中,VAR_NAMEdeploy 参数名称中斜线后面的名称。例如,如果您定义了一个名为 customTarget/vertexAIModel 的部署参数,请以 CLOUD_DEPLOY_customTarget_vertexAIModel 形式引用该参数。

包含部署钩子的部署参数

您可以在部署钩子中使用任何部署参数作为环境变量。

使用部署验证功能部署参数

您可以在部署验证中使用任何部署参数作为环境变量。

查看发布版本的所有参数

您可以查看为指定版本设置的参数。它们会显示在版本详细信息页面和命令行 (gcloud deploy releases describe) 的表格中。

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

  2. 发布版本详情页面上,选择工件标签页。

为相应版本设置的所有部署参数都会显示在一个表格中,其中一列包含变量名称和值,另一列包含受影响的目标。

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

后续步骤