版本：v1.3

补丁型特征

在自定义运维特征中，使用补丁型特征是一种比较常用的形式。

它让我们可以修改、补丁某些属性给组件对象（一般是工作负载）来完成特定操作，比如更新 sidecar 和节点亲和性（node affinity）的规则（并且，这个操作一定是在资源往集群部署前就已经生效）。

当我们的组件是从第三方提供并自定义而来的时候，由于它们的模版往往是固定不可变的，所以能使用补丁型特征就显得尤为有用了。

尽管运维特征是由 CUE 来定义，它能打补丁的组件类型并不限，不管是来自 CUE、Helm 还是其余支持的模版格式。

下面，我们通过一个节点亲和性（node affinity）的例子，讲解如何使用补丁型特征为组件打补丁：

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "affinity specify node affinity and toleration"
  6.   name: node-affinity
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: true
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         patch: {
  15.             spec: template: spec: {
  16.                 if parameter.affinity != _|_ {
  17.                     affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: [{
  18.                         matchExpressions: [
  19.                             for k, v in parameter.affinity {
  20.                                 key:      k
  21.                                 operator: "In"
  22.                                 values:   v
  23.                             },
  24.                         ]}]
  25.                 }
  26.                 if parameter.tolerations != _|_ {
  27.                     tolerations: [
  28.                         for k, v in parameter.tolerations {
  29.                             effect:   "NoSchedule"
  30.                             key:      k
  31.                             operator: "Equal"
  32.                             value:    v
  33.                         }]
  34.                 }
  35.             }
  36.         }
  38.         parameter: {
  39.             affinity?: [string]: [...string]
  40.             tolerations?: [string]: string
  41.         }

具体来说，我们上面的这个补丁型特征，假定了使用它的组件对象将会使用 spec.template.spec.affinity 这个字段。因此，我们需要用 appliesToWorkloads 来指明，让当前运维特征被应用到拥有这个字段的对应工作负载实例上。

另一个重要的字段是 podDisruptive，这个补丁型特征将修改 Pod 模板字段，因此对该运维特征的任何字段进行更改，都会导致 Pod 重启。我们应该增加 podDisruptive 并且设置它的值为 true，以此告诉用户这个运维特征生效后将导致 Pod 重新启动。

现在用户只需要，声明他们希望增加一个节点亲和性的规则到组件实例当中：

  1. apiVersion: core.oam.dev/v1alpha2
  2. kind: Application
  3. metadata:
  4.   name: testapp
  5. spec:
  6.   components:
  7.     - name: express-server
  8.       type: webservice
  9.       properties:
  10.         image: oamdev/testapp:v1
  11.       traits:
  12.         - type: "node-affinity"
  13.           properties:
  14.             affinity:
  15.               server-owner: ["owner1","owner2"]
  16.               resource-pool: ["pool1","pool2","pool3"]
  17.             tolerations:
  18.               resource-pool: "broken-pool1"
  19.               server-owner: "old-owner"

注意：该功能在 KubeVela 1.4 版本之后生效。

你还可以通过在 Definition 中使用 patchOutputs，来为其他运维特征打补丁。如：

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   name: patch-annotation
  5. spec:
  6.   appliesToWorkloads:
  7.     - deployments.apps
  8.   podDisruptive: true
  9.   schematic:
  10.     cue:
  11.       template: |
  12.         patchOutputs: {
  13.           ingress: {
  14.             metadata: annotations: {
  15.               "kubernetes.io/ingress.class": "istio"
  16.             }
  17.           }
  18.         }

上面的这个补丁型特征，假定了它绑定的组件还有别的运维特征，并且别的运维特征拥有 ingress 资源。该补丁型特征则会为这个 ingress 资源打上一个 istio 的 annotation。

我们可以部署如下应用来查看：

  1. apiVersion: core.oam.dev/v1alpha2
  2. kind: Application
  3. metadata:
  4.   name: testapp
  5. spec:
  6.   components:
  7.     - name: express-server
  8.       type: webservice
  9.       properties:
  10.         image: oamdev/testapp:v1
  11.       traits:
  12.         - type: "gateway"
  13.           properties:
  14.             domain: testsvc.example.com
  15.             http:
  16.               "/": 8000
  17.         - type: "patch-annotation"
  18.           properties:
  19.             name: "patch-annotation-trait"

应用成功运行后，ingress 资源如下：

  1. apiVersion: networking.k8s.io/v1beta1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     kubernetes.io/ingress.class: istio
  6.   name: ingress
  7. spec:
  8.   rules:
  9.   spec:
  10.     rules:
  11.     - host: testsvc.example.com
  12.       http:
  13.         paths:
  14.         - backend:
  15.             service:
  16.               name: express-server
  17.               port:
  18.                 number: 8000
  19.           path: /
  20.           pathType: ImplementationSpecific

