Built-in Trait Type

This documentation will walk through the built-in traits.

gateway

The gateway trait exposes a component to public Internet via a valid domain.

Apply To Component Types

• all component types

Parameters

NAME	DESCRIPTION	TYPE	REQUIRED	DEFAULT
http	Specify the mapping relationship between the http path and the workload port	map[string]int	true
class	Specify the class of ingress to use	string	true	nginx
classInSpec	Set ingress class in '.spec.ingressClassName' instead of 'kubernetes.io/ingress.class' annotation.	bool	false	false
domain	Specify the domain you want to expose	string	true

Examples

# vela-app.yaml

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: first-vela-app

spec:

components:

- name: express-server

type: webservice

properties:

image: oamdev/hello-world

port: 8000

traits:

- type: gateway

properties:

domain: testsvc.example.com

http:

"/": 8000

rollout

Rollout Trait performs a rolling update on Component.

Apply To Component Types

• webservice
• worker
• clonset

Parameters

Name	Description	Type	Required	Default
targetRevision	The target ComponentRevision	string	No	If this field is empty, it will always point to the latest revision
targetSize	Number of target Workload's replicas	int	Yes	Nil
rolloutBatches	Strategy of rolling update	[]rolloutBatch	Yes	Nil
batchPartition	Partition of rolloutBatches	int	No	Nil, if this field is empty, all batches will be updated

Configurations of rolloutBatch

Name	Description	Type	Required	Default
replicas	number of replicas in one batch	int	Yes	Nil

Examples

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: rollout-trait-test

spec:

components:

- name: express-server

type: webservice

externalRevision: express-server-v1

properties:

image: stefanprodan/podinfo:4.0.3

traits:

- type: rollout

properties:

targetSize: 5

rolloutBatches:

- replicas: 2

- replicas: 3

Scaler

The scaler trait allows you to change the replicas for the component.

Apply To Component Types

• webservice
• worker
• task

Parameters

$ vela show scaler

# Properties

+----------+--------------------------------+------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+----------+--------------------------------+------+----------+---------+

| replicas | Specify the number of workload | int | true | 1 |

+----------+--------------------------------+------+----------+---------+

Examples

# sample.yaml

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: website

spec:

components:

- name: frontend # This is the component I want to deploy

type: webservice

properties:

image: nginx

traits:

- type: scaler # Set the replica to the specified value

properties:

replicas: 5

AutoScaler

autoscaler trait use K8s HPA to control the replica of component.

Note: autoscaler trait is hidden by default in VelaUX, you can use it in CLI.

Apply To Component Types

• All component based on deployments.apps

Parameters

NAME	DESCRIPTION	TYPE	REQUIRED	DEFAULT
min	Specify the minimal number of replicas to which the autoscaler can scale down	int	true	1
max	Specify the maximum number of of replicas to which the autoscaler can scale up	int	true	10
cpuUtil	Specify the average cpu utilization, for example, 50 means the CPU usage is 50%	int	true	50

Examples

# sample.yaml

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: website

spec:

components:

- name: frontend # This is the component I want to deploy

type: webservice

properties:

image: nginx

traits:

- type: cpuscaler # Automatically scale the component by CPU usage after deployed

properties:

min: 1

max: 10

cpuPercent: 60

Storage

The storage trait allows you to manage storages for the component.

storage can help us create and bind storages like pvc, emptyDir, secret, or configMap for our component. For secret and configMap type storage, we can also bind it to the env.

If you don't want to create the storages automatically, you can set mountOnly to true.

Apply To Component Types

• All component based on deployments.apps

Parameters

$ vela show storage

# Properties

## pvc

+------------------+-------------+---------------------------------+----------+------------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+------------------+-------------+---------------------------------+----------+------------+

| name | | string | true | |

| volumeMode | | string | true | Filesystem |

| mountPath | | string | true | |

| mountOnly | | bool | true | false |

| accessModes | | [...] | true | |

| volumeName | | string | false | |

| storageClassName | | string | false | |

