CUE based Addon Application

    • Utilize the flexible and concise syntax of the CUE language, rich built-in functions and its parameter verification capabilities, to render and deploy the application and auxiliary resources with parameters and metadata of addon.
    • An addon may contain multiple Definitions and CRD Operators. They can be selectively installed according to parameters of the addon.

    This doc will introduce how to define addon application by writing CUE files.

    Application description files contain two parts: application template files and resource files (they are in the folder).

    The most important part in the application template is output field, which must place a KubeVela application as follows:

    In this example, the name of the namespace defined in spec.components[0].properties.objects[0] of this application is determined by parameter.namespace, which means that its name will be dynamically rendered by the namespace parameter when the addon is enabled. If you want the created namespace to be my-namespace, you can run the following command:

    1. vela addon enable <addon-name> namespace=my-namespace

    After rendered, the resulting application is:

    1. kind: Application
    2. metadata:
    3. spec:
    4.   components:
    5.     - name: namespace
    6.       type: k8s-objects
    7.       properties:
    8.         objects:
    9.           - apiVersion: v1
    10.             kind: Namespace
    11.             metadata:
    12.               name: my-namespace

    You can refer to the CUE basic to learn language details.

    In the example above, we use the parameter namespace to set the name of Kubernetes namespace resource. Actually, we also need a parameter definition file (parameter.cue) to declare what parameters this addon has. For example,

    1. parameter: {
    2.   //+usage=namespace to create
    3.   namespace: string
    4. }

    When enabling the addon, you can set the parameters declared in the parameter definition file by appending the parameters to the command, as follows:

    1. vela addon enable <addon-Name> <parameter-name-1=value> <parameter-name-2=value>

    KubeVela has supported CUE package in an addon, which means you can define any CUE files containing data or schema inside the resources/ folder and reference them in application CUE file as a while package. This also help you avoid defining all content in one template file.

    Continuing with the example above, we split the CUE blocks that define the namesapce component under the resources/ folder, the folder structure is as follows:

    1. ├── resources/
    2. │   └── namespace.cue
    3. ├── README.md
    4. ├── metadata.yaml
    5. ├── parameter.cue
    6. └── template.cue

    The namespace.cue file is as follows:

    1. // resources/namespace.cue
    2. package main
    4. namespace: {
    5.     type: "k8s-objects"
    6.     name: "example-namespace"
    7.     properties: objects: [{
    8.         apiVersion: "v1"
    9.         kind:       "Namespace"
    10.         metadata: name: parameter.namespace
    11.     }]
    12. }

    Then we can reference this CUE block in template.cue :

    1. // template.cue
    3. package main
    5. output: {
    6.     apiVersion: "core.oam.dev/v1beta1"
    7.     kind:       "Application"
    8.     spec: {
    9.         // reference namespace block from resources/naemspace.cue
    10.         components: [namespace]
    11.     }
    12. }

    After enabled this addon with command $ vela addon enable <addon-name> namespace=my-namespace clusters=local,cluser1, the resulting application is:

    1. apiVersion: core.oam.dev/v1beta1
    2. kind: Application
    3. metadata:
    4.   name: example
    5.   namespace: vela-system
    6. spec:
    7.   components:
    8.     - name: namespace
    9.       type: k8s-objects
    10.       properties:
    11.         objects:
    12.           - apiVersion: v1
    13.             kind: Namespace
    14.             metadata:
    15.               name: my-namespace

    The NOTES.cue file allows you to display dynamic notifications once the addon has been enabled, based on specified parameters.

    For example, you can write the NOTES.cue as shown below:

    and parameter.cue as shown below:

    1. paramters: {
    2.     pluginOnly: *false | string

    When you enable the addon using the CLI, the information displayed in your console will vary depending on the specified parameter. For example, running the command:

    1. $ vela addon enable experimental/backstage

    Once the addon has been enabled, you will see the following notice::

    1. By default, the backstage app is strictly serving in the domain `127.0.0.1:7007`, check it by:
    2.         vela port-forward addon-backstage -n vela-system
    4. You can build your own backstage app if you want to use it in other domains.

    If you enable the addon with the parameter.pluginOnly=true setting, you will see this information:

    1. You can use the endpoint of 'backstage-plugin-vela' in your own backstage app by configuring the 'vela.host', refer to example https://github.com/wonderflow/vela-backstage-demo.

    This example is from the backstage addon, you can find more information by visiting this .

    This section will introduce the way of writing application description file to implement several core features of addon.

    If you want the resources in the addon to be installed not only in the control-plane, but also in managed clusters, you can use the topology policy in your application as shown below. The parameter clusters field will be filled when the addon is enabled with the clusters parameter specified.

    1. package main
    3. output: {
    4.     apiVersion: "core.oam.dev/v1beta1"
    5.     kind:       "Application"
    6.     spec: {
    7.         components:{...}
    8.         policies: [{
    9.             type: "topology"
    10.             name: "deploy-topology"
    11.             properties: {
    12.                 if parameter.clusters != _|_ {
    13.                     clusters: parameter.clusters
    14.                 }
    15.                 if parameter.clusters == _|_ {
    16.                     clusterLabelSelector: {}
    17.                 }
    18.             }
    19.         }]
    20.     }}

    If you execute the command to enable the addon as follows:

    1. $ vela addon enable <addon-name> --clusters=local,cluster1

    or:

    1. $ vela addon enable <addon-name> clusters="{local,cluster1}"

    The rendering result will be:

    1. kind: Application
    2. metadata:
    3.   name: addon-example
    4.   namespace: vela-system
    5. spec:
    6.   components: ...
    7.   policies:
    8.     - type: "topology"
    9.       name: "deploy-topology"
    10.       properties:
    11.         clusters:
    12.           - local
    13.           - cluster1

    After enabling the addon, the KubeVela controller will install components to the local and cluster1 clusters as defined in the application’s topology policy.

    If you need to enable the addon in all clusters, you can enable the addon by not setting the cluster parameter as follows:

    The rendering result is :

    1. kind: Application
    2. metadata:
    3.   name: addon-example
    4.   namespace: vela-system
    5. spec:
    6.   components: ...
    7.   policies:
    8.     - type: "topology"
    9.       name: "deploy-topology"
    10.       properties:
    11.         clusterLabelSelector: {}

    You can also define some auxiliary resources in the outputs field of the template.cue file. These resources will only be applied to the control plane.

    1. package main
    3. output: {
    4.     apiVersion: "core.oam.dev/v1beta1"
    5.     kind:       "Application"
    6.     spec: {
    8.     }
    9.     ... 
    10. }
    12. outputs: resourceTree: {
    13.     apiVersion: "v1"
    14.     kind:       "ConfigMap"
    15.     metadata: {
    16.         name:      "resource-tree"
    17.         namespace: "vela-system"
    18.         labels: {
    19.             "rules.oam.dev/resources":       "true"
    20.             "rules.oam.dev/resource-format": "json"
    21.     }
    22.     data: rules: json.Marshal(_rules)
    25. _rules: {...}

    In this example, we define a configmap resourceTree as an auxiliary resource, this configmap is actually a resource topology rule . The function of this resource is to establish the relationship of CustomResources in the cluster, so that it can be displayed in the topology graph. It only needs to be applied to control-plane.

    You can also run the cue eval *.cue resources/*.cue -e output -d yaml command from local to see the result of resource rendering.

    In addition to dynamically rendering the application by parameters, you can also read fields defined in metadata.yaml for rendering. For example, you can define a template.cue file as follows:

    1. output: {
    2.     apiVersion: "core.oam.dev/v1beta1"
    3.     kind:       "Application"
    4.     spec: {
    5.         components: [
    6.             {
    7.                 type: "webservice"
    8.                 properties: {
    9.                     image: "oamdev/vela-apiserver:" + context.metadata.version
    10.                 }
    11.             },
    12.         ]
    13.     }
    14. }

    When rendering, the fields defined in metadata.yaml will be put into the CUE block of context and rendered together with other CUE files. For example, the metadata.yaml is:

    1. ...
    2. name: velaux
    3. version: 1.2.4
    4. ...

    Resulting application is:

    1. apiVersion: core.oam.dev/v1beta1
    2. kind:       Application
    3. metadata:
    4.   name: addon-example
    5.   namespace: "vela-system"
    6. spec:
    7.   components:
    8.     - type: webservice
    9.       properties:
    10.         image: "oamdev/vela-apiserver:v1.2.4"

    The image tag becomes the addon’s version which the context.metadata.version field points to. The real example is . Other available fields of metadata please refer to metadata.

    When the addon is enabled, template.cue, parameter.cue and the resource files will be gathered with the addon metadata in metadata.yaml to render out the resources and apply them.

    If you want to bind a Definition to a component in the application, to dynamically enable the ability of one Definition, you can do it by setting addon.oam.dev/bind-component annotation on the Definition.

    An actual example is addon.

    ComponentDefinition kustomize in this addon is:

    1. kustomize: {
    2.     attributes: workload: type: "autodetects.core.oam.dev"
    3.     description: "kustomize can fetching, building, updating and applying Kustomize manifests from git repo."
    4.     type:        "component"
    5.     annotations: {
    6.          "addon.oam.dev/ignore-without-component": "fluxcd-kustomize-controller"
    7.    }
    8. }
    10. ...

    This Definition has an annotation "addon.oam.dev/bind-component": "fluxcd-kustomize-controller", which means, bind the ComponentDefinition to fluxcd-kustomize-controller component.

    The template.cue of this addon is:

    1. //...
    3. kustomizeController: {
    4.     type: "webService"
    5.     Name: "fluxcd-kustomize-controller",
    6.     //....
    7. }
    9. gitOpsController: [...]
    11. if parameter.onlyHelmComponents == false {
    12.     gitOpsController: [kustomizeController]
    13. }
    15. output: {
    16.     apiVersion: "core.oam.dev/v1beta1"
    17.     kind:       "Application"
    18.     spec: {
    19.         //...
    20.         components: [
    21.             helmController,
    22.             sourceController,
    23.         ] + gitOpsController
    24.         //...
    25.     }
    26. }
    27. //...

    If you enable this addon by following the command:

      The fluxcd-kustomize-controller component won’t be added to the application. The kustomize ComponentDefinitions will not be applied either.