Version: v1.1

交付完整模块

现在你已经了解了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
  2. "my-stateful": {
  3.     annotations: {}
  4.     attributes: workload: definition: {
  5.         apiVersion: "<change me> apps/v1"
  6.         kind:       "<change me> Deployment"
  7.     }
  8.     description: "My StatefulSet component."
  9.     labels: {}
  10.     type: "component"
  11. }
  14. template: {
  15.     output: {
  16.         apiVersion: "v1"
  17.         kind:       "Service"
  18.             ... // 省略一些非重要信息
  19.     }
  20.     outputs: web: {
  21.         apiVersion: "apps/v1"
  22.         kind:       "StatefulSet"
  23.             ... // 省略一些非重要信息
  24.     }
  25.     parameter: {}
  26. }

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

  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
  2. Validation succeed.

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

  1. $ cat my-stateful.cue
  2. "my-stateful": {
  3.     annotations: {}
  4.     attributes: workload: definition: {
  5.         apiVersion: "apps/v1"
  6.         kind:       "StatefulSet"
  7.     }
  8.     description: "My StatefulSet component."
  9.     labels: {}
  10.     type: "component"
  11. }
  14. template: {
  15.     output: {
  16.         apiVersion: "apps/v1"
  17.         kind:       "StatefulSet"
  18.         metadata: name: "web"
  19.         spec: {
  20.             selector: matchLabels: app: "nginx"
  21.             replicas:    3
  22.             serviceName: "nginx"
  23.             template: {
  24.                 metadata: labels: app: "nginx"
  25.                 spec: {
  26.                     containers: [{
  27.                         name: "nginx"
  28.                         ports: [{
  29.                             name:          "web"
  30.                             containerPort: 80
  31.                         }]
  32.                         image: "k8s.gcr.io/nginx-slim:0.8"
  33.                         volumeMounts: [{
  34.                             name:      "www"
  35.                             mountPath: "/usr/share/nginx/html"
  36.                         }]
  37.                     }]
  38.                     terminationGracePeriodSeconds: 10
  39.                 }
  40.             }
  41.             volumeClaimTemplates: [{
  42.                 metadata: name: "www"
  43.                 spec: {
  44.                     accessModes: ["ReadWriteOnce"]
  45.                     resources: requests: storage: "1Gi"
  46.                     storageClassName: "my-storage-class"
  47.                 }
  48.             }]
  49.         }
  50.     }
  51.     outputs: web: {
  52.         apiVersion: "v1"
  53.         kind:       "Service"
  54.         metadata: {
  55.             name: "nginx"
  56.             labels: app: "nginx"
  57.         }
  58.         spec: {
  59.             clusterIP: "None"
  60.             ports: [{
  61.                 name: "web"
  62.                 port: 80
  63.             }]
  64.             selector: app: "nginx"
  65.         }
  66.     }
  67.     parameter: {}
  68. }

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

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

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

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

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

  1. cat <<EOF | kubectl apply -f -
  2. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  4. metadata:
  5.   name: website
  6. spec:
  7.   components:
  8.     - name: my-component
  9.       type: my-stateful
  10. EOF

为组件定义定制化参数

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

  • 镜像名称，允许用户自定义镜像
  • 实例名，允许用户自定义生成的 StatefulSet 对象和 Service 对象的实例名称
  • 副本数，生成对象的副本数
  1.     ... # 省略其他没有修改的字段 
  2.     template: {
  3.         output: {
  4.             apiVersion: "apps/v1"
  5.             kind:       "StatefulSet"
  6.             metadata: name: parameter.name
  7.             spec: {
  8.                 selector: matchLabels: app: "nginx"
  9.                 replicas:    parameter.replicas
  10.                 serviceName: "nginx"
  11.                 template: {
  12.                     metadata: labels: app: "nginx"
  13.                     spec: {
  14.                         containers: [{
  15.                             image: parameter.image
  17.                             ... // 省略其他没有修改的字段  
  18.                         }]
  19.                     }
  20.                 }
  21.                     ... // 省略其他没有修改的字段
  22.             }
  23.         }
  24.         outputs: web: {
  25.             apiVersion: "v1"
  26.             kind:       "Service"
  27.             metadata: {
  28.                 name: "nginx"
  29.                 labels: app: "nginx"
  30.             }
  31.             spec: {
  32.                 ... // 省略其他没有修改的字段      
  33.             }
  34.         }
  35.         parameter: {
  36.             image: string
  37.             name: string
  38.             replicas: int
  39.         }
  40.     }

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

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

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

  1. $ vela show my-stateful
  2. # Properties
  3. +----------+-------------+--------+----------+---------+
  4. |   NAME   | DESCRIPTION |  TYPE  | REQUIRED | DEFAULT |
  5. +----------+-------------+--------+----------+---------+
  6. | name     |             | string | true     |         |
  7. | replicas |             | int    | true     |         |
  8. | image    |             | string | true     |         |
  9. +----------+-------------+--------+----------+---------+

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

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

  1.     apiVersion: core.oam.dev/v1beta1
  2.     kind: Application
  3.     metadata:
  4.       name: website
  5.     spec:
  6.       components:
  7.         - name: my-component
  8.           type: my-stateful
  9.           properties:
  10.             image: nginx:latest
  11.             replicas: 1
  12.             name: my-component

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

