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

Scaler

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

Apply To Component Types

• webservice
• worker
• task

Parameters

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

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	false
dataSourceRef		dataSourceRef	false
dataSource		dataSource	false
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	false
mountPath		string	true
mountToEnv		mountToEnv	false
mountOnly		bool	true	false
data		map[string]{null	bool	string
stringData		map[string]{null	bool	string
readOnly		bool	true	false

configMap

NAME	DESCRIPTION	TYPE	REQUIRED	DEFAULT
name		string	true
defaultMode		int	true	420
items		[]items	false
mountPath		string	true
mountToEnv		mountToEnv	false
mountOnly		bool	true	false
data		map[string]{null	bool	string
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

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

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

NAME	DESCRIPTION	TYPE	REQUIRED	DEFAULT
patches	a list of StrategicMerge or JSON6902 patch to selected target	[]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	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

NAME	DESCRIPTION	TYPE	REQUIRED	DEFAULT
patchesJson	A list of JSON6902 patch.	[]patchesJson	true

patchesJson

NAME	DESCRIPTION	TYPE	REQUIRED	DEFAULT
patch		patch	true
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

NAME	DESCRIPTION	TYPE	REQUIRED	DEFAULT
patchesStrategicMerge	a list of strategicmerge, defined as inline yaml objects.	[]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

+---------+-----------------------------------------+-----------------------+----------+---------+ | 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 | 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