Manage Definition

Before reading this part, please make sure you’ve learned the Definition Concept of KubeVela.

In KubeVela CLI, vela def command group provides a series of convenient definition writing tools. With these commands, users only need to write CUE files to generate and edit definitions, instead of composing Kubernetes YAML object with mixed CUE string.

init

vela def init is a command that helps users bootstrap new definitions. To create an empty trait definition, run vela def init my-trait -t trait --desc "My trait description."

  1. "my-trait": {
  2.         annotations: {}
  3.         attributes: {
  4.                 appliesToWorkloads: []
  5.                 conflictsWith: []
  6.                 definitionRef:   ""
  7.                 podDisruptive:   false
  8.                 workloadRefPath: ""
  9.         }
  10.         description: "My trait description."
  11.         labels: {}
  12.         type: "trait"
  13. }
  14. template: patch: {}

Or you can use vela def init my-comp --interactive to initiate definitions interactively.

  1. $ vela def init my-comp --interactive
  2. Please choose one definition type from the following values: component, trait, policy, workload, scope, workflow-step
  3. > Definition type: component
  4. > Definition description: My component definition.
  5. Please enter the location the template YAML file to build definition. Leave it empty to generate default template.
  6. > Definition template filename: 
  7. Please enter the output location of the generated definition. Leave it empty to print definition to stdout.
  8. > Definition output filename: my-component.cue
  9. Definition written to my-component.cue

In addition, users can create definitions from existing YAML files. For example, if a user want to create a ComponentDefinition which is designed to generate a deployment, and this deployment has already been created elsewhere, he/she can use the --template-yaml flag to complete the transformation. The YAML file is as below

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: hello-world
  5. spec:
  6.   replicas: 1
  7.   selector:
  8.     matchLabels:
  9.       app.kubernetes.io/name: hello-world
  10.   template:
  11.     metadata:
  12.       labels:
  13.         app.kubernetes.io/name: hello-world
  14.     spec:
  15.       containers:
  16.       - name: hello-world
  17.         image: somefive/hello-world
  18.         ports: 
  19.         - name: http
  20.           containerPort: 80
  21.           protocol: TCP
  22. ---
  23. apiVersion: v1
  24. kind: Service
  25. metadata:
  26.   name: hello-world-service
  27. spec:
  28.   selector:
  29.     app: hello-world
  30.   ports:
  31.   - name: http
  32.     protocol: TCP
  33.     port: 80
  34.     targetPort: 8080
  35.   type: LoadBalancer

Running vela def init my-comp -t component --desc "My component." --template-yaml ./my-deployment.yaml to get the CUE-format ComponentDefinition

  1. "my-comp": {
  2.         annotations: {}
  3.         attributes: workload: definition: {
  4.                 apiVersion: "<change me> apps/v1"
  5.                 kind:       "<change me> Deployment"
  6.         }
  7.         description: "My component."
  8.         labels: {}
  9.         type: "component"
  10. }
  11. template: {
  12.         output: {
  13.                 metadata: name: "hello-world"
  14.                 spec: {
  15.                         replicas: 1
  16.                         selector: matchLabels: "app.kubernetes.io/name": "hello-world"
  17.                         template: {
  18.                                 metadata: labels: "app.kubernetes.io/name": "hello-world"
  19.                                 spec: containers: [{
  20.                                         name:  "hello-world"
  21.                                         image: "somefive/hello-world"
  22.                                         ports: [{
  23.                                                 name:          "http"
  24.                                                 containerPort: 80
  25.                                                 protocol:      "TCP"
  26.                                         }]
  27.                                 }]
  28.                         }
  29.                 }
  30.                 apiVersion: "apps/v1"
  31.                 kind:       "Deployment"
  32.         }
  33.         outputs: "hello-world-service": {
  34.                 metadata: name: "hello-world-service"
  35.                 spec: {
  36.                         ports: [{
  37.                                 name:       "http"
  38.                                 protocol:   "TCP"
  39.                                 port:       80
  40.                                 targetPort: 8080
  41.                         }]
  42.                         selector: app: "hello-world"
  43.                         type: "LoadBalancer"
  44.                 }
  45.                 apiVersion: "v1"
  46.                 kind:       "Service"
  47.         }
  48.         parameter: {}
  50. }

