Version: v1.8

OAM Definition Protocol

KubeVela is fully programmable via CUE, while it leverage Kubernetes as control plane and align with the API in yaml.

You can manage the definition in CUE and the vela def command will render it into Kubernetes API with the following protocol.

Essentially, a definition object in KubeVela is a programmable building block. A definition object normally includes several information to model a certain platform capability that would used in further application deployment:

  • Capability Indicator
    • ComponentDefinition uses spec.workload to indicate the workload type of this component.
    • TraitDefinition uses spec.definition to indicate the provider of this trait.
    • These indicators can be auto detected, so they’re not necessary.
  • Interoperability Fields
    • they are for the platform to ensure a trait can work with given workload type. Hence only TraitDefinition has these fields.
  • Capability Encapsulation and Abstraction defined by spec.schematic
    • this defines the templating and parametering (i.e. encapsulation) of this capability.

Hence, the basic structure of definition object is as below:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: XxxDefinition
  3. metadata:
  4.   name: <definition name>
  5.   annotations:
  6.     <map of annotations>
  7.   labels:
  8.     <map of labels>
  9. spec:
  10.   ...
  11.   schematic:
  12.     cue:
  13.       # cue template ...
  14.   # ... interoperability fields

Below is a framework of definition in CUE format:

  1. <definition name>: {
  2.     annotations: {}
  3.     labels: {}    
  4.     attributes: {}
  5.     description: ""
  6.     type: "<definition type>"
  7. }
  9. template: {
  10.     ...
  11. }
  • The "<definition name>" aligns with the .metadata.name in OAM API.
  • The .annotations aligns with the .metadata.annotations in OAM API.
  • The .labels aligns with the .metadata.labels in OAM API.
  • The .attributes. aligns with the .spec. in OAM API except the .spec.schematic field.
  • The template aligns with the .spec.schematic.cue field, only CUE schematic supported in this conversion.
  • The description aligns with the .metadata.annotations["definition.oam.dev/description"] field.

Let’s check the OAM definition API details one by one.

The design goal of ComponentDefinition is to allow platform administrators to encapsulate any type of deployable products into “components” to be delivered. Once defined, this type of component can be referenced, instantiated and delivered by users in the Application.

Common component types include Helm Chart, Kustomize directory, a set of Kubernetes YAML files, container images, cloud resource IaC files, or CUE configuration file modules, etc. The component supplier corresponds to the real-world role, which is generally a third-party software distributor (ISV), a DevOps team engineer, or a code package and image generated by the CI system you built.

ComponentDefinition can be shared and reused. For example, a Helm chart, a CUE module, or a Terraform module. Another example is, for an Alibaba Cloud RDS component type, end users can select the same Alibaba Cloud RDS component type in different applications and instantiate them into cloud database instances with different specifications and different parameter configurations.

Let’s take a look at the frame format of ComponentDefinition:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: ComponentDefinition
  3. metadata:
  4.   name: <ComponentDefinition name>
  5.   annotations:
  6.     definition.oam.dev/description: <Function description>
  7. spec:
  8.   workload: # Workload Capability Indicator
  9.     definition:
  10.       apiVersion: <Kubernetes Workload resource group>
  11.       kind: <Kubernetes Workload types>
  12.   schematic:  # Component description
  13.     cue: # Details of components defined by CUE language
  14.       template: <CUE format template>

The indicator of workload type is declared as spec.workload.

Below is a definition for Web Service in KubeVela:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: ComponentDefinition
  3. metadata:
  4.   name: webservice
  5.   namespace: default
  6.   annotations:
  7.     definition.oam.dev/description: "Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers."
  8. spec:
  9.   workload:
  10.     definition:
  11.       apiVersion: apps/v1
  12.       kind: Deployment
  13.     ...

In above example, it claims to leverage Kubernetes Deployment (apiVersion: apps/v1, kind: Deployment) as the workload type for component.

The programmable template of given capability are defined in spec.schematic field. For example, below is the full definition of Helm type in KubeVela:

