Version: v1.2

交付完整模块

现在你已经了解了OAM 模型和模块定义（X-Definition ）的概念，本节将介绍如何使用 CUE 交付完整的模块化功能，使得你的平台可以随着用户需求变化动态扩展功能，适应各类用户和场景，满足公司业务长期发展的迭代诉求。

将 Kubernetes API 对象转化为自定义组件

KubeVela 使用 CUE 配置语言作为管理用户模块化交付的核心，同时也围绕 CUE 提供了管理工具来编辑和生成 KubeVela 的模块定义对象。

下面我们以 Kubernetes 官方的 StatefulSet 对象为例，来具体看如何使用 KubeVela 构建自定义的模块化功能并提供能力。 我们将官方文档中 StatefulSet 的 YAML 例子保存在本地，并命名为 my-stateful.yaml， 然后执行如下命令，生成一个名为 “my-stateful” 的 Component 模块定义，并输出到 “my-stateful.cue” 文件中：

  1.  vela def init my-stateful -t component --desc "My StatefulSet component." --template-yaml ./my-stateful.yaml -o my-stateful.cue

查看生成的 “my-stateful.cue” 文件：

  1. $ cat my-stateful.cue
  3. "my-stateful": {
  5.     annotations: {}
  7.     attributes: workload: definition: {
  9.         apiVersion: "<change me> apps/v1"
  11.         kind:       "<change me> Deployment"
  13.     }
  15.     description: "My StatefulSet component."
  17.     labels: {}
  19.     type: "component"
  21. }
  26. template: {
  28.     output: {
  30.         apiVersion: "v1"
  32.         kind:       "Service"
  34.             ... // 省略一些非重要信息
  36.     }
  38.     outputs: web: {
  40.         apiVersion: "apps/v1"
  42.         kind:       "StatefulSet"
  44.             ... // 省略一些非重要信息
  46.     }
  48.     parameter: {}
  50. }

下面我们来对这个自动生成的自定义组件做一些微调：

  1. StatefulSet 官网的例子是由 StatefulSet和 Service 两个对象构成的一个复合组件。而根据 KubeVela 自定义组件的规则，在复合组件中，比如 StatefulSet 这样的核心工作负载需要由 template.output字段表示，其他辅助对象用 template.outputs表示，所以我们将内容做一些调整，将自动生成的 output 和 outputs 中的全部调换。
  2. 然后我们将核心工作负载的 apiVersion 和 kind 数据填写到标注为 <change me>的部分

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

  1. $ vela def vet my-stateful.cue
  3. Validation succeed.

经过两步改动后的文件如下：

  1. $ cat my-stateful.cue
  3. "my-stateful": {
  5.     annotations: {}
  7.     attributes: workload: definition: {
  9.         apiVersion: "apps/v1"
  11.         kind:       "StatefulSet"
  13.     }
  15.     description: "My StatefulSet component."
  17.     labels: {}
  19.     type: "component"
  21. }
  26. template: {
  28.     output: {
  30.         apiVersion: "apps/v1"
  32.         kind:       "StatefulSet"
  34.         metadata: name: "web"
  36.         spec: {
  38.             selector: matchLabels: app: "nginx"
  40.             replicas:    3
  42.             serviceName: "nginx"
  44.             template: {
  46.                 metadata: labels: app: "nginx"
  48.                 spec: {
  50.                     containers: [{
  52.                         name: "nginx"
  54.                         ports: [{
  56.                             name:          "web"
  58.                             containerPort: 80
  60.                         }]
  62.                         image: "k8s.gcr.io/nginx-slim:0.8"
  64.                         volumeMounts: [{
  66.                             name:      "www"
  68.                             mountPath: "/usr/share/nginx/html"
  70.                         }]
  72.                     }]
  74.                     terminationGracePeriodSeconds: 10
  76.                 }
  78.             }
  80.             volumeClaimTemplates: [{
  82.                 metadata: name: "www"
  84.                 spec: {
  86.                     accessModes: ["ReadWriteOnce"]
  88.                     resources: requests: storage: "1Gi"
  90.                     storageClassName: "my-storage-class"
  92.                 }
  94.             }]
  96.         }
  98.     }
  100.     outputs: web: {
  102.         apiVersion: "v1"
  104.         kind:       "Service"
  106.         metadata: {
  108.             name: "nginx"
  110.             labels: app: "nginx"
  112.         }
  114.         spec: {
  116.             clusterIP: "None"
  118.             ports: [{
  120.                 name: "web"
  122.                 port: 80
  124.             }]
  126.             selector: app: "nginx"
  128.         }
  130.     }
  132.     parameter: {}
  134. }

