Version: v1.3

Definition

Definition are the basic building block of the KubeVela platform. A definition encapsulates an arbitrarily complex automation as a lego style module that can be used to compose an Application, then safely shared, and repeatably executed by any KubeVela engine.

There’re four types of Definition, they’re ComponentDefinition, TraitDefinition, PolicyDefinition and WorkflowStepDefinition, corresponding to the application concepts.

There’re two sources of definitions:

A definition’s lifecycle usually has 3 stages:

When definitions installed in the system, they can be discovered by end user immediately.

  • Check the list:
  1. $ vela def list
  2. NAME TYPE NAMESPACE DESCRIPTION
  3. webservice ComponentDefinition vela-system Describes long-running, scalable, containerized services
  4. that have a stable network endpoint to receive external
  5. network traffic from customers.
  6. gateway TraitDefinition vela-system Enable public web traffic for the component, the ingress API
  7. matches K8s v1.20+.
  8. health PolicyDefinition vela-system Apply periodical health checking to the application.
  9. notification WorkflowStepDefinition vela-system Send message to webhook
  10. ...snip...
  • Show the details:
  1. $ vela show webservice
  2. # Properties
  3. +------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
  4. | NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
  5. +------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
  6. | cmd | Commands to run in the container | []string | false | |
  7. | env | Define arguments by using environment variables | [[]env](#env) | false | |
  8. | labels | Specify the labels in the workload | map[string]string | false | |
  9. | annotations | Specify the annotations in the workload | map[string]string | false | |
  10. | image | Which image would you like to use for your service | string | true | |
  11. | ports | Which ports do you want customer traffic sent to, defaults to 80 | [[]ports](#ports) | false | |
  12. +------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
  13. ...snip...

You can also view the details with a browser, the following command will launch a server and invoke your browser automatically:

  1. vela show webservice --web
  • Discover in UI console

alt

These definitions can also be discovered by the UI console, the more important thing is they can be displayed very well with ui schema defined.

If you’re a fan of our UI console, the usage of definition is very straight forward, just click along with the creation of the deployment process.

alt

Finally, the UI console will compose the whole deployment plan in the format of OAM like below, then KubeVela controller will take care of the rest things:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4. name: first-vela-app
  5. spec:
  6. components:
  7. - name: express-server
  8. type: webservice
  9. properties:
  10. image: oamdev/hello-world
  11. ports:
  12. - port: 8000
  13. expose: true
  14. traits:
  15. - type: scaler
  16. properties:
  17. replicas: 1
  18. policies:
  19. - name: target-default
  20. type: topology
  21. properties:
  22. clusters: ["local"]
  23. namespace: "default"
  24. - name: target-prod
  25. type: topology
  26. properties:
  27. clusters: ["local"]
  28. namespace: "prod"
  29. - name: deploy-ha
  30. type: override
  31. properties:
  32. components:
  33. - type: webservice
  34. traits:
  35. - type: scaler
  36. properties:
  37. replicas: 2
  38. workflow:
  39. steps:
  40. - name: deploy2default
  41. type: deploy
  42. properties:
  43. policies: ["target-default"]
  44. - name: manual-approval
  45. type: suspend
  46. - name: deploy2prod
  47. type: deploy
  48. properties:
  49. policies: ["target-prod", "deploy-ha"]

Use the definition in command works the same, you can compose the application yaml manually and use vela command line tool to deploy.

  1. vela up -f https://kubevela.net/example/applications/first-app.yaml

⚠️ In most cases, you don’t need to customize any definitions unless you’re going to extend the capability of KubeVela. Before that, you should check the built-in definitions and addons to confirm if they can fit your needs.

A new definition is built in a declarative template in CUE configuration language. If you’re not familiar with CUE, you can refer to CUE Basic for some knowledge.

A definition describes the module’s inputs, outputs, operations, and the wiring between them. Here is an example of a simple component definition:

  1. webserver: {
  2. type: "component"
  3. attributes: {}
  4. }
  5. template: {
  6. parameter: {
  7. name: string
  8. image: string
  9. }
  10. output: {
  11. apiVersion: "apps/v1"
  12. kind: "Deployment"
  13. spec: {
  14. containers: [{
  15. name: parameter.name
  16. image: parameter.image
  17. }]
  18. }
  19. }
  20. }

The type defines what kind of definition it is, the parameter defines the inputs, while the output section defines the outputs. You can refer to detail docs about how to manage definition or learn the definition protocol.

  • View Architecture to learn the overall architecture of KubeVela.

Last updated on Nov 1, 2022 by Tianxin Dong