Skip to main content
Version: Next

Built-in Policy Type

This documentation will walk through all the built-in policy types sorted alphabetically.

It was generated automatically by scripts, please don't update manually, last updated at 2023-07-28T09:33:26+08:00.

Apply-Once

Description

Allow configuration drift for applied resources, delivery the resource without continuously reconciliation.

Examples (apply-once)

It's generally used in one time delivery only without continuous management scenario.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: apply-once-app
spec:
components:
- name: hello-world
type: webservice
properties:
image: oamdev/hello-world
traits:
- type: scaler
properties:
replicas: 1
policies:
- name: apply-once
type: apply-once
properties:
enable: true

Specification (apply-once)

NameDescriptionTypeRequiredDefault
enableWhether to enable apply-once for the whole application.boolfalsefalse
rulesSpecify the rules for configuring apply-once policy in resource level.[]rulesfalse

rules (apply-once)

NameDescriptionTypeRequiredDefault
selectorSpecify how to select the targets of the rule.selectorfalse
strategySpecify the strategy for configuring the resource level configuration drift behaviour.strategytrue
selector (apply-once)
NameDescriptionTypeRequiredDefault
componentNamesSelect resources by component names.[]stringfalse
componentTypesSelect resources by component types.[]stringfalse
oamTypesSelect resources by oamTypes (COMPONENT or TRAIT).[]stringfalse
traitTypesSelect resources by trait types.[]stringfalse
resourceTypesSelect resources by resource types (like Deployment).[]stringfalse
resourceNamesSelect resources by their names.[]stringfalse
strategy (apply-once)
NameDescriptionTypeRequiredDefault
affectWhen the strategy takes effect,e.g. onUpdate、onStateKeep.stringfalse
pathSpecify the path of the resource that allow configuration drift.[]stringtrue

Garbage-Collect

Description

Configure the garbage collect behaviour for the application.

Examples (garbage-collect)

It's used in garbage collection scenario. It can be used to configure the collection policy, e.g. don't delete the legacy resources when updating.

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: ingress-1-20
properties:
domain: testsvc.example.com
http:
"/": 8000
policies:
- name: keep-legacy-resource
type: garbage-collect
properties:
keepLegacyResource: true
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: garbage-collect-app
spec:
components:
- name: hello-world-new
type: webservice
properties:
image: oamdev/hello-world
traits:
- type: expose
properties:
port: [8000]
policies:
- name: garbage-collect
type: garbage-collect
properties:
rules:
- selector:
traitTypes:
- expose
strategy: onAppDelete

Specification (garbage-collect)

NameDescriptionTypeRequiredDefault
applicationRevisionLimitIf set, it will override the default revision limit number and customize this number for the current application.intfalse
keepLegacyResourceIf is set, outdated versioned resourcetracker will not be recycled automatically, outdated resources will be kept until resourcetracker be deleted manually.boolfalsefalse
continueOnFailureIf is set, continue to execute gc when the workflow fails, by default gc will be executed only after the workflow succeeds.boolfalsefalse
rulesSpecify the list of rules to control gc strategy at resource level, if one resource is controlled by multiple rules, first rule will be used.[]rulesfalse

rules (garbage-collect)

NameDescriptionTypeRequiredDefault
selectorSpecify how to select the targets of the rule.selectortrue
strategySpecify the strategy for target resource to recycle."onAppUpdate" or "onAppDelete" or "never"falseonAppUpdate
propagationSpecify the deletion propagation strategy for target resource to delete."orphan" or "cascading"false
selector (garbage-collect)
NameDescriptionTypeRequiredDefault
componentNamesSelect resources by component names.[]stringfalse
componentTypesSelect resources by component types.[]stringfalse
oamTypesSelect resources by oamTypes (COMPONENT or TRAIT).[]stringfalse
traitTypesSelect resources by trait types.[]stringfalse
resourceTypesSelect resources by resource types (like Deployment).[]stringfalse
resourceNamesSelect resources by their names.[]stringfalse

Override

Description

Describe the configuration to override when deploying resources, it only works with specified deploy step in workflow.

