Version: v1.2

自定义组件入门

在阅读本部分之前，请确保你已经了解 KubeVela 中 组件定义（ComponentDefinition 的概念且学习掌握了 CUE 的基本知识

本节将以组件定义的例子展开说明，介绍如何使用 CUE 通过组件定义 ComponentDefinition 来自定义应用部署计划的组件。

交付一个简单的自定义组件

我们可以通过 vela def init 来根据已有的 YAML 文件来生成一个 ComponentDefinition 模板。

YAML 文件：

  1. apiVersion: "apps/v1"
  3. kind: "Deployment"
  5. spec:
  7.   selector:
  9.     matchLabels:
  11.       "app.oam.dev/component": "name"
  13.   template:
  15.     metadata:
  17.       labels:
  19.         "app.oam.dev/component": "name"
  21.     spec:
  23.       containers: 
  25.       - name: "name"
  27.         image: "image"

根据以上的 YAML 来生成 ComponentDefinition：

  1. vela def init stateless -t component --template-yaml ./stateless.yaml -o stateless.cue

得到如下结果：

  1. $ cat stateless.cue
  3. stateless: {
  5.     annotations: {}
  7.     attributes: workload: definition: {
  9.         apiVersion: "<change me> apps/v1"
  11.         kind:       "<change me> Deployment"
  13.     }
  15.     description: ""
  17.     labels: {}
  19.     type: "component"
  21. }
  26. template: {
  28.     output: {
  30.         spec: {
  32.             selector: matchLabels: "app.oam.dev/component": "name"
  34.             template: {
  36.                 metadata: labels: "app.oam.dev/component": "name"
  38.                 spec: containers: [{
  40.                     name:  "name"
  42.                     image: "image"
  44.                 }]
  46.             }
  48.         }
  50.         apiVersion: "apps/v1"
  52.         kind:       "Deployment"
  54.     }
  56.     outputs: {}
  58.     parameters: {}
  60. }

在这个自动生成的模板中：

  • 需要 .spec.workload 来指示该组件的工作负载类型。
  • .spec.schematic.cue.template 是一个 CUE 模板：
    • output 字段定义了 CUE 要输出的抽象模板。
    • parameter 字段定义了模板参数，即在应用部署计划（Application）中公开的可配置属性（KubeVela 将基于 parameter 字段自动生成 Json schema）。

下面我们来给这个自动生成的自定义组件添加参数并进行赋值：

  1. stateless: {
  3.     annotations: {}
  5.     attributes: workload: definition: {
  7.         apiVersion: "<change me> apps/v1"
  9.         kind:       "<change me> Deployment"
  11.     }
  13.     description: ""
  15.     labels: {}
  17.     type: "component"
  19. }
  24. template: {
  26.     output: {
  28.         spec: {
  30.             selector: matchLabels: "app.oam.dev/component": parameter.name
  32.             template: {
  34.                 metadata: labels: "app.oam.dev/component": parameter.name
  36.                 spec: containers: [{
  38.                     name:  parameter.name
  40.                     image: parameter.image
  42.                 }]
  44.             }
  46.         }
  48.         apiVersion: "apps/v1"
  50.         kind:       "Deployment"
  52.     }
  54.     outputs: {}
  56.     parameters: {
  58.     name: string
  60.     image: string
  62.   }
  64. }

修改后可以用 vela def vet 做一下格式检查和校验。

  1. $ vela def vet stateless.cue
  3. Validation succeed.

接着，让我们声明另一个名为 task 的组件。

  1. vela def init task -t component -o task.cue

得到如下结果：

  1. $ cat task.cue
  3. task: {
  5.     annotations: {}
  7.     attributes: workload: definition: {
  9.         apiVersion: "<change me> apps/v1"
  11.         kind:       "<change me> Deployment"
  13.     }
  15.     description: ""
  17.     labels: {}
  19.     type: "component"
  21. }
  26. template: {
  28.     output: {}
  30.     parameter: {}
  32. }