将该组件定义安装到 Kubernetes 集群中：

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

此时平台的最终用户已经可以通过 vela components命令看到有一个 my-stateful组件可以使用了。

  1. $ vela components
  3. NAME        NAMESPACE   WORKLOAD                                DESCRIPTION
  5. ...
  7. my-stateful vela-system statefulsets.apps                       My StatefulSet component.
  9. ...

通过 KubeVela 的应用部署计划发布到集群中，就可以拉起我们刚刚定义的 StatefulSet 和 Service 对象。

  1. cat <<EOF | vela up -f -
  3. apiVersion: core.oam.dev/v1beta1
  5. kind: Application
  7. metadata:
  9.   name: website
  11. spec:
  13.   components:
  15.     - name: my-component
  17.       type: my-stateful
  19. EOF

为组件定义定制化参数

为了满足用户变化的需求，我们需要在最后的 parameter 里暴露一些参数，在 CUE 基础入门文档中你可以了解到参数相关的语法。在本例中，我们为用户暴露一下参数：

  • 镜像名称，允许用户自定义镜像
  • 实例名，允许用户自定义生成的 StatefulSet 对象和 Service 对象的实例名称
  • 副本数，生成对象的副本数
  1.     ... # 省略其他没有修改的字段 
  3.     template: {
  5.         output: {
  7.             apiVersion: "apps/v1"
  9.             kind:       "StatefulSet"
  11.             metadata: name: parameter.name
  13.             spec: {
  15.                 selector: matchLabels: app: "nginx"
  17.                 replicas:    parameter.replicas
  19.                 serviceName: "nginx"
  21.                 template: {
  23.                     metadata: labels: app: "nginx"
  25.                     spec: {
  27.                         containers: [{
  29.                             image: parameter.image
  33.                             ... // 省略其他没有修改的字段  
  35.                         }]
  37.                     }
  39.                 }
  41.                     ... // 省略其他没有修改的字段
  43.             }
  45.         }
  47.         outputs: web: {
  49.             apiVersion: "v1"
  51.             kind:       "Service"
  53.             metadata: {
  55.                 name: "nginx"
  57.                 labels: app: "nginx"
  59.             }
  61.             spec: {
  63.                 ... // 省略其他没有修改的字段      
  65.             }
  67.         }
  69.         parameter: {
  71.             image: string
  73.             name: string
  75.             replicas: int
  77.         }
  79.     }

修改后同样使用 vela def apply安装到集群中：

  1. $ vela def apply my-stateful.cue
  3. ComponentDefinition my-stateful in namespace vela-system updated.

这个修改过程是实时生效的，用户立即可以看到系统中的 my-stateful 组件增加了新的参数。

  1. $ vela show my-stateful
  3. # Properties
  5. +----------+-------------+--------+----------+---------+
  7. |   NAME   | DESCRIPTION |  TYPE  | REQUIRED | DEFAULT |
  9. +----------+-------------+--------+----------+---------+
  11. | name     |             | string | true     |         |
  13. | replicas |             | int    | true     |         |
  15. | image    |             | string | true     |         |
  17. +----------+-------------+--------+----------+---------+

组件定义的修改并不会影响已经在运行的应用，当下次应用修改并重新部署时，新的组件定义就会生效。

最终用户就可以在应用中指定新增的这三个参数：

  1.     apiVersion: core.oam.dev/v1beta1
  3.     kind: Application
  5.     metadata:
  7.       name: website
  9.     spec:
  11.       components:
  13.         - name: my-component
  15.           type: my-stateful
  17.           properties:
  19.             image: nginx:latest
  21.             replicas: 1
  23.             name: my-component

