kubevela
/
kubevela.github.io
mirror of https://github.com/kubevela/kubevela.github.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
kubevela.github.io/docs/end-user/traits/references.md

689 lines
22 KiB
Markdown
Raw Blame History

---
title: 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
```yaml
# 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
```yaml
# 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
```yaml
# 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](#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
```yaml
# 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
```shell
# 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
```shell
# 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](#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
```yaml
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](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/patchesjson6902/) to patch for the kustomize component.
### Apply To Component Types
* kustomize
### Parameters
| 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
```yaml
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](#patchesStrategicMerge) | true | |
#### patchesStrategicMerge
+-----------+-------------+--------------------------------------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-----------+-------------+--------------------------------------------------------+----------+---------+
| undefined | | map[string]{null|bool|string|bytes|{...}|[...]|number} | true | |
### Examples
```yaml
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:
```yaml
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.
```yaml
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.
```yaml
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.
```yaml
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](#volumes) | false | |
+---------+-----------------------------------------+-----------------------+----------+---------+
## volumes
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
| --------- | ----------- | ------ | -------- | ------- |
| name | | string | true | |
| path | | string | true | |
### Examples
```yaml
# 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
```
Reference in New Issue View Git Blame Copy Permalink