默认来说，补丁型特征是通过 CUE 的 merge 操作来实现的。它有以下限制：

  • 不能处理有冲突的字段名
    • 比方说，在一个组件实例中已经设置过这样的值 replicas=5，那一旦有运维特征实例，尝试给 replicas 字段的值打补丁就会失败。所以我们建议你提前规划好，不要在组件和运维特征之间使用重复的字段名。
  • 数组列表被补丁时，会按索引顺序进行合并。如果数组里出现了重复的值，将导致问题。为了规避这个风险，请查询后面的解决方案。

策略补丁，通过增加注解（annotation）而生效，并支持如下两种模式。

请注意，这里开始并不是 CUE 官方提供的功能, 而是 KubeVela 扩展开发而来

这个注解，是给数组列表打补丁用的。它的执行方式也不遵循 CUE 官方的方式，而是将每一个数组列表视作对象，并执行如下的策略：

  • 如果发现重复的键名，补丁数据会直接替换掉它的值
  • 如果没有重复键名，补丁则会自动附加这些数据

下面来看看，一个使用 patchKey 的策略补丁：

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "add sidecar to the app"
  6.   name: sidecar
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: true
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         patch: {
  15.             // +patchKey=name
  16.             spec: template: spec: containers: [parameter]
  17.         }
  18.         parameter: {
  19.             name:  string
  20.             image: string
  21.             command?: [...string]
  22.         }

在上述的这个例子中，我们定义了要 patchKey 的字段 name，是来自容器的参数键名。如果工作负载中并没有同名的容器，那么一个 sidecar 容器就会被加到 spec.template.spec.containers 数组列表中。如果工作负载中有重名的 sidecar 运维特征，则会执行 merge 操作而不是附加。

在 KubeVela 1.4 版本之后，你可以使用 , 分割多个 patchKey，如 patchKey=name,image。

如果 patch 和 outputs 同时存在于一个运维特征定义中，patch 会率先被执行然后再渲染 outputs。

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "expose the app"
  6.   name: expose
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: true
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         patch: {spec: template: metadata: labels: app: context.name}
  15.         outputs: service: {
  16.             apiVersion: "v1"
  17.             kind:       "Service"
  18.             metadata: name: context.name
  19.             spec: {
  20.                 selector: app: context.name
  21.                 ports: [
  22.                     for k, v in parameter.http {
  23.                         port:       v
  24.                         targetPort: v
  25.                     },
  26.                 ]
  27.             }
  28.         }
  29.         parameter: {
  30.             http: [string]: int
  31.         }

在上面这个运维特征定义中，我们将会把一个 Service 添加到给定的组件实例上。同时会先去给工作负载类型打上补丁数据，然后基于模版里的 outputs 渲染余下的资源。

这个注解的策略，与 Kubernetes 官方的 retainKeys 策略类似。

在一些场景下，整个对象需要被一起替换掉，使用 retainKeys 就是最适合的办法。

假定一个 Deployment 对象是这样编写的：

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: retainkeys-demo
  5. spec:
  6.   selector:
  7.     matchLabels:
  8.       app: nginx
  9.   strategy:
  10.     type: rollingUpdate
  11.     rollingUpdate:
  12.       maxSurge: 30%
  13.   template:
  14.     metadata:
  15.       labels:
  16.         app: nginx
  17.     spec:
  18.       containers:
  19.       - name: retainkeys-demo-ctr
  20.         image: nginx

现在如果我们想替换掉 rollingUpdate 策略，你可以这样写：

  1. apiVersion: core.oam.dev/v1alpha2
  2. kind: TraitDefinition
  3. metadata:
  4.   name: recreate
  5. spec:
  6.   appliesToWorkloads:
  7.     - deployments.apps
  8.   extension:
  9.     template: |-
  10.       patch: {
  11.          spec: {
  12.               // +patchStrategy=retainKeys
  13.               strategy: type: "Recreate"
  14.            }
  15.       }

这个 YAML 资源将变更为：

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: retainkeys-demo
  5. spec:
  6.   selector:
  7.     matchLabels:
  8.       app: nginx
  9.   strategy:
  10.     type: Recreate
  11.   template:
  12.     metadata:
  13.       labels:
  14.         app: nginx
  15.     spec:
  16.       containers:
  17.       - name: retainkeys-demo-ctr
  18.         image: nginx

补丁型特征，针对组件层面做些整体操作时，非常有用。我们看看还可以满足哪些需求：