修改该组件定义：

  1. task: {
  3.     annotations: {}
  5.     attributes: workload: definition: {
  7.         apiVersion: "batch/v1"
  9.         kind:       "Job"
  11.     }
  13.     description: ""
  15.     labels: {}
  17.     type: "component"
  19. }
  24. template: {
  26.   output: {
  28.     apiVersion: "batch/v1"
  30.     kind:       "Job"
  32.     spec: {
  34.       parallelism: parameter.count
  36.       completions: parameter.count
  38.       template: spec: {
  40.         restartPolicy: parameter.restart
  42.         containers: [{
  44.           image: parameter.image
  46.           if parameter["cmd"] != _|_ {
  48.             command: parameter.cmd
  50.           }
  52.         }]
  54.       }
  56.     }
  58.   }
  60.     parameter: {
  62.     count:   *1 | int
  64.     image:   string
  66.     restart: *"Never" | string
  68.     cmd?: [...string]
  70.   }
  72. }

将以上两个组件定义部署到集群中：

  1. $ vela def apply stateless.cue
  3. ComponentDefinition stateless created in namespace vela-system.
  5. $ vela def apply task.cue
  7. ComponentDefinition task created in namespace vela-system.

这两个已经定义好的组件，最终会在应用部署计划中实例化，我们引用自定义的组件类型 stateless，命名为 hello。同样，我们也引用了自定义的第二个组件类型 task，并命令为 countdown。

然后把它们编写到应用部署计划中，如下所示：

  1. apiVersion: core.oam.dev/v1alpha2
  3. kind: Application
  5. metadata:
  7.   name: website
  9. spec:
  11.   components:
  13.     - name: hello
  15.       type: stateless
  17.       properties:
  19.         image: crccheck/hello-world
  21.         name: mysvc
  23.     - name: countdown
  25.       type: task
  27.       properties:
  29.         image: centos:7
  31.         cmd:
  33.           - "bin/bash"
  35.           - "-c"
  37.           - "for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done"

以上，我们就完成了一个自定义应用组件的应用交付全过程。值得注意的是，作为管理员的我们，可以通过 CUE 提供用户所需要的任何自定义组件类型，同时也为用户提供了模板参数 parameter 来灵活地指定对 Kubernetes 相关资源的要求。

查看 Kubernetes 最终资源信息

  1. apiVersion: apps/v1
  3. kind: Deployment
  5. metadata:
  7.   name: backend
  9.   ... # 隐藏一些与本小节讲解无关的信息
  11. spec:
  13.   template:
  15.     spec:
  17.       containers:
  19.         - name: mysvc
  21.           image: crccheck/hello-world
  23.     metadata:
  25.       labels:
  27.         app.oam.dev/component: mysvc
  29.   selector:
  31.     matchLabels:
  33.       app.oam.dev/component: mysvc
  35. ---
  37. apiVersion: batch/v1
  39. kind: Job
  41. metadata:
  43.   name: countdown
  45.   ... # 隐藏一些与本小节讲解无关的信息
  47. spec:
  49.   parallelism: 1
  51.   completions: 1
  53.   template:
  55.     metadata:
  57.       name: countdown
  59.     spec:
  61.       containers:
  63.         - name: countdown
  65.           image: 'centos:7'
  67.           command:
  69.             - bin/bash
  71.             - '-c'
  73.             - for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done
  75.       restartPolicy: Never

交付一个复合的自定义组件

除了上面这个例子外，一个组件的定义通常也会由多个 Kubernetes API 资源组成。例如，一个由 Deployment 和 Service 组成的 webserver 组件。CUE 同样能很好的满足这种自定义复合组件的需求。

我们会使用 output 这个字段来定义工作负载类型的模板，而其他剩下的资源模板，都在 outputs 这个字段里进行声明，格式如下：

  1. outputs: <unique-name>: 
  3.   <full template data>