将文件保存在本地并命名为 app-stateful.yaml，执行 vela up -f app-stateful.yaml更新应用，你可以看到 StatefulSet 对象的名称、镜像和实例数均已更新。

调试模块化功能的正确性

为了保证用户的应用使用参数能够正确运行，你也可以用 vela dry-run 命令对你的模板进行试运行验证。

  1. vela dry-run -f app-stateful.yaml

查看输出，你就可以对比生成的对象和你实际期望的对象是否一致。甚至可以直接把这个 YAML 执行到 Kubernetes 集群中使用看运行的结果做验证。

  1. # Application(website) -- Component(my-component)
  3. ---
  8. apiVersion: v1
  10. kind: Service
  12. metadata:
  14.   labels:
  16.     app: nginx
  18.     app.oam.dev/appRevision: ""
  20.     app.oam.dev/component: my-component
  22.     app.oam.dev/name: website
  24.     workload.oam.dev/type: my-stateful
  26.   name: nginx
  28.   namespace: default
  30. spec:
  32.   clusterIP: None
  34.   ports:
  36.   - name: web
  38.     port: 80
  40.   selector:
  42.     app: nginx
  44.   template:
  46.     spec:
  48.       containers:
  50.       - image: saravak/fluentd:elastic
  52.         name: my-sidecar
  57. ---
  59. apiVersion: apps/v1
  61. kind: StatefulSet
  63. metadata:
  65.   labels:
  67.     app.oam.dev/appRevision: ""
  69.     app.oam.dev/component: my-component
  71.     app.oam.dev/name: website
  73.     trait.oam.dev/resource: web
  75.     trait.oam.dev/type: AuxiliaryWorkload
  77.   name: web
  79.   namespace: default
  81. spec:
  83.   replicas: 3
  85.   selector:
  87.     matchLabels:
  89.       app: nginx
  91.   serviceName: nginx
  93.   template:
  95.     metadata:
  97.       labels:
  99.         app: nginx
  101.     spec:
  103.       containers:
  105.       - image: k8s.gcr.io/nginx-slim:0.8
  107.         name: nginx
  109.         ports:
  111.         - containerPort: 80
  113.           name: web
  115.         volumeMounts:
  117.         - mountPath: /usr/share/nginx/html
  119.           name: www
  121.       terminationGracePeriodSeconds: 10
  123.   volumeClaimTemplates:
  125.   - metadata:
  127.       name: www
  129.     spec:
  131.       accessModes:
  133.       - ReadWriteOnce
  135.       resources:
  137.         requests:
  139.           storage: 1Gi
  141.       storageClassName: my-storage-class

你还可以通过 vela dry-run -h 来查看更多可用的功能参数。

使用上下文信息减少参数

在我们上面的 Application 例子中，properties 中的 name 和 Component 的 name 字段是相同的，此时我们可以在模板中使用携带了上下文信息的 context关键字，其中 context.name 就是运行时组件名称，此时 parameter 中的 name 参数就不再需要的。

  1. ... # 省略其他没有修改的字段 
  3. template: {
  5.     output: {
  7.         apiVersion: "apps/v1"
  9.         kind:       "StatefulSet"
  11.         metadata: name: context.name
  13.             ... // 省略其他没有修改的字段
  15.     }
  17.     parameter: {
  19.         image: string
  21.         replicas: int
  23.     }
  25. }

KubeVela 内置了应用所需的上下文信息，你可以根据需要配置.

使用运维能力按需添加配置

对于用户的新需求，除了修改组件定义增加参数以外，你还可以使用运维能力，按需添加配置。一方面，KubeVela 已经内置了大量的通用运维能力，可以满足诸如：添加 label、annotation，注入环境变量、sidecar，添加 volume 等等的需求。另一方面，你可以像自定义组件一样，自定义补丁型运维特征，来满足更多的配置灵活组装的需求。

