Skip to main content
Version: v1.3

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#

NAMEDESCRIPTIONTYPEREQUIREDDEFAULT
httpSpecify the mapping relationship between the http path and the workload portmap[string]inttrue
classSpecify the class of ingress to usestringtruenginx
classInSpecSet ingress class in '.spec.ingressClassName' instead of 'kubernetes.io/ingress.class' annotation.boolfalsefalse
domainSpecify the domain you want to exposestringtrue

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#

Parameters#

NameDescriptionTypeRequiredDefault
targetRevisionThe target ComponentRevisionstringNoIf this field is empty, it will always point to the latest revision
targetSizeNumber of target Workload's replicasintYesNil
rolloutBatchesStrategy of rolling update[]rolloutBatchYesNil
batchPartitionPartition of rolloutBatchesintNoNil, if this field is empty, all batches will be updated

Configurations of rolloutBatch

NameDescriptionTypeRequiredDefault
replicasnumber of replicas in one batchintYesNil

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#

NAMEDESCRIPTIONTYPEREQUIREDDEFAULT
minSpecify the minimal number of replicas to which the autoscaler can scale downinttrue1
maxSpecify the maximum number of of replicas to which the autoscaler can scale upinttrue10
cpuUtilSpecify the average cpu utilization, for example, 50 means the CPU usage is 50%inttrue50

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#

NameDescriptionTypeRequiredDefault
envMappingsThe mapping of environment variables to secretmap[string]#KeySecrettrue

KeySecret#

NameDescriptionTypeRequiredDefault
keyif key is empty, we will use envMappings key insteadstringfalse
secretKubernetes secret namestringtrue

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
  1. 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
Last updated on by Jianbo Sun