Manage Definition

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

    In KubeVela CLI, 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.

    vela def init is a command that helps users bootstrap new definitions. To create an empty trait definition, run:

    It will generate the following scaffold:

    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: {}

    You can also initiate definitions interactively like below:

    1. vela def init my-comp --interactive

    expected output

    1. Please choose one definition type from the following values: component, trait, policy, workload, scope, workflow-step
    2. > Definition type: component
    3. > Definition description: My component definition.
    4. Please enter the location the template YAML file to build definition. Leave it empty to generate default template.
    5. > Definition template filename: 
    6. Please enter the output location of the generated definition. Leave it empty to print definition to stdout.
    7. > Definition output filename: my-component.cue
    8. 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. # my-deployment.yaml
    2. apiVersion: apps/v1
    3. kind: Deployment
    4. metadata:
    5.   name: hello-world
    6. spec:
    7.   replicas: 1
    8.   selector:
    9.     matchLabels:
    10.       app.kubernetes.io/name: hello-world
    11.   template:
    12.     metadata:
    13.       labels:
    14.         app.kubernetes.io/name: hello-world
    15.     spec:
    16.       containers:
    17.       - name: hello-world
    18.         image: somefive/hello-world
    19.         ports: 
    20.         - name: http
    21.           containerPort: 80
    22.           protocol: TCP
    23. ---
    24. apiVersion: v1
    25. kind: Service
    26. metadata:
    27.   name: hello-world-service
    28. spec:
    29.   selector:
    30.     app: hello-world
    31.   ports:
    32.   - name: http
    33.     protocol: TCP
    34.     port: 80
    35.     targetPort: 8080
    36.   type: LoadBalancer

    Running the following command to get the CUE-format ComponentDefinition:

    1. vela def init my-comp -t component --desc "My component." --template-yaml ./my-deployment.yaml

    The expect output will be:

    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.                                         }]
    26.                                 }]
    27.                         }
    28.                 }
    29.                 apiVersion: "apps/v1"
    30.                 kind:       "Deployment"
    31.         }
    32.         outputs: "hello-world-service": {
    33.                 metadata: name: "hello-world-service"
    34.                 spec: {
    35.                         ports: [{
    36.                                 name:       "http"
    37.                                 protocol:   "TCP"
    38.                                 port:       80
    39.                                 targetPort: 8080
    40.                         }]
    41.                         selector: app: "hello-world"
    42.                         type: "LoadBalancer"
    43.                 }
    44.                 apiVersion: "v1"
    45.                 kind:       "Service"
    46.         }
    47.         parameter: {}
    49. }

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

    After initializing definition files, run vela def vet <my-def.cue> to validate if there are any syntax error in the definition file.

    After confirming the definition file has correct syntax, users can apply this definition into control plane by:

    1. vela def apply my-comp.cue --namespace my-namespace

    The definition will be applied to the namespace named my-namespace, by default the namespace is vela-system。

    tip

    When definition applied to vela-system, the definition can be used for all applications in this cluster. If definitions are applied in some other namespaces, only the application in the same namespace can use that. It’s useful when in multi-tenant cases.

    If you want to check the transformed Kubernetes API format, you can use --dry-run can achieve that.

    1. vela def apply my-comp.cue --dry-run

    expected output

    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

    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 will automatically convert the YAML object into the CUE-format definition.

    1. vela def get my-comp

    You can list all definitions installed through:

    1. vela def list

    You can filter type by:

    • List component only:

      1. vela def list -t component
      1. vela def list -t workflow-step

    • List policy only:

      1. vela def list -t policy

    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 favorite editor.

    1. EDITOR=vim vela def edit my-comp

    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

    When we want to debug definition with application, we can use vela dry-run --definitions or -d for short, to specify local definitions.

    Dry run will help you to understand what are the real resources which will to be expanded and deployed to the Kubernetes cluster. In other words, it will mock to run the same logic as KubeVela’s controller and output the results locally.

    For example, let’s dry-run the following application:

    1. # app.yaml
    2. apiVersion: core.oam.dev/v1beta1
    3. kind: Application
    4. metadata:
    5.   name: vela-app
    6. spec:
    7.   components:
    8.     - name: express-server
    9.       type: my-comp

    Use dry run for test:

    1. vela dry-run -f app.yaml -d my-comp.cue

    caution

    Before KubeVela CLI 1.6.2, you can only use definition in Kubernetes API format.

    1. ---
    2. # Application(vela-app) -- Component(express-server)
    3. ---
    5. apiVersion: apps/v1
    6. kind: Deployment
    7. metadata:
    8.   annotations: {}
    9.   labels:
    10.     app.oam.dev/appRevision: ""
    11.     app.oam.dev/component: express-server
    12.     app.oam.dev/name: vela-app
    13.     app.oam.dev/namespace: default
    14.     app.oam.dev/resourceType: WORKLOAD
    15.     workload.oam.dev/type: my-comp
    16.   name: hello-world
    17.   namespace: default
    18. spec:
    19.   replicas: 1
    20.   selector:
    21.     matchLabels:
    22.       app.kubernetes.io/name: hello-world
    23.   template:
    24.     metadata:
    25.       labels:
    26.         app.kubernetes.io/name: hello-world
    27.     spec:
    28.       containers:
    29.       - image: somefive/hello-world
    30.         name: hello-world
    31.         ports:
    32.         - containerPort: 80
    33.           name: http
    34.           protocol: TCP
    36. ---
    37. ## From the auxiliary workload
    38. apiVersion: v1
    39. kind: Service
    40. metadata:
    41.   annotations: {}
    42.   labels:
    43.     app.oam.dev/appRevision: ""
    44.     app.oam.dev/component: express-server
    45.     app.oam.dev/name: vela-app
    46.     app.oam.dev/namespace: default
    47.     app.oam.dev/resourceType: TRAIT
    48.     trait.oam.dev/resource: hello-world-service
    49.     trait.oam.dev/type: AuxiliaryWorkload
    50.   name: hello-world-service
    51.   namespace: default
    52. spec:
    53.   ports:
    54.   - name: http
    55.     port: 80
    56.     protocol: TCP
    57.     targetPort: 8080
    58.   selector:
    59.     app: hello-world
    60.   type: LoadBalancer
    62. ---