你可以使用 vela traits 查看，带 * 标记的 trait 均为通用 trait，能够对常见的 Kubernetes 资源对象做操作。

  1. $ vela traits
  3. NAME                        NAMESPACE   APPLIES-TO          CONFLICTS-WITH  POD-DISRUPTIVE  DESCRIPTION
  5. annotations                 vela-system *                                   true            Add annotations on K8s pod for your workload which follows
  7.                                                                                             the pod spec in path 'spec.template'.
  9. configmap                   vela-system *                                   true            Create/Attach configmaps on K8s pod for your workload which
  11.                                                                                             follows the pod spec in path 'spec.template'.
  13. env                         vela-system *                                   false           add env on K8s pod for your workload which follows the pod
  15.                                                                                             spec in path 'spec.template.'
  17. hostalias                   vela-system *                                   false           Add host aliases on K8s pod for your workload which follows
  19.                                                                                             the pod spec in path 'spec.template'.
  21. labels                      vela-system *                                   true            Add labels on K8s pod for your workload which follows the
  23.                                                                                             pod spec in path 'spec.template'.
  25. lifecycle                   vela-system *                                   true            Add lifecycle hooks for the first container of K8s pod for
  27.                                                                                             your workload which follows the pod spec in path
  29.                                                                                             'spec.template'.
  31. node-affinity               vela-system *                                   true            affinity specify node affinity and toleration on K8s pod for
  33.                                                                                             your workload which follows the pod spec in path
  35.                                                                                             'spec.template'.
  37. scaler                      vela-system *                                   false           Manually scale K8s pod for your workload which follows the
  39.                                                                                             pod spec in path 'spec.template'.
  41. sidecar                     vela-system *                                   true            Inject a sidecar container to K8s pod for your workload
  43.                                                                                             which follows the pod spec in path 'spec.template'.

以 sidecar 为例，你可以查看 sidecar 的用法：

  1. $ vela show sidecar
  3. # Properties
  5. +---------+-----------------------------------------+-----------------------+----------+---------+
  7. |  NAME   |               DESCRIPTION               |         TYPE          | REQUIRED | DEFAULT |
  9. +---------+-----------------------------------------+-----------------------+----------+---------+
  11. | name    | Specify the name of sidecar container   | string                | true     |         |
  13. | cmd     | Specify the commands run in the sidecar | []string              | false    |         |
  15. | image   | Specify the image of sidecar container  | string                | true     |         |
  17. | volumes | Specify the shared volume path          | [[]volumes](#volumes) | false    |         |
  19. +---------+-----------------------------------------+-----------------------+----------+---------+
  27. ## volumes
  29. +------+-------------+--------+----------+---------+
  31. | NAME | DESCRIPTION |  TYPE  | REQUIRED | DEFAULT |
  33. +------+-------------+--------+----------+---------+
  35. | path |             | string | true     |         |
  37. | name |             | string | true     |         |
  39. +------+-------------+--------+----------+---------+

直接使用 sidecar 注入一个容器，应用的描述如下：

  1. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  5. metadata:
  7.   name: website
  9. spec:
  11.   components:
  13.     - name: my-component
  15.       type: my-stateful
  17.       properties:
  19.         image: nginx:latest
  21.         replicas: 1
  23.         name: my-component
  25.       traits:
  27.       - type: sidecar
  29.         properties:
  31.           name: my-sidecar
  33.           image: saravak/fluentd:elastic

部署运行该应用，就可以看到 StatefulSet 中已经部署运行了一个 fluentd 的 sidecar。

你也可以使用 vela def 获取 sidecar 的 CUE 源文件进行修改，增加参数等。

  1. vela def get sidecar

运维能力的自定义与组件自定义类似，不再赘述，你可以阅读运维能力自定义文档了解更详细的功能。

总结

本节介绍了如何通过 CUE 交付完整的模块化能力，其核心是可以随着用户的需求，不断动态增加配置能力，逐步暴露更多的功能和用法，以便降低用户整体的学习门槛，最终提升研发效率。 KubeVela 背后提供的开箱即用的能力，包括组件、运维功能、策略以及工作流，均是通过同样的方式提供了可插拔、可修改的能力。

下一步