回到 webserver 这个复合自定义组件上，它的 CUE 文件编写如下：

  1. webserver: {
  3.     annotations: {}
  5.     attributes: workload: definition: {
  7.         apiVersion: "apps/v1"
  9.         kind:       "Deployment"
  11.     }
  13.     description: ""
  15.     labels: {}
  17.     type: "component"
  19. }
  24. template: {
  26.   output: {
  28.     apiVersion: "apps/v1"
  30.     kind:       "Deployment"
  32.     spec: {
  34.       selector: matchLabels: {
  36.         "app.oam.dev/component": context.name
  38.       }
  40.       template: {
  42.         metadata: labels: {
  44.           "app.oam.dev/component": context.name
  46.         }
  48.         spec: {
  50.           containers: [{
  52.             name:  context.name
  54.             image: parameter.image
  59.             if parameter["cmd"] != _|_ {
  61.               command: parameter.cmd
  63.             }
  68.             if parameter["env"] != _|_ {
  70.               env: parameter.env
  72.             }
  77.             if context["config"] != _|_ {
  79.               env: context.config
  81.             }
  86.             ports: [{
  88.               containerPort: parameter.port
  90.             }]
  95.             if parameter["cpu"] != _|_ {
  97.               resources: {
  99.                 limits:
  101.                   cpu: parameter.cpu
  103.                 requests:
  105.                   cpu: parameter.cpu
  107.               }
  109.             }
  111.           }]
  113.         }
  115.       }
  117.     }
  119.   }
  121.   // an extra template
  123.   outputs: service: {
  125.     apiVersion: "v1"
  127.     kind:       "Service"
  129.     spec: {
  131.       selector: {
  133.         "app.oam.dev/component": context.name
  135.       }
  137.       ports: [
  139.         {
  141.           port:       parameter.port
  143.           targetPort: parameter.port
  145.         },
  147.       ]
  149.     }
  151.   }
  153.     parameter: {
  155.     image: string
  157.     cmd?: [...string]
  159.     port: *80 | int
  161.     env?: [...{
  163.       name:   string
  165.       value?: string
  167.       valueFrom?: {
  169.         secretKeyRef: {
  171.           name: string
  173.           key:  string
  175.         }
  177.       }
  179.     }]
  181.     cpu?: string
  183.   }
  185. }

可以看到：

  1. 最核心的工作负载，我们按需要在 output 字段里，定义了一个要交付的 Deployment 类型的 Kubernetes 资源。
  2. Service 类型的资源，则放到 outputs 里定义。以此类推，如果你要复合第三个资源，只需要继续在后面以键值对的方式添加：
  1. outputs: service: {
  3.             apiVersion: "v1"
  5.             kind:       "Service"
  7.             spec: {
  9. ...
  11. outputs: third-resource: {
  13.             apiVersion: "v1"
  15.             kind:       "Service"
  17.             spec: {   
  19. ...

在理解这些之后，将上面的组件定义对象保存到 CUE 文件中，并部署到你的 Kubernetes 集群。

  1. $ vela def apply webserver.cue
  3. ComponentDefinition webserver created in namespace vela-system.

然后，我们使用它们，来编写一个应用部署计划：

  1. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  5. metadata:
  7.   name: webserver-demo
  9.   namespace: default
  11. spec:
  13.   components:
  15.     - name: hello-world
  17.       type: webserver
  19.       properties:
  21.         image: crccheck/hello-world
  23.         port: 8000
  25.         env:
  27.         - name: "foo"
  29.           value: "bar"
  31.         cpu: "100m"

进行部署：

  1. $ vela up -f webserver.yaml

最后，它将在运行时集群生成相关 Kubernetes 资源如下：

  1. $ kubectl get deployment
  3. NAME             READY   UP-TO-DATE   AVAILABLE   AGE
  5. hello-world-v1   1/1     1            1           15s
  10. $ kubectl get svc
  12. NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
  14. hello-world-trait-7bdcff98f7   ClusterIP   <your ip>       <none>        8000/TCP   32s

使用 CUE Context

KubeVela 让你可以在运行时，通过 context 关键字来引用一些信息。

最常用的就是应用部署计划的名称 context.appName 和组件的名称 context.name。

  1. context: {
  3.   appName: string
  5.   name: string
  7. }

举例来说，假设你在实现一个组件定义，希望将容器的名称填充为组件的名称。那么这样做：

  1. parameter: {
  3.     image: string
  5. }
  7. output: {
  9.   ...
  11.     spec: {
  13.         containers: [{
  15.             name:  context.name
  17.             image: parameter.image
  19.         }]
  21.     }
  23.   ...
  25. }

注意，context 的信息会在资源部署到目标集群之前就自动注入了

CUE context 的配置项

Context 变量名说明
context.appRevision应用部署计划的版本
context.appRevisionNum应用部署计划的版本号(int 类型), 比如说如果 context.appRevision 是 app-v1 的话，context.appRevisionNum 会是 1
context.appName应用部署计划的名称
context.name组件的名称
context.namespace应用部署计划的命名空间
context.output组件中渲染的工作负载 API 资源，这通常用在运维特征里
context.outputs.<resourceName>组件中渲染的运维特征 API 资源，这通常用在运维特征里