Details

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: ComponentDefinition
  3. metadata:
  4.   name: helm
  5.   namespace: vela-system
  6.   annotations:
  7.     definition.oam.dev/description: "helm release is a group of K8s resources from either git repository or helm repo"
  8. spec:
  9.   workload:
  10.     type: autodetects.core.oam.dev
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         output: {
  15.           apiVersion: "source.toolkit.fluxcd.io/v1beta1"
  16.           metadata: {
  17.             name: context.name
  18.           }
  19.           if parameter.repoType == "git" {
  20.             kind: "GitRepository"
  21.             spec: {
  22.               url: parameter.repoUrl
  23.               ref:
  24.                 branch: parameter.branch
  25.               interval: parameter.pullInterval
  26.             }
  27.           }
  28.           if parameter.repoType == "helm" {
  29.             kind: "HelmRepository"
  30.             spec: {
  31.               interval: parameter.pullInterval
  32.               url:      parameter.repoUrl
  33.               if parameter.secretRef != _|_ {
  34.                 secretRef: {
  35.                   name: parameter.secretRef
  36.                 }
  37.               }
  38.             }
  39.           }
  40.         }
  42.         outputs: release: {
  43.           apiVersion: "helm.toolkit.fluxcd.io/v2beta1"
  44.           kind:       "HelmRelease"
  45.           metadata: {
  46.             name: context.name
  47.           }
  48.           spec: {
  49.             interval: parameter.pullInterval
  50.             chart: {
  51.               spec: {
  52.                 chart:   parameter.chart
  53.                 version: parameter.version
  54.                 sourceRef: {
  55.                   if parameter.repoType == "git" {
  56.                     kind: "GitRepository"
  57.                   }
  58.                   if parameter.repoType == "helm" {
  59.                     kind: "HelmRepository"
  60.                   }
  61.                   name:      context.name
  62.                   namespace: context.namespace
  63.                 }
  64.                 interval: parameter.pullInterval
  65.               }
  66.             }
  67.             if parameter.targetNamespace != _|_ {
  68.               targetNamespace: parameter.targetNamespace
  69.             }
  70.             if parameter.values != _|_ {
  71.               values: parameter.values
  72.             }
  73.           }
  74.         }
  76.         parameter: {
  77.           repoType: "git" | "helm"
  78.           // +usage=The Git or Helm repository URL, accept HTTP/S or SSH address as git url.
  79.           repoUrl: string
  80.           // +usage=The interval at which to check for repository and relese updates.
  81.           pullInterval: *"5m" | string
  82.           // +usage=1.The relative path to helm chart for git source. 2. chart name for helm resource
  83.           chart: string
  84.           // +usage=Chart version
  85.           version?: string
  86.           // +usage=The Git reference to checkout and monitor for changes, defaults to master branch.
  87.           branch: *"master" | string
  88.           // +usage=The name of the secret containing authentication credentials for the Helm repository.
  89.           secretRef?: string
  90.           // +usage=The namespace for helm chart
  91.           targetNamespace?: string
  92.           // +usage=Chart version
  93.           value?: #nestedmap
  94.         }
  96.         #nestedmap: {
  97.           ...
  98.         }

The specification of schematic is explained in the CUE with KubeVela documentations.

TraitDefinition provides a series of DevOps actions for the component that can be bound on demand. These operation and maintenance actions are usually provided by the platform administrator, such as adding a load balancing strategy, routing strategy, or performing scaler, gray release strategy, etc.

The format and field functions of the TraitDefinition are as follows:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   name: <TraitDefinition name>
  5.   annotations:
  6.     definition.oam.dev/description: <function description>
  7. spec:
  8.   definition:
  9.     apiVersion: <corresponding Kubernetes resource group>
  10.     kind: <corresponding Kubernetes resource type>
  11.   workloadRefPath: <The path to the reference field of the Workload object in the Trait>
  12.   podDisruptive: <whether the parameter update of Trait cause the underlying resource (pod) to restart>
  13.   manageWorkload: <Whether the workload is managed by this Trait>
  14.   skipRevisionAffect: <Whether this Trait is not included in the calculation of version changes>
  15.   appliesToWorkloads:
  16.   - <Workload that TraitDefinition can adapt to>
  17.   conflictsWith:
  18.   - <other Traits that conflict with this><>
  19.   revisionEnabled: <whether Trait is aware of changes in component version>
  20.   controlPlaneOnly: <Whether resources generated by trait are dispatched to the hubcluster (local)>
  21.   schematic:  # Abstract
  22.     cue: # There are many abstracts
  23.       template: <CUE format template>