比如说，我们要给组件实例打上 virtualgroup 的通用标签。

  1. apiVersion: core.oam.dev/v1alpha2
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "Add virtual group labels"
  6.   name: virtualgroup
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: true
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         patch: {
  15.             spec: template: {
  16.                 metadata: labels: {
  17.                     if parameter.scope == "namespace" {
  18.                         "app.namespace.virtual.group": parameter.group
  19.                     }
  20.                     if parameter.scope == "cluster" {
  21.                         "app.cluster.virtual.group": parameter.group
  22.                     }
  23.                 }
  24.             }
  25.         }
  26.         parameter: {
  27.             group: *"default" | string
  28.             scope:  *"namespace" | string
  29.         }

然后这样用就可以了:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. spec:
  4.   ...
  5.       traits:
  6.       - type: virtualgroup
  7.         properties:
  8.           group: "my-group1"
  9.           scope: "cluster"

与通用标签类似，你也可以给组件实例打补丁，增加一些注解。注解的格式，必须是 JSON。

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "Specify auto scale by annotation"
  6.   name: kautoscale
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: false
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         import "encoding/json"
  16.         patch: {
  17.             metadata: annotations: {
  18.                 "my.custom.autoscale.annotation": json.Marshal({
  19.                     "minReplicas": parameter.min
  20.                     "maxReplicas": parameter.max
  21.                 })
  22.             }
  23.         }
  24.         parameter: {
  25.             min: *1 | int
  26.             max: *3 | int
  27.         }

给 Pod 去注入环境变量也是非常常见的操作。

这种使用方式依赖策略补丁而生效, 所以记得加上 +patchKey=name

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "add env into your pods"
  6.   name: env
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: true
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         patch: {
  15.             spec: template: spec: {
  16.                 // +patchKey=name
  17.                 containers: [{
  18.                     name: context.name
  19.                     // +patchStrategy=retainKeys
  20.                     env: [
  21.                         for k, v in parameter.env {
  22.                             name:  k
  23.                             value: v
  24.                         },
  25.                     ]
  26.                 }]
  27.             }
  28.         }
  30.         parameter: {
  31.             env: [string]: string
  32.         }

在这个场景下，service-account 是从一个鉴权服务中动态获取、再通过打补丁给到应用的。

我们这里展示的是，将 UID token 放进 HTTP header 的例子。你也可以用 HTTP body 来完成需求。

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "dynamically specify service account"
  6.   name: service-account
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: true
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         processing: {
  15.             output: {
  16.                 credentials?: string
  17.             }
  18.             http: {
  19.                 method: *"GET" | string
  20.                 url:    parameter.serviceURL
  21.                 request: {
  22.                     header: {
  23.                         "authorization.token": parameter.uidtoken
  24.                     }
  25.                 }
  26.             }
  27.         }
  28.         patch: {
  29.             spec: template: spec: serviceAccountName: processing.output.credentials
  30.         }
  32.         parameter: {
  33.             uidtoken:   string
  34.             serviceURL: string
  35.         }

InitContainer 常用于预定义镜像内的操作，并且在承载应用的容器运行前就跑起来。

看看示例:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "add an init container and use shared volume with pod"
  6.   name: init-container
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   podDisruptive: true
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         patch: {
  15.             spec: template: spec: {
  16.                 // +patchKey=name
  17.                 containers: [{
  18.                     name: context.name
  19.                     // +patchKey=name
  20.                     volumeMounts: [{
  21.                         name:      parameter.mountName
  22.                         mountPath: parameter.appMountPath
  23.                     }]
  24.                 }]
  25.                 initContainers: [{
  26.                     name:  parameter.name
  27.                     image: parameter.image
  28.                     if parameter.command != _|_ {
  29.                         command: parameter.command
  30.                     }
  32.                     // +patchKey=name
  33.                     volumeMounts: [{
  34.                         name:      parameter.mountName
  35.                         mountPath: parameter.initMountPath
  36.                     }]
  37.                 }]
  38.                 // +patchKey=name
  39.                 volumes: [{
  40.                     name: parameter.mountName
  41.                     emptyDir: {}
  42.                 }]
  43.             }
  44.         }
  46.         parameter: {
  47.             name:  string
  48.             image: string
  49.             command?: [...string]
  50.             mountName:     *"workdir" | string
  51.             appMountPath:  string
  52.             initMountPath: string
  53.         }

用法像这样:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: testapp
  5. spec:
  6.   components:
  7.     - name: express-server
  8.       type: webservice
  9.       properties:
  10.         image: oamdev/testapp:v1
  11.       traits:
  12.         - type: "init-container"
  13.           properties:
  14.             name:  "install-container"
  15.             image: "busybox"
  16.             command:
  17.             - wget
  18.             - "-O"
  19.             - "/work-dir/index.html"
  20.             - http://info.cern.ch
  21.             mountName: "workdir"
  22.             appMountPath:  "/usr/share/nginx/html"
  23.             initMountPath: "/work-dir"

Last updated on 2022年11月1日 by Tianxin Dong