Definition

    With the help of OAM definitions, the platform builder can easily adopt infrastructure capabilities from ecosystem, hide complexity with their best practices without losing any extensibility, the most important is the application won’t be affected even if we change the capability providers.

    The picture above is an example of definition, we can use FluxCD or as Helm capability provider. Once the platform builder registered the definition written by CUE, the end user can discover the helm capability and define application by referring to the type.

    There’re mainly four types of definitions in KubeVela, they’re ComponentDefinition, TraitDefinition, PolicyDefinition and WorkflowStepDefinition, corresponding to the application concepts. As an end user, you can get out-of-box definitions from KubeVela community.

    There’re two sources to get out-of-box definitions:

    • Built-in definitions will be installed along with KubeVela helm chart. You can refer to the following links to learn more about built-in definitions.
    • Install Addons, they’re scenario-oriented system extensions of KubeVela, each addon contains a bunch of definitions along its CRD controllers.
      • The community has a which contains a large catalog of addons, the registry is maintained by the KubeVela team.

    Lifecycle of a Definition

    A definition’s lifecycle usually has 3 stages:

    • Check the definition list

    expected output

    1. NAME                            TYPE                    NAMESPACE   DESCRIPTION
    2. webservice                      ComponentDefinition     vela-system Describes long-running, scalable, containerized services
    3.                                                                     that have a stable network endpoint to receive external
    4.                                                                     network traffic from customers.
    5. gateway                         TraitDefinition         vela-system Enable public web traffic for the component, the ingress API
    6.                                                                     matches K8s v1.20+.
    7. health                          PolicyDefinition        vela-system Apply periodical health checking to the application.
    8. notification                    WorkflowStepDefinition  vela-system Send message to webhook
    9. ...snip...
    • Show property details of one definition

    expected output

    1. # Properties
    2. +------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
    3. |       NAME       |                                        DESCRIPTION                                        |               TYPE                | REQUIRED | DEFAULT |
    4. +------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
    5. | cmd              | Commands to run in the container                                                          | []string                          | false    |         |
    6. | env              | Define arguments by using environment variables                                           | [[]env](#env)                     | false    |         |
    7. | labels           | Specify the labels in the workload                                                        | map[string]string                 | false    |         |
    8. | annotations      | Specify the annotations in the workload                                                   | map[string]string                 | false    |         |
    9. | image            | Which image would you like to use for your service                                        | string                            | true     |         |
    10. | ports            | Which ports do you want customer traffic sent to, defaults to 80                          | [[]ports](#ports)                 | false    |         |
    11. +------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
    12. ...snip...

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

    Once installed, these definitions can be discovered and generated with forms by the UI console automatically. More than that, you can even customize the layout by defining the ui schema like below.

    alt

    Using definition on UI console is very straight forward, just click along with the application creation process.

    1. Create Application and choose Component type which is actually choosing which component definition to use.
    2. Fill the properties of component is actually fill the parameter of component definition.
    3. The same step for trait, policy and workflow.
    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
    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.             traits:
    34.               - type: scaler
    35.                 properties:
    36.                   replicas: 2
    37.   workflow:
    38.     steps:
    39.       - name: deploy2default
    40.         type: deploy
    41.         properties:
    43.       - name: manual-approval
    44.         type: suspend
    45.       - name: deploy2prod
    46.         type: deploy
    47.         properties:
    48.           policies: ["target-prod", "deploy-ha"]

    Use the definition in vela command line works the same, you can compose the application yaml manually and deploy by vela up command.

    Application is also one kind of Kubernetes CRD, you can also use kubectl apply or invoke Kubernetes API to integrate with vela application.

    caution

    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 . 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. }
    6. template: {
    7.     parameter: {
    8.         name:  string
    9.         image: string
    10.     }
    11.     output: {
    12.         apiVersion: "apps/v1"
    13.         kind:       "Deployment"
    14.         spec: {
    15.             containers: [{
    16.                 name:  parameter.name
    17.                 image: parameter.image
    18.             }]
    19.         }
    20. }