Examples (override)

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: deploy-with-override
namespace: examples
spec:
components:
- name: nginx-with-override
type: webservice
properties:
image: nginx
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
- name: topology-local
type: topology
properties:
clusters: ["local"]
namespace: examples-alternative
- name: override-nginx-legacy-image
type: override
properties:
components:
- name: nginx-with-override
properties:
image: nginx:1.20
- name: override-high-availability
type: override
properties:
components:
- type: webservice
traits:
- type: scaler
properties:
replicas: 3
workflow:
steps:
- type: deploy
name: deploy-local
properties:
policies: ["topology-local"]
- type: deploy
name: deploy-hangzhou
properties:
policies: ["topology-hangzhou-clusters", "override-nginx-legacy-image", "override-high-availability"]
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: advance-override
namespace: examples
spec:
components:
- name: nginx-advance-override-legacy
type: webservice
properties:
image: nginx:1.20
- name: nginx-advance-override-latest
type: webservice
properties:
image: nginx
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
- name: topology-local
type: topology
properties:
clusters: ["local"]
namespace: examples-alternative
- name: override-nginx-legacy
type: override
properties:
selector: ["nginx-advance-override-legacy"]
- name: override-nginx-latest
type: override
properties:
selector: ["nginx-advance-override-latest", "nginx-advance-override-stable"]
components:
- name: nginx-advance-override-stable
type: webservice
properties:
image: nginx:stable
workflow:
steps:
- type: deploy
name: deploy-local
properties:
policies: ["topology-local", "override-nginx-legacy"]
- type: deploy
name: deploy-hangzhou
properties:
policies: ["topology-hangzhou-clusters", "override-nginx-latest"]

Specification (override)

NameDescriptionTypeRequiredDefault
componentsSpecify the overridden component configuration.[]componentstrue
selectorSpecify a list of component names to use, if empty, all components will be selected.[]stringfalse

components (override)

NameDescriptionTypeRequiredDefault
nameSpecify the name of the patch component, if empty, all components will be merged.stringfalse
typeSpecify the type of the patch component.stringfalse
propertiesSpecify the properties to override.map[string]_false
traitsSpecify the traits to override.[]traitsfalse
traits (override)
NameDescriptionTypeRequiredDefault
typeSpecify the type of the trait to be patched.stringtrue
propertiesSpecify the properties to override.map[string]_false
disableSpecify if the trait should be remove, default false.boolfalsefalse

Read-Only

Description

Configure the resources to be read-only in the application (no update / state-keep).

Examples (read-only)

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: read-only
spec:
components:
- name: busybox
type: worker
properties:
image: busybox
cmd:
- sleep
- '1000000'
policies:
- type: read-only
name: read-only
properties:
rules:
- selector:
resourceTypes: ["Deployment"]

Specification (read-only)

NameDescriptionTypeRequiredDefault
rulesSpecify the list of rules to control read only strategy at resource level.[]rulesfalse

rules (read-only)

NameDescriptionTypeRequiredDefault
selectorSpecify how to select the targets of the rule.selectortrue
selector (read-only)
NameDescriptionTypeRequiredDefault
componentNamesSelect resources by component names.[]stringfalse
componentTypesSelect resources by component types.[]stringfalse
oamTypesSelect resources by oamTypes (COMPONENT or TRAIT).[]stringfalse
traitTypesSelect resources by trait types.[]stringfalse
resourceTypesSelect resources by resource types (like Deployment).[]stringfalse
resourceNamesSelect resources by their names.[]stringfalse

Replication

Description

Describe the configuration to replicate components when deploying resources, it only works with specified deploy step in workflow.

Examples (replication)

Background

In KubeVela, we can dispatch resources across the clusters. But projects like OpenYurt have finer-grained division like node pool. This requires to dispatch some similar resources to the same cluster. These resources are called replication. Back to the example of OpenYurt, it can integrate KubeVela and replicate the resources then dispatch them to the different node pool.

Usage

Replication is an internal policy. It can be only used with deploy workflow step. When using replication policy. A new field replicaKey will be added to context. User can use definitions that make use of context.replicaKey. For example, apply a replica-webservice ComponentDefinition.

In this ComponentDefinition, we can use context.replicaKey to distinguish the name of Deployment and Service.

NOTE: ComponentDefinition below is trimmed for brevity. See complete YAML in replication.yaml

