Version: v1.2

How-to

In this section we will introduce how to define a trait.

Simple Trait

A trait in KubeVela can be defined by simply reference a existing Kubernetes API resource.

  1. apiVersion: core.oam.dev/v1beta1
  3. kind: TraitDefinition
  5. metadata:
  7.   name: ingress
  9. spec:
  11.   definitionRef:
  13.     name: ingresses.networking.k8s.io

Let’s attach this trait to a component instance in Application:

  1. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  5. metadata:
  7.   name: testapp
  9. spec:
  11.   components:
  13.     - name: express-server
  15.       type: webservice
  17.       properties:
  19.         cmd:
  21.           - node
  23.           - server.js
  25.         image: oamdev/testapp:v1
  27.         port: 8080
  29.       traits:
  31.         - type: ingress
  33.           properties:
  35.             rules:
  37.             - http:
  39.                 paths:
  41.                 - path: /testpath
  43.                   pathType: Prefix
  45.                   backend:
  47.                     service:
  49.                       name: test
  51.                       port:
  53.                         number: 80

Note that in this case, all fields in the referenced resource’s spec will be exposed to end user and no metadata (e.g. annotations etc) are allowed to be set trait properties. Hence this approach is normally used when you want to bring your own CRD and controller as a trait, and it dose not rely on annotations etc as tuning knobs.

Using CUE as Trait Schematic

The recommended approach is defining a CUE based schematic for trait as well. In this case, it comes with abstraction and you have full flexibility to templating any resources and fields as you want. Note that KubeVela requires all traits MUST be defined in outputs section (not output) in CUE template with format as below:

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

Below is an example for ingress trait.

  1. apiVersion: core.oam.dev/v1beta1
  3. kind: TraitDefinition
  5. metadata:
  7.   name: ingress
  9. spec:
  11.   podDisruptive: false
  13.   schematic:
  15.     cue:
  17.       template: |
  19.         parameter: {
  21.             domain: string
  23.             http: [string]: int
  25.         }
  30.         // trait template can have multiple outputs in one trait
  32.         outputs: service: {
  34.             apiVersion: "v1"
  36.             kind:       "Service"
  38.             spec: {
  40.                 selector:
  42.                     app: context.name
  44.                 ports: [
  46.                     for k, v in parameter.http {
  48.                         port:       v
  50.                         targetPort: v
  52.                     },
  54.                 ]
  56.             }
  58.         }
  63.         outputs: ingress: {
  65.             apiVersion: "networking.k8s.io/v1beta1"
  67.             kind:       "Ingress"
  69.             metadata:
  71.                 name: context.name
  73.             spec: {
  75.                 rules: [{
  77.                     host: parameter.domain
  79.                     http: {
  81.                         paths: [
  83.                             for k, v in parameter.http {
  85.                                 path: k
  87.                                 backend: {
  89.                                     serviceName: context.name
  91.                                     servicePort: v
  93.                                 }
  95.                             },
  97.                         ]
  99.                     }
  101.                 }]
  103.             }
  105.         }

Let’s attach this trait to a component instance in Application:

  1. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  5. metadata:
  7.   name: testapp
  9. spec:
  11.   components:
  13.     - name: express-server
  15.       type: webservice
  17.       properties:
  19.         cmd:
  21.           - node
  23.           - server.js
  25.         image: oamdev/testapp:v1
  27.         port: 8080
  29.       traits:
  31.         - type: ingress
  33.           properties:
  35.             domain: test.my.domain
  37.             http:
  39.               "/api": 8080

CUE based trait definitions can also enable many other advanced scenarios such as patching and data passing. They will be explained in detail in the following documentations.