| resources | | [resources](#resources) | false | |

| dataSourceRef | | [dataSourceRef](#dataSourceRef) | false | |

| dataSource | | [dataSource](#dataSource) | false | |

| selector | | [selector](#selector) | false | |

+------------------+-------------+---------------------------------+----------+------------+

...

## emptyDir

+-----------+-------------+--------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-----------+-------------+--------+----------+---------+

| name | | string | true | |

| medium | | string | true | empty |

| mountPath | | string | true | |

+-----------+-------------+--------+----------+---------+

## secret

+-------------+-------------+--------------------------------------------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-------------+-------------+--------------------------------------------------------+----------+---------+

| name | | string | true | |

| defaultMode | | int | true | 420 |

| items | | [[]items](#items) | false | |

| mountPath | | string | true | |

| mountToEnv | | [mountToEnv](#mountToEnv) | false | |

| mountOnly | | bool | true | false |

| data | | map[string]{null|bool|string|bytes|{...}|[...]|number} | false | |

| stringData | | map[string]{null|bool|string|bytes|{...}|[...]|number} | false | |

| readOnly | | bool | true | false |

+-------------+-------------+--------------------------------------------------------+----------+---------+

...

## configMap

+-------------+-------------+--------------------------------------------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-------------+-------------+--------------------------------------------------------+----------+---------+

| name | | string | true | |

| defaultMode | | int | true | 420 |

| items | | [[]items](#items) | false | |

| mountPath | | string | true | |

| mountToEnv | | [mountToEnv](#mountToEnv) | false | |

| mountOnly | | bool | true | false |

| data | | map[string]{null|bool|string|bytes|{...}|[...]|number} | false | |

| readOnly | | bool | true | false |

+-------------+-------------+--------------------------------------------------------+----------+---------+

Examples

# sample.yaml

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: storage-app

spec:

components:

- name: express-server

type: webservice

properties:

image: oamdev/hello-world

ports:

- port: 8000

traits:

- type: storage

properties:

# PVC type storage

pvc:

- name: test1

mountPath: /test/mount/pvc

# EmptyDir type storage

emptyDir:

- name: test1

mountPath: /test/mount/emptydir

# ConfigMap type storage

configMap:

- name: test1

mountPath: /test/mount/cm

# Mount ConfigMap to Env

mountToEnv:

envName: TEST_ENV

configMapKey: key1

data:

key1: value1

key2: value2

# Secret type storage

secret:

- name: test1

mountPath: /test/mount/secret

# Mount Secret to Env

mountToEnv:

envName: TEST_SECRET

secretKey: key1

data:

key1: dmFsdWUx

key2: dmFsdWUy

Labels

labels trait allow us to mark labels on Pod for workload.

Note: labels trait are hidden by default in VelaUX, you can use them in CLI.

Apply To Component Types

• all component types

Parameters

$ vela show labels

# Properties

+-----------+-------------+-------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-----------+-------------+-------------------+----------+---------+

| - | | map[string]string | true | |

+-----------+-------------+-------------------+----------+---------+

They're all string Key-Value pairs.

Examples

# myapp.yaml

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: myapp

spec:

components:

- name: express-server

type: webservice

properties:

image: oamdev/hello-world

port: 8000

traits:

- type: labels

properties:

"release": "stable"

Annotations

annotations trait allow us to mark annotations on Pod for workload.

Note: annotations trait are hidden by default in VelaUX, you can use them in CLI.

Apply To Component Types

• all component types

Parameters

$ vela show annotations

# Properties

+-----------+-------------+-------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-----------+-------------+-------------------+----------+---------+

| - | | map[string]string | true | |

+-----------+-------------+-------------------+----------+---------+

They're all string Key-Value pairs.

Examples

# myapp.yaml

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: myapp

spec:

components:

- name: express-server

type: webservice

properties:

image: oamdev/hello-world

port: 8000

traits:

- type: annotations

properties:

"description": "web application"

kustomize-patch

Trait kustomize-patch will patch on the Kustomize component.

Note: To use kustomize trait, you must enable fluxcd addon first.

Apply To Component Types

• kustomize

Parameters

vela show kustomize-patch

# Properties

+---------+---------------------------------------------------------------+-----------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+---------+---------------------------------------------------------------+-----------------------+----------+---------+

| patches | a list of StrategicMerge or JSON6902 patch to selected target | [[]patches](#patches) | true | |

+---------+---------------------------------------------------------------+-----------------------+----------+---------+

## patches

+--------+---------------------------------------------------+-------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+--------+---------------------------------------------------+-------------------+----------+---------+

| patch | Inline patch string, in yaml style | string | true | |

| target | Specify the target the patch should be applied to | [target](#target) | true | |

+--------+---------------------------------------------------+-------------------+----------+---------+

### target

+--------------------+-------------+--------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+--------------------+-------------+--------+----------+---------+

| name | | string | false | |

| group | | string | false | |

| version | | string | false | |

| kind | | string | false | |

| namespace | | string | false | |

| annotationSelector | | string | false | |

| labelSelector | | string | false | |

+--------------------+-------------+--------+----------+---------+

Examples

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: bucket-app

spec:

components:

- name: bucket-comp

type: kustomize

# ... omitted for brevity

traits:

- type: kustomize-patch

properties:

patches:

- patch: |-

apiVersion: v1

kind: Pod

metadata:

name: not-used

labels:

app.kubernetes.io/part-of: test-app

target:

labelSelector: "app=podinfo"

In this example, the kustomize-patch will patch the content for all Pods with label app=podinfo.

kustomize-json-patch

You could use this trait in JSON6902 format to patch for the kustomize component.

Apply To Component Types

• kustomize

Parameters

vela show kustomize-json-patch

# Properties

+-------------+---------------------------+-------------------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-------------+---------------------------+-------------------------------+----------+---------+

| patchesJson | A list of JSON6902 patch. | [[]patchesJson](#patchesJson) | true | |

+-------------+---------------------------+-------------------------------+----------+---------+

## patchesJson

+--------+-------------+-------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+--------+-------------+-------------------+----------+---------+

| patch | | [patch](#patch) | true | |

| target | | [target](#target) | true | |

+--------+-------------+-------------------+----------+---------+

#### target

+--------------------+-------------+--------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+--------------------+-------------+--------+----------+---------+

| name | | string | false | |

| group | | string | false | |

| version | | string | false | |

| kind | | string | false | |

| namespace | | string | false | |

| annotationSelector | | string | false | |

| labelSelector | | string | false | |

+--------------------+-------------+--------+----------+---------+

### patch

+-------+-------------+--------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-------+-------------+--------+----------+---------+

| path | | string | true | |

| op | | string | true | |

| value | | string | false | |

+-------+-------------+--------+----------+---------+

Examples

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: bucket-app

spec:

components:

- name: bucket-comp

type: kustomize

# ... omitted for brevity

traits:

- type: kustomize-json-patch

properties:

patchesJson:

- target:

version: v1

kind: Deployment

name: podinfo

patch:

- op: add

path: /metadata/annotations/key

value: value

kustomize-strategy-merge

kustomize-strategy-merge trait provide strategy merge patch for kustomize component.

Apply To Component Types

• kustomize

Parameters

vela show kustomize-json-patch

# Properties

+-----------------------+-----------------------------------------------------------+---------------------------------------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-----------------------+-----------------------------------------------------------+---------------------------------------------------+----------+---------+

| patchesStrategicMerge | a list of strategicmerge, defined as inline yaml objects. | [[]patchesStrategicMerge](#patchesStrategicMerge) | true | |

+-----------------------+-----------------------------------------------------------+---------------------------------------------------+----------+---------+

## patchesStrategicMerge

+-----------+-------------+--------------------------------------------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-----------+-------------+--------------------------------------------------------+----------+---------+

| undefined | | map[string]{null|bool|string|bytes|{...}|[...]|number} | true | |

Examples

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: bucket-app

spec:

components:

- name: bucket-comp

type: kustomize

# ... omitted for brevity

traits:

- type: kustomize-strategy-merge

properties:

patchesStrategicMerge:

- apiVersion: apps/v1

kind: Deployment

metadata:

name: podinfo

spec:

template:

spec:

serviceAccount: custom-service-account

service-binding

Service binding trait will bind data from Kubernetes Secret to the application container's ENV.

Apply To Component Types

• webservice
• worker
• task
• cron-task

Parameters

Name	Description	Type	Required	Default
envMappings	The mapping of environment variables to secret	map[string]#KeySecret	true

KeySecret

Name	Description	Type	Required	Default
key	if key is empty, we will use envMappings key instead	string	false
secret	Kubernetes secret name	string	true

Examples

1. Prepare a Kubernetes Secret

The secret can be manually created, or generated by other component or external system.

For example, we have a secret db-conn-example whose data is as below:

endpoint: https://xxx.com

password: 123

username: myname

2. Bind the Secret into your component by service-binding trait

For example, we have a webservice component who needs to consume a database. The database connection string should be set to Pod environments: endpoint, username and DB_PASSWORD.

We can set the properties for envMappings as below. For each environment, secret represents the secret name, and key represents the key of the secret.

Here is the complete properties for the trait.

traits:

- type: service-binding

properties:

envMappings:

DB_PASSWORD:

secret: db-conn-example

key: password

endpoint:

secret: db-conn-example

key: endpoint

username:

secret: db-conn-example

key: username

In particular, if the environment name, like endpoint, is same to the key of the secret, we can omit the key. So we can simplify the properties as below.

traits:

- type: service-binding

properties:

envMappings:

DB_PASSWORD:

secret: db-conn-example

key: password

endpoint:

secret: db-conn-example

username:

secret: db-conn-example

We can finally prepare an Application for the business component binding-test-comp to consume the secret, which is a representative of a database cloud resource.

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: webapp

spec:

components:

- name: binding-test-comp

type: webservice

properties:

image: zzxwill/flask-web-application:v0.3.1-crossplane

ports: 80

traits:

- type: service-binding

properties:

envMappings:

# environments refer to db-conn secret

DB_PASSWORD:

secret: db-conn-example

key: password

endpoint:

secret: db-conn-example

username:

secret: db-conn-example

Deploy this YAML and the Secret db-conn-example will be binding into environment of workload.

sidecar

The sidecar trait allows you to attach a sidecar container to the component.

Apply To Component Types

• webservice
• worker
• task
• cron-task

Parameters

# Properties

+---------+-----------------------------------------+-----------------------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+---------+-----------------------------------------+-----------------------+----------+---------+

| name | Specify the name of sidecar container | string | true | |

| cmd | Specify the commands run in the sidecar | []string | false | |

| image | Specify the image of sidecar container | string | true | |

| volumes | Specify the shared volume path | [[]volumes](#volumes) | false | |

+---------+-----------------------------------------+-----------------------+----------+---------+

## volumes

+-----------+-------------+--------+----------+---------+

| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |

+-----------+-------------+--------+----------+---------+

| name | | string | true | |

| path | | string | true | |

+-----------+-------------+--------+----------+---------+

Examples

# app.yaml

apiVersion: core.oam.dev/v1beta1

kind: Application

metadata:

name: vela-app-with-sidecar

spec:

components:

- name: log-gen-worker

type: worker

properties:

image: busybox

cmd:

- /bin/sh

- -c

- >

i=0;

while true;

do

echo "$i: $(date)" >> /var/log/date.log;

i=$((i+1));

sleep 1;

done

volumes:

- name: varlog

mountPath: /var/log

type: emptyDir

traits:

- type: sidecar

properties:

name: count-log

image: busybox

cmd: [ /bin/sh, -c, 'tail -n+1 -f /var/log/date.log']

volumes:

- name: varlog

path: /var/log