apiVersion: core.oam.dev/v1beta1
kind: ComponentDefinition
metadata:
annotations:
definition.oam.dev/description: Webservice, but can be replicated
name: replica-webservice
namespace: vela-system
spec:
workload:
type: autodetects.core.oam.dev
schematic:
cue:
template: |
output: {
apiVersion: "apps/v1"
kind: "Deployment"
metadata: {
if context.replicaKey != _|_ {
name: context.name + "-" + context.replicaKey
}
if context.replicaKey == _|_ {
name: context.name
}
}
spec: {
selector: matchLabels: {
"app.oam.dev/component": context.name
if context.replicaKey != _|_ {
"app.oam.dev/replicaKey": context.replicaKey
}
}

template: {
metadata: {
labels: {
if parameter.labels != _|_ {
parameter.labels
}
if parameter.addRevisionLabel {
"app.oam.dev/revision": context.revision
}
"app.oam.dev/name": context.appName
"app.oam.dev/component": context.name
if context.replicaKey != _|_ {
"app.oam.dev/replicaKey": context.replicaKey
}

}
if parameter.annotations != _|_ {
annotations: parameter.annotations
}
}
}
}
}
outputs: {
if len(exposePorts) != 0 {
webserviceExpose: {
apiVersion: "v1"
kind: "Service"
metadata: {
if context.replicaKey != _|_ {
name: context.name + "-" + context.replicaKey
}
if context.replicaKey == _|_ {
name: context.name
}
}
spec: {
selector: {
"app.oam.dev/component": context.name
if context.replicaKey != _|_ {
"app.oam.dev/replicaKey": context.replicaKey
}
}
ports: exposePorts
type: parameter.exposeType
}
}
}
}

Then user can apply application below. Replication policy is declared in application.spec.policies. These policies are used in deploy-with-rep workflow step. They work together to influence the deploy step.

  • override: select hello-rep component to deploy.
  • topology: select cluster local to deploy.
  • replication: select hello-rep component to replicate.

As a result, there will be two Deployments and two Services:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: app-replication-policy
spec:
components:
- name: hello-rep
type: replica-webservice
properties:
image: crccheck/hello-world
ports:
- port: 80
expose: true
policies:
- name: comp-to-replicate
type: override
properties:
selector: [ "hello-rep" ]
- name: target-default
type: topology
properties:
clusters: [ "local" ]
- name: replication-default
type: replication
properties:
keys: ["beijing","hangzhou"]
selector: ["hello-rep"]

workflow:
steps:
- name: deploy-with-rep
type: deploy
properties:
policies: ["comp-to-replicate","target-default","replication-default"]
kubectl get deploy -n default
NAME READY UP-TO-DATE AVAILABLE AGE
hello-rep-beijing 1/1 1 1 5s
hello-rep-hangzhou 1/1 1 1 5s

kubectl get service -n default
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
hello-rep-hangzhou ClusterIP 10.43.23.200 <none> 80/TCP 41s
hello-rep-beijing ClusterIP 10.43.24.116 <none> 80/TCP 12s

Specification (replication)

NameDescriptionTypeRequiredDefault
keysSpicify the keys of replication. Every key coresponds to a replication components.[]stringtrue
selectorSpecify the components which will be replicated.[]stringfalse

Resource-Update

Description

Configure the update strategy for selected resources.

Examples (resource-update)

resource-update policy can allow users to customize the update behavior for selected resources.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: recreate
spec:
components:
- type: k8s-objects
name: recreate
properties:
objects:
- apiVersion: v1
kind: Secret
metadata:
name: recreate
data:
key: dgo=
immutable: true
policies:
- type: resource-update
name: resource-update
properties:
rules:
- selector:
resourceTypes: ["Secret"]
strategy:
recreateFields: ["data.key"]

By specifying recreateFields, the application will recreate the target resource (Secret here) when the field changes (data.key here). If the field is not changed, the application will use the normal update (patch here).

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: recreate
spec:
components:
- type: k8s-objects
name: recreate
properties:
objects:
- apiVersion: v1
kind: ConfigMap
metadata:
name: recreate
data:
key: val
policies:
- type: resource-update
name: resource-update
properties:
rules:
- selector:
resourceTypes: ["ConfigMap"]
strategy:
op: replace

By specifying op to replace, the application will update the given resource (ConfigMap here) by replace. Compared to patch, which leverages three-way merge patch to only modify the fields managed by KubeVela application, "replace" will update the object as a whole and wipe out other fields even if it is not managed by the KubeVela application. It can be seen as an "application-level" ApplyResourceByReplace.

Specification (resource-update)

NameDescriptionTypeRequiredDefault
rulesSpecify the list of rules to control resource update strategy at resource level.[]rulesfalse

rules (resource-update)

NameDescriptionTypeRequiredDefault
selectorSpecify how to select the targets of the rule.selectortrue
strategyThe update strategy for the target resources.strategytrue
selector (resource-update)
NameDescriptionTypeRequiredDefault
componentNamesSelect resources by component names.[]stringfalse
componentTypesSelect resources by component types.[]stringfalse
oamTypesSelect resources by oamTypes (COMPONENT or TRAIT).[]stringfalse
traitTypesSelect resources by trait types.[]stringfalse
resourceTypesSelect resources by resource types (like Deployment).[]stringfalse
resourceNamesSelect resources by their names.[]stringfalse
strategy (resource-update)
NameDescriptionTypeRequiredDefault
opSpecify the op for updating target resources."patch" or "replace"falsepatch
recreateFieldsSpecify which fields would trigger recreation when updated.[]stringfalse