The interoperability fields are trait only. Let’s explain them in detail.

This field defines the constraints that what kinds of workloads this trait is allowed to apply to.

  • It accepts an array of string as value.
  • Each item in the array refers to one or a group of workload types to which this trait is allowed to apply.

There are three approaches to denote one or a group of workload types.

  • ComponentDefinition definition reference (CRD name), e.g., deployments.apps
  • Resource group of ComponentDefinition definition reference prefixed with *., e.g., *.apps, *.oam.dev. This means the trait is allowed to apply to any workloads in this group.
  • * means this trait is allowed to apply to any workloads

If this field is omitted, it means this trait is allowed to apply to any workload types.

For now, this field is not checked when applying application. Strict checking is planed to be implemented in the KubeVela 1.6.

This field defines that constraints that what kinds of traits are conflicting with this trait, if they are applied to the same workload.

  • It accepts an array of string as value.
  • Each item in the array refers to one or a group of traits.

There are four approaches to denote one or a group of workload types.

  • TraitDefinition name, e.g., ingress
  • Resource group of TraitDefinition definition reference prefixed with *., e.g., *.networking.k8s.io. This means the trait is conflicting with any traits in this group.
  • * means this trait is conflicting with any other trait.

If this field is omitted, it means this trait is NOT conflicting with any traits.

This field defines the field path of the trait which is used to store the reference of the workload to which the trait is applied.

  • It accepts a string as value, e.g., spec.workloadRef.

If this field is set, KubeVela core will automatically fill the workload reference into target field of the trait. Then the trait controller can get the workload reference from the trait latter. So this field usually accompanies with the traits whose controllers relying on the workload reference at runtime.

For example, when this field set in the following custom trait:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   name: myscaler
  5. spec:
  6.   workloadRefPath: spec.workloadRef
  7.   schematic:
  8.     cue:
  9.       template: |
  10.         outputs: scaler: {
  11.           apiVersion: "core.oam.dev/v1alpha2"
  12.           kind:       "ManualScalerTrait"
  13.           spec: {
  14.             replicaCount: parameter.replicas
  15.           }
  16.         }
  17.         parameter: {
  18.           //+short=r
  19.           //+usage=Replicas of the workload
  20.           replicas: *1 | int
  21.         }

The controller will automatically inject the apiVersion/Kind/Name of the workload defined in the component into the field specified in workloadRefPath, the result of the trait object in the app can be something like below, assume the workload is a Kubernetes Deployment:

  1. apiVersion: "core.oam.dev/v1alpha2"
  2. kind:       "ManualScalerTrait"
  3. spec:
  4.   workloadRef:
  5.     apiVersion: apps/v1
  6.     kind: Deployment
  7.     name: mywork
  8.   replicaCount: 1

This field defines that adding/updating the trait will disruptive the pod or not. In this example, the answer is not, so the field is false, it will not affect the pod when the trait is added or updated. If the field is true, then it will cause the pod to disruptive and restart when the trait is added or updated. By default, the value is false which means this trait will not affect. Please take care of this field, it’s really important and useful for serious large scale production usage scenarios.

Let’s look at a practical example:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: TraitDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: "configure k8s Horizontal Pod Autoscaler for Component which using Deployment as worklaod"
  6.   name: hpa
  7. spec:
  8.   appliesToWorkloads:
  9.     - deployments.apps
  10.   workloadRefPath: spec.scaleTargetRef
  11.   schematic:
  12.     cue:
  13.       template: |
  14.         outputs: hpa: {
  15.           apiVersion: "autoscaling/v2beta2"
  16.           kind:       "HorizontalPodAutoscaler"
  17.           spec: {
  18.             minReplicas: parameter.min
  19.             maxReplicas: parameter.max
  20.             metrics: [{
  21.               type: "Resource"
  22.               resource: {
  23.                 name: "cpu"
  24.                 target: {
  25.                   type:               "Utilization"
  26.                   averageUtilization: parameter.cpuUtil
  27.                 }
  28.               }
  29.             }]
  30.           }
  31.         }
  32.         parameter: {
  33.           min:     *1 | int
  34.           max:     *10 | int
  35.           cpuUtil: *50 | int
  36.         }