Then the user can make further modifications based on the definition file above, like removing \<change me> in workload.definition。

vet

After initializing definition files, run vela def vet my-comp.cue to validate if there are any syntax error in the definition file. It can be used to detect some simple errors such as missing brackets.

  1. $ vela def vet my-comp.cue
  2. Validation succeed.

render / apply

After confirming the definition file has correct syntax. users can run vela def apply my-comp.cue --namespace my-namespace to apply this definition in the my-namespace namespace。If you want to check the transformed Kubernetes YAML file, vela def apply my-comp.cue --dry-run or vela def render my-comp.cue -o my-comp.yaml can achieve that.

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: ComponentDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: My component.
  6.   labels: {}
  7.   name: my-comp
  8.   namespace: vela-system
  9. spec:
  10.   schematic:
  11.     cue:
  12.       template: |
  13.         output: {
  14.                 metadata: name: "hello-world"
  15.                 spec: {
  16.                         replicas: 1
  17.                         selector: matchLabels: "app.kubernetes.io/name": "hello-world"
  18.                         template: {
  19.                                 metadata: labels: "app.kubernetes.io/name": "hello-world"
  20.                                 spec: containers: [{
  21.                                         name:  "hello-world"
  22.                                         image: "somefive/hello-world"
  23.                                         ports: [{
  24.                                                 name:          "http"
  25.                                                 containerPort: 80
  26.                                                 protocol:      "TCP"
  27.                                         }]
  28.                                 }]
  29.                         }
  30.                 }
  31.                 apiVersion: "apps/v11"
  32.                 kind:       "Deployment"
  33.         }
  34.         outputs: "hello-world-service": {
  35.                 metadata: name: "hello-world-service"
  36.                 spec: {
  37.                         ports: [{
  38.                                 name:       "http"
  39.                                 protocol:   "TCP"
  40.                                 port:       80
  41.                                 targetPort: 8080
  42.                         }]
  43.                         selector: app: "hello-world"
  44.                         type: "LoadBalancer"
  45.                 }
  46.                 apiVersion: "v1"
  47.                 kind:       "Service"
  48.         }
  49.         parameter: {}
  50.   workload:
  51.     definition:
  52.       apiVersion: apps/v1
  53.       kind: Deployment
  1. $ vela def apply my-comp.cue -n my-namespace
  2. ComponentDefinition my-comp created in namespace my-namespace.

get / list / edit / del

While you can use native kubectl tools to confirm the results of the apply command, as mentioned above, the YAML object mixed with raw CUE template string is complex. Using vela def get will automatically convert the YAML object into the CUE-format definition.

  1. $ vela def get my-comp -t component

Or you can list all definitions installed through vela def list

  1. $ vela def list -n my-namespace -t component
  2. NAME                    TYPE                    NAMESPACE       DESCRIPTION  
  3. my-comp                 ComponentDefinition     my-namespace    My component.

Similarly, using vela def edit to edit definitions in pure CUE-format. The transformation between CUE-format definition and YAML object is done by the command. Besides, you can specify the EDITOR environment variable to use your favourate editor.

  1. $ EDITOR=vim vela def edit my-comp

Finally, vela def del can be utilized to delete existing definitions.

  1. $ vela def del my-comp -n my-namespace  
  2. Are you sure to delete the following definition in namespace my-namespace?
  3. ComponentDefinition my-comp: My component.
  4. [yes|no] > yes
  5. ComponentDefinition my-comp in namespace my-namespace deleted.

A brief quick view for these commands are shown below.

def-demo

Next Step