Shared-Resource

Description

Configure the resources to be sharable across applications.

Examples (shared-resource)

It's used in shared-resource scenario. It can be used to configure which resources can be shared between applications. The target resource will allow multiple application to read it but only the first one to be able to write it.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: app1
spec:
components:
- name: ns1
type: k8s-objects
properties:
objects:
- apiVersion: v1
kind: Namespace
metadata:
name: example
- name: cm1
type: k8s-objects
properties:
objects:
- apiVersion: v1
kind: ConfigMap
metadata:
name: cm1
namespace: example
data:
key: value1
policies:
- name: shared-resource
type: shared-resource
properties:
rules:
- selector:
resourceTypes: ["Namespace"]
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: app2
spec:
components:
- name: ns2
type: k8s-objects
properties:
objects:
- apiVersion: v1
kind: Namespace
metadata:
name: example
- name: cm2
type: k8s-objects
properties:
objects:
- apiVersion: v1
kind: ConfigMap
metadata:
name: cm2
namespace: example
data:
key: value2
policies:
- name: shared-resource
type: shared-resource
properties:
rules:
- selector:
resourceTypes: ["Namespace"]

Specification (shared-resource)

NameDescriptionTypeRequiredDefault
rulesSpecify the list of rules to control shared-resource strategy at resource level.[]rulesfalse

rules (shared-resource)

NameDescriptionTypeRequiredDefault
selectorSpecify how to select the targets of the rule.selectortrue
selector (shared-resource)
NameDescriptionTypeRequiredDefault
componentNamesSelect resources by component names.[]stringfalse
componentTypesSelect resources by component types.[]stringfalse
oamTypesSelect resources by oamTypes (COMPONENT or TRAIT).[]stringfalse
traitTypesSelect resources by trait types.[]stringfalse
resourceTypesSelect resources by resource types (like Deployment).[]stringfalse
resourceNamesSelect resources by their names.[]stringfalse

Take-Over

Description

Configure the resources to be able to take over when it belongs to no application.

Examples (take-over)

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: take-over
spec:
components:
- name: busybox
type: k8s-objects
properties:
objects:
- apiVersion: apps/v1
kind: Deployment
metadata:
name: busybox-ref
policies:
- type: take-over
name: take-over
properties:
rules:
- selector:
resourceTypes: ["Deployment"]

Specification (take-over)

NameDescriptionTypeRequiredDefault
rulesSpecify the list of rules to control take over strategy at resource level.[]rulesfalse

rules (take-over)

NameDescriptionTypeRequiredDefault
selectorSpecify how to select the targets of the rule.selectortrue
selector (take-over)
NameDescriptionTypeRequiredDefault
componentNamesSelect resources by component names.[]stringfalse
componentTypesSelect resources by component types.[]stringfalse
oamTypesSelect resources by oamTypes (COMPONENT or TRAIT).[]stringfalse
traitTypesSelect resources by trait types.[]stringfalse
resourceTypesSelect resources by resource types (like Deployment).[]stringfalse
resourceNamesSelect resources by their names.[]stringfalse

Topology

Description

Describe the destination where components should be deployed to.

Examples (topology)

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: basic-topology
namespace: examples
spec:
components:
- name: nginx-basic
type: webservice
properties:
image: nginx
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusters: ["hangzhou-1", "hangzhou-2"]
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: label-selector-topology
namespace: examples
spec:
components:
- name: nginx-label-selector
type: webservice
properties:
image: nginx
policies:
- name: topology-hangzhou-clusters
type: topology
properties:
clusterLabelSelector:
region: hangzhou
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: local-ns-topology
namespace: examples
spec:
components:
- name: nginx-local-ns
type: webservice
properties:
image: nginx
policies:
- name: topology-local
type: topology
properties:
clusters: ["local"]
namespace: examples-alternative

Specification (topology)

NameDescriptionTypeRequiredDefault
clustersSpecify the names of the clusters to select.[]stringfalse
clusterLabelSelectorSpecify the label selector for clusters.map[string]stringfalse
allowEmptyIgnore empty cluster error.boolfalse
clusterSelectorDeprecated: Use clusterLabelSelector instead.map[string]stringfalse
namespaceSpecify the target namespace to deploy in the selected clusters, default inherit the original namespace.stringfalse