PolicyDefinition is simimarly to TraitDefinition, the difference is that TraitDefinition acts on a single component but PolicyDefinition is to act on the entire application as a whole (multiple components).

It can provide global policy for applications, commonly including global security policies (such as RBAC permissions, auditing, and key management), application insights (such as application SLO management, etc.).

The format is as follows:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: PolicyDefinition
  3. metadata:
  4.   name: <PolicyDefinition name>
  5.   annotations:
  6.     definition.oam.dev/description: <function description>
  7. spec:
  8.   schematic:  # strategy description
  9.     cue: 
  10.       template: <CUE format template>

A specific example is shown below:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: PolicyDefinition
  3. metadata:
  4.   name: env-binding
  5.   annotations:
  6.     definition.oam.dev/description: <Provide differentiated configuration and environmental scheduling strategies for applications>
  7. spec:
  8.   schematic:
  9.     cue:
  10.       template: |
  11.         output: {
  12.           apiVersion: "core.oam.dev/v1alpha1"
  13.           kind:       "EnvBinding"
  14.           spec: {
  15.             engine: parameter.engine
  16.             appTemplate: {
  17.               apiVersion: "core.oam.dev/v1beta1"
  18.               kind:       "Application"
  19.               metadata: {
  20.                 name:      context.appName
  21.                 namespace: context.namespace
  22.               }
  23.               spec: {
  24.                 components: context.components
  25.               }
  26.             }
  27.             envs: parameter.envs
  28.           }
  29.         }
  31.         #Env: {
  32.           name: string
  33.           patch: components: [...{
  34.             name: string
  35.             type: string
  36.             properties: {...}
  37.           }]
  38.           placement: clusterSelector: {
  39.             labels?: [string]: string
  40.             name?: string
  41.           }
  42.         }
  44.         parameter: {
  45.           engine: *"ocm" | string
  46.           envs: [...#Env]
  47.         }

WorkflowStepDefinition is used to describe a series of steps that can be declared in the workflow, such as the deployment of execution resources, status check, data output, dependent input, external script call, etc.

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: WorkflowStepDefinition
  3. metadata:
  4.   name: <WorkflowStepDefinition name>
  5.   annotations:
  6.     definition.oam.dev/description: <function description>
  7. spec:
  8.   schematic:  # node description
  9.     cue: 
  10.       template: <CUE format template>

An actual WorkflowStepDefinition is as follows:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: WorkflowStepDefinition
  3. metadata:
  4.   name: apply-component
  5. spec:
  6.   schematic:
  7.     cue:
  8.       template: |
  9.         import ("vela/op")
  10.         parameter: {
  11.            component: string
  12.         }
  14.         // load component from application
  15.         component: op.#Load & {
  16.            component: parameter.component
  17.         }
  19.         // apply workload to kubernetes cluster
  20.         apply: op.#ApplyComponent & {
  21.            component: parameter.name
  22.         }
  24.         // wait until workload.status equal "Running"
  25.         wait: op.#ConditionalWait & {
  26.            continue: apply.status.phase =="Running"
  27.         }

Once the application is created, KubeVela will tag the created resources with a series of tags, which include the version, name, type, etc. of the application. Through these standard protocols, application components, traits and policies can be coordinated. The specific metadata list is as follows:

LabelDescription
workload.oam.dev/typeCorresponds to the name of ComponentDefinition
trait.oam.dev/typeCorresponds to the name of TraitDefinition
app.oam.dev/nameApplication name
app.oam.dev/componentComponent name
trait.oam.dev/resourceoutputs.\<resource type\>in Trait
app.oam.dev/appRevisionApplication Revision Name

In the Definitions, some runtime context information can be obtained through the context variable, please check out:

Please note that all the Definition concepts introduced in this section only need to be understood by the platform administrator when they want to expand the functions of KubeVela. The end users will learn the schema of above definitions with visualized forms (or the JSON schema of parameters if they prefer) and reference them in application deployment plan. Please check the Generate Forms from Definitions section about how this is achieved.

Last updated on May 6, 2023 by Tianxin Dong