将参数传递给部署

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

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

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

为何使用部署参数?

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

工作原理

以下步骤介绍了配置部署的常规过程 并提供相应的值:

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

    这包括以下内容:

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

    • 为这些占位符添加值。

      为此,您可以采用三种方法(详见此处)。

  2. 创建版本时,您的清单 已渲染

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

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

    在创建版本时,所有部署参数都会编译到 字典,用于替换 清单。

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

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

    呈现流程已将值应用到清单模板, 替换某些值,以及添加 Cloud Deploy。但这些部署参数的值是 会在呈现后被替换为替代值清单模板与 Deployment 参数 此处

  4. 该清单会应用于目标运行时,以部署您的应用。

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

传递值的不同方式

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

  • 在交付流水线定义中

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

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

  • 在目标定义中

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

  • 在命令行中创建版本时

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

    通过此方法,您可以在创建版本时替换值,应用该值 值添加到所有受影响目标的清单中。

更详细地介绍了这些对象的配置 此处

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

可以,您可以在流水线阶段、目标配置中以及命令行中添加部署参数。结果就是,所有参数 并添加到字典中。但是,如果将特定参数 但在多个位置使用不同值时,gcloud deploy releases create 命令会失败并显示错误。

这与清单模板有何不同

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

方法 替换时间 适用对象
清单模板 渲染阶段 特定版本;特定目标平台
在命令行中 呈现后 特定版本;所有目标
在交付流水线上 呈现后 所有版本;具体目标(按标签)
符合目标 呈现后 所有版本;具体目标

本文档仅介绍了部署参数(在命令行、流水线和 目标),而不是 模板化清单

限制

  • 对于每种参数类型,您最多可以创建 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 个字符。

  • 部署参数占位符不能用于 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: 则告知 deploy-parameters 占位符后跟的 Cloud Deploy。

  • ${VAR_NAME}

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

Helm 图表值的参数

如果您要渲染一个接受 配置值, 您希望使用部署参数、部署参数 其名称必须与您要设置的 Helm 配置值一致。 所有部署参数在渲染时都会作为 --set 参数传递给 Helm, 无需修改skaffold.yaml

例如,如果您的 skaffold.yaml 正在安装一个 Helm 图表,该图表接受 webserver.port 的配置参数,用于指定 Web 服务器的端口 您希望从部署作业中 参数,您需要创建一个部署参数,参数为 将名称 webserver.port 替换为您希望 Web 服务器端口使用的值。

因此,如果您不仅在 skaffold.yaml 中引用 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`.

向流水线阶段添加参数

您可以向传送流水线进程中的某个阶段添加键值对。这对于并行部署非常有用, 。

  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,每个 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 清单或 使用参数代替 部署所需的值

    示例如下:

    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_NAME部署参数名称。例如,如果您定义了一个名为 customTarget/vertexAIModel 的部署参数,请以 CLOUD_DEPLOY_customTarget_vertexAIModel 的形式引用该参数。

使用部署钩子部署参数

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

部署参数(包含部署验证)

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

查看版本的所有参数

您可以查看为指定版本设置的参数。它们是 以表格形式显示版本详情页面和命令行 (gcloud deploy releases describe).

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

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

已为此版本设置的所有部署参数都显示在表格中, 在一列中使用变量名称和值,以及受影响的目标或 目标。

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

后续步骤