调试模块化功能的正确性

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

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

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

  1. # Application(website) -- Component(my-component)
  2. ---
  5. apiVersion: v1
  6. kind: Service
  7. metadata:
  8.   labels:
  9.     app: nginx
  10.     app.oam.dev/appRevision: ""
  11.     app.oam.dev/component: my-component
  12.     app.oam.dev/name: website
  13.     workload.oam.dev/type: my-stateful
  14.   name: nginx
  15.   namespace: default
  16. spec:
  17.   clusterIP: None
  18.   ports:
  19.   - name: web
  20.     port: 80
  21.   selector:
  22.     app: nginx
  23.   template:
  24.     spec:
  25.       containers:
  26.       - image: saravak/fluentd:elastic
  27.         name: my-sidecar
  30. ---
  31. apiVersion: apps/v1
  32. kind: StatefulSet
  33. metadata:
  34.   labels:
  35.     app.oam.dev/appRevision: ""
  36.     app.oam.dev/component: my-component
  37.     app.oam.dev/name: website
  38.     trait.oam.dev/resource: web
  39.     trait.oam.dev/type: AuxiliaryWorkload
  40.   name: web
  41.   namespace: default
  42. spec:
  43.   replicas: 3
  44.   selector:
  45.     matchLabels:
  46.       app: nginx
  47.   serviceName: nginx
  48.   template:
  49.     metadata:
  50.       labels:
  51.         app: nginx
  52.     spec:
  53.       containers:
  54.       - image: k8s.gcr.io/nginx-slim:0.8
  55.         name: nginx
  56.         ports:
  57.         - containerPort: 80
  58.           name: web
  59.         volumeMounts:
  60.         - mountPath: /usr/share/nginx/html
  61.           name: www
  62.       terminationGracePeriodSeconds: 10
  63.   volumeClaimTemplates:
  64.   - metadata:
  65.       name: www
  66.     spec:
  67.       accessModes:
  68.       - ReadWriteOnce
  69.       resources:
  70.         requests:
  71.           storage: 1Gi
  72.       storageClassName: my-storage-class

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

使用上下文信息减少参数

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

  1. ... # 省略其他没有修改的字段 
  2. template: {
  3.     output: {
  4.         apiVersion: "apps/v1"
  5.         kind:       "StatefulSet"
  6.         metadata: name: context.name
  7.             ... // 省略其他没有修改的字段
  8.     }
  9.     parameter: {
  10.         image: string
  11.         replicas: int
  12.     }
  13. }

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

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

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

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

  1. $ vela traits
  2. NAME                        NAMESPACE   APPLIES-TO          CONFLICTS-WITH  POD-DISRUPTIVE  DESCRIPTION
  3. annotations                 vela-system *                                   true            Add annotations on K8s pod for your workload which follows
  4.                                                                                             the pod spec in path 'spec.template'.
  5. configmap                   vela-system *                                   true            Create/Attach configmaps on K8s pod for your workload which
  6.                                                                                             follows the pod spec in path 'spec.template'.
  7. env                         vela-system *                                   false           add env on K8s pod for your workload which follows the pod
  8.                                                                                             spec in path 'spec.template.'
  9. hostalias                   vela-system *                                   false           Add host aliases on K8s pod for your workload which follows
  10.                                                                                             the pod spec in path 'spec.template'.
  11. labels                      vela-system *                                   true            Add labels on K8s pod for your workload which follows the
  12.                                                                                             pod spec in path 'spec.template'.
  13. lifecycle                   vela-system *                                   true            Add lifecycle hooks for the first container of K8s pod for
  14.                                                                                             your workload which follows the pod spec in path
  15.                                                                                             'spec.template'.
  16. node-affinity               vela-system *                                   true            affinity specify node affinity and toleration on K8s pod for
  17.                                                                                             your workload which follows the pod spec in path
  18.                                                                                             'spec.template'.
  19. scaler                      vela-system *                                   false           Manually scale K8s pod for your workload which follows the
  20.                                                                                             pod spec in path 'spec.template'.
  21. sidecar                     vela-system *                                   true            Inject a sidecar container to K8s pod for your workload
  22.                                                                                             which follows the pod spec in path 'spec.template'.

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

  1. $ vela show sidecar
  2. # Properties
  3. +---------+-----------------------------------------+-----------------------+----------+---------+
  4. |  NAME   |               DESCRIPTION               |         TYPE          | REQUIRED | DEFAULT |
  5. +---------+-----------------------------------------+-----------------------+----------+---------+
  6. | name    | Specify the name of sidecar container   | string                | true     |         |
  7. | cmd     | Specify the commands run in the sidecar | []string              | false    |         |
  8. | image   | Specify the image of sidecar container  | string                | true     |         |
  9. | volumes | Specify the shared volume path          | [[]volumes](#volumes) | false    |         |
  10. +---------+-----------------------------------------+-----------------------+----------+---------+
  15. ## volumes
  16. +------+-------------+--------+----------+---------+
  17. | NAME | DESCRIPTION |  TYPE  | REQUIRED | DEFAULT |
  18. +------+-------------+--------+----------+---------+
  19. | path |             | string | true     |         |
  20. | name |             | string | true     |         |
  21. +------+-------------+--------+----------+---------+

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

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: website
  5. spec:
  6.   components:
  7.     - name: my-component
  8.       type: my-stateful
  9.       properties:
  10.         image: nginx:latest
  11.         replicas: 1
  12.         name: my-component
  13.       traits:
  14.       - type: sidecar
  15.         properties:
  16.           name: my-sidecar
  17.           image: saravak/fluentd:elastic

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

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

  1. vela def get sidecar

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

总结

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

下一步