Version: v1.2

CUE Advanced

This section will introduce how to use CUE to deliver KubeVela modules. You can can dynamically expand the platform as user needs change, adapt to growing number of users and scenarios, and meet the iterative demands of the company’s long-term business development.

Convert Kubernetes API Objects Into Custom Components

Let’s take the Kubernetes StatefulSet as an example to show how to use KubeVela to build custom modules and provide capabilities.

Save the YAML example of StatefulSet in the official document locally and name it as my-stateful.yaml, then execute commande as below:

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

View the generated “my-stateful.cue” file:

  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.             ... // omit non-critical info
  36.     }
  38.     outputs: web: {
  40.         apiVersion: "apps/v1"
  42.         kind:       "StatefulSet"
  44.             ... // omit non-critical info
  46.     }
  48.     parameter: {}
  50. }

Modify the generated file as follows:

  1. The example of the official StatefulSet website is a composite component composed of two objects StatefulSet and Service. According to KubeVela Rules for customize components, in composite components, core workloads such as StatefulSet need to be represented by the template.output field, and other auxiliary objects are represented by template.outputs, so we make some adjustments and all the automatically generated output and outputs are switched.
  2. Then we fill in the apiVersion and kind data of the core workload into the part marked as <change me>

After modification, you can use vela def vet to do format check and verification.

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

The file after two steps of changes is as follows:

  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. }

Install ComponentDefinition into the Kubernetes cluster:

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

You can see that a my-stateful component via vela components command:

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

When you put this customized component into Application, it looks like:

  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

Define Customized Parameters For Component

In previous section we have defined a ComponentDefinition that has no parameter. In this section we will show how to expose parameters.

In this example, we expose the following parameters to the user:

  • Image name, allowing users to customize the image
  • Instance name, allowing users to customize the instance name of the generated StatefulSet object and Service object
  • The number of replica, the number of copies of the generated object
  1.     ... # Omit other unmodified fields
  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.                             ... // Omit other unmodified fields
  35.                         }]
  37.                     }
  39.                 }
  41.                     ... // Omit other unmodified fields
  43.             }
  45.         }
  47.         outputs: web: {
  49.             apiVersion: "v1"
  51.             kind:       "Service"
  53.             metadata: {
  55.                 name: "nginx"
  57.                 labels: app: "nginx"
  59.             }
  61.             spec: {
  63.                 ... // Omit other unmodified fields 
  65.             }
  67.         }
  69.         parameter: {
  71.             image: string
  73.             name: string
  75.             replicas: int
  77.         }
  79.     }

After modification, use vela def apply to install to the cluster:

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

You can see the parameters of my-stateful ComponentDefinition as follows:

  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. +----------+-------------+--------+----------+---------+

Updating the ComponentDefinition will not affect existing Applications. It will take effect only after updating the Applications next time.

You can specify the three new parameters in the application:

  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

Save the file locally and name it app-stateful.yaml, execute vela up -f app-stateful.yaml to update the application, you can see that the name, image, and number of instances of the StatefulSet object have been updated.

Dry-run

In order to ensure that the user’s application can run correctly with the parameters, you can also use the vela dry-run command to verify the trial run of your template.

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

By viewing the output, you can compare whether the generated object is consistent with the object you actually expect. You can even execute this YAML directly into the Kubernetes cluster and use the results of the operation for verification.

  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

You can also use vela dry-run -h to view more available function parameters.

Use context to get runtime information

In our Application example above, the name field in the properties and the name field of the Component are the same. So we can use the context keyword that carries context information in the template, where context.name is the runtime component Name, thus the name parameter in parameter is no longer needed.

  1. ... # Omit other unmodified fields
  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 has built-in application required context, you can configure it according to your needs.

Add Traits On Demand

In addition to modifying ComponentDefinitions and adding parameters, you can also use the TraitDefinition to patch configurations to Components. KubeVela has built-in operations to meet the following needs: adding labels, annotations, injecting environment variables, sidecars, adding volumes, and so on. You can also customize Trait to do more flexible patching.

You can use vela traits to view, the traits marked with * are general traits, which can operate on common Kubernetes resource objects.

  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'.

Taking sidecar as an example, you can check the usage of 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. +------+-------------+--------+----------+---------+

Use the sidecar directly to inject a container, the application description is as follows:

  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

Deploy and run the application, and you can see that a fluentd sidecar has been deployed and running in the StatefulSet.

You can also use vela def to get the CUE source file of the sidecar to modify, add parameters, etc.

  1. vela def get sidecar

The customization of operation and maintenance capabilities is similar to component customization, so we won’t go into details here. You can read Customize Trait for more detailed functions.

Summarize

This section introduces how to deliver complete modular capabilities through CUE. The core is that it can dynamically increase configuration capabilities according to user needs, and gradually expose more functions and usages, so as to reduce the overall learning threshold for users and ultimately improve R&D efficient. The out-of-the-box capabilities provided by KubeVela, including components, traits, policy, and workflow, are also designed as pluggable and modifiable capabilities.

Next

Get to know about how to customize: