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 2022-12-06T16:17:10+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.

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: apply-once-app
  5. spec:
  6.   components:
  7.     - name: hello-world
  8.       type: webservice
  9.       properties:
  10.         image: oamdev/hello-world
  11.       traits:
  12.         - type: scaler
  13.           properties:
  14.             replicas: 1
  15.   policies:
  16.     - name: apply-once
  17.       type: apply-once
  18.       properties:
  19.         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.

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: first-vela-app
  5. spec:
  6.   components:
  7.     - name: express-server
  8.       type: webservice
  9.       properties:
  10.         image: oamdev/hello-world
  11.         port: 8000
  12.       traits:
  13.         - type: ingress-1-20
  14.           properties:
  15.             domain: testsvc.example.com
  16.             http:
  17.               "/": 8000
  18.   policies:
  19.     - name: keep-legacy-resource
  20.       type: garbage-collect
  21.       properties:
  22.         keepLegacyResource: true
  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: garbage-collect-app
  5. spec:
  6.   components:
  7.     - name: hello-world-new
  8.       type: webservice
  9.       properties:
  10.         image: oamdev/hello-world
  11.       traits:
  12.         - type: expose
  13.           properties:
  14.             port: [8000]
  15.   policies:
  16.     - name: garbage-collect
  17.       type: garbage-collect
  18.       properties:
  19.         rules:
  20.           - selector:
  21.               traitTypes:
  22.                 - expose
  23.             strategy: onAppDelete

Specification (garbage-collect)

NameDescriptionTypeRequiredDefault
keepLegacyResourceIf is set, outdated versioned resourcetracker will not be recycled automatically, outdated resources will be kept until resourcetracker be deleted manually.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
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

Health

Description

Apply periodical health checking to the application.

Examples (health)

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: example-app-rollout
  5.   namespace: default
  6. spec:
  7.   components:
  8.     - name: hello-world-server
  9.       type: webservice
  10.       properties:
  11.         image: crccheck/hello-world
  12.         ports: 
  13.         - port: 8000
  14.           expose: true
  15.         type: webservice
  16.   policies:
  17.     - name: health-policy-demo
  18.       type: health
  19.       properties:
  20.         probeInterval: 5
  21.         probeTimeout: 10

Specification (health)

NameDescriptionTypeRequiredDefault
probeTimeoutSpecify health checking timeout(seconds), default 10s.intfalse10
probeIntervalSpecify health checking interval(seconds), default 30s.intfalse30

Override

Description

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

Examples (override)

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: deploy-with-override
  5.   namespace: examples
  6. spec:
  7.   components:
  8.     - name: nginx-with-override
  9.       type: webservice
  10.       properties:
  11.         image: nginx
  12.   policies:
  13.     - name: topology-hangzhou-clusters
  14.       type: topology
  15.       properties:
  16.         clusterLabelSelector:
  17.           region: hangzhou
  18.     - name: topology-local
  19.       type: topology
  20.       properties:
  21.         clusters: ["local"]
  22.         namespace: examples-alternative
  23.     - name: override-nginx-legacy-image
  24.       type: override
  25.       properties:
  26.         components:
  27.           - name: nginx-with-override
  28.             properties:
  29.               image: nginx:1.20
  30.     - name: override-high-availability
  31.       type: override
  32.       properties:
  33.         components:
  34.           - type: webservice
  35.             traits:
  36.               - type: scaler
  37.                 properties:
  38.                   replicas: 3
  39.   workflow:
  40.     steps:
  41.       - type: deploy
  42.         name: deploy-local
  43.         properties:
  44.           policies: ["topology-local"]
  45.       - type: deploy
  46.         name: deploy-hangzhou
  47.         properties:
  48.           policies: ["topology-hangzhou-clusters", "override-nginx-legacy-image", "override-high-availability"]
  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: advance-override
  5.   namespace: examples
  6. spec:
  7.   components:
  8.     - name: nginx-advance-override-legacy
  9.       type: webservice
  10.       properties:
  11.         image: nginx:1.20
  12.     - name: nginx-advance-override-latest
  13.       type: webservice
  14.       properties:
  15.         image: nginx
  16.   policies:
  17.     - name: topology-hangzhou-clusters
  18.       type: topology
  19.       properties:
  20.         clusterLabelSelector:
  21.           region: hangzhou
  22.     - name: topology-local
  23.       type: topology
  24.       properties:
  25.         clusters: ["local"]
  26.         namespace: examples-alternative
  27.     - name: override-nginx-legacy
  28.       type: override
  29.       properties:
  30.         selector: ["nginx-advance-override-legacy"]
  31.     - name: override-nginx-latest
  32.       type: override
  33.       properties:
  34.         selector: ["nginx-advance-override-latest", "nginx-advance-override-stable"]
  35.         components:
  36.           - name: nginx-advance-override-stable
  37.             type: webservice
  38.             properties:
  39.               image: nginx:stable
  40.   workflow:
  41.     steps:
  42.       - type: deploy
  43.         name: deploy-local
  44.         properties:
  45.           policies: ["topology-local", "override-nginx-legacy"]
  46.       - type: deploy
  47.         name: deploy-hangzhou
  48.         properties:
  49.           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

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

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: ComponentDefinition
  3. metadata:
  4.   annotations:
  5.     definition.oam.dev/description: Webservice, but can be replicated
  6.   name: replica-webservice
  7.   namespace: vela-system
  8. spec:
  9.   schematic:
  10.     cue:
  11.       template: |
  12.         output: {
  13.             apiVersion: "apps/v1"
  14.             kind:       "Deployment"
  15.             metadata: {
  16.                 if context.replicaKey != _|_ {
  17.                     name: context.name + "-" + context.replicaKey
  18.                 }
  19.                 if context.replicaKey == _|_ {
  20.                     name: context.name
  21.                 }
  22.             }
  23.             spec: {
  24.                 selector: matchLabels: {
  25.                     "app.oam.dev/component": context.name
  26.                     if context.replicaKey != _|_ {
  27.                         "app.oam.dev/replicaKey": context.replicaKey
  28.                     }
  29.                 }
  31.                 template: {
  32.                     metadata: {
  33.                         labels: {
  34.                             if parameter.labels != _|_ {
  35.                                 parameter.labels
  36.                             }
  37.                             if parameter.addRevisionLabel {
  38.                                 "app.oam.dev/revision": context.revision
  39.                             }
  40.                             "app.oam.dev/name":      context.appName
  41.                             "app.oam.dev/component": context.name
  42.                             if context.replicaKey != _|_ {
  43.                                 "app.oam.dev/replicaKey": context.replicaKey
  44.                             }
  46.                         }
  47.                         if parameter.annotations != _|_ {
  48.                             annotations: parameter.annotations
  49.                         }
  50.                     }
  51.                 }
  52.             }
  53.         }
  54.         outputs: {
  55.             if len(exposePorts) != 0 {
  56.                 webserviceExpose: {
  57.                     apiVersion: "v1"
  58.                     kind:       "Service"
  59.                     metadata: {
  60.                         if context.replicaKey != _|_ {
  61.                             name: context.name + "-" + context.replicaKey
  62.                         }
  63.                         if context.replicaKey == _|_ {
  64.                             name: context.name
  65.                         }
  66.                     }
  67.                     spec: {
  68.                         selector: {
  69.                             "app.oam.dev/component": context.name
  70.                             if context.replicaKey != _|_ {
  71.                                 "app.oam.dev/replicaKey": context.replicaKey
  72.                             }
  73.                         }
  74.                         ports: exposePorts
  75.                         type:  parameter.exposeType
  76.                     }
  77.                 }
  78.             }
  79.         }

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:

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: app-replication-policy
  5. spec:
  6.   components:
  7.     - name: hello-rep
  8.       type: replica-webservice
  9.       properties:
  10.         image: crccheck/hello-world
  11.         ports:
  12.           - port: 80
  13.             expose: true
  14.   policies:
  15.     - name: comp-to-replicate
  16.       type: override
  17.       properties:
  18.         selector: [ "hello-rep" ]
  19.     - name: target-default
  20.       type: topology
  21.       properties:
  22.         clusters: [ "local" ]
  23.     - name: replication-default
  24.       type: replication
  25.       properties:
  26.         keys: ["beijing","hangzhou"]
  27.         selector: ["hello-rep"]
  29.   workflow:
  30.     steps:
  31.       - name: deploy-with-rep
  32.         type: deploy
  33.         properties:
  34.           policies: ["comp-to-replicate","target-default","replication-default"]
  1. kubectl get deploy -n default
  2. NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
  3. hello-rep-beijing    1/1     1            1           5s
  4. hello-rep-hangzhou   1/1     1            1           5s
  6. kubectl get service -n default
  7. NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
  8. hello-rep-hangzhou   ClusterIP   10.43.23.200   <none>        80/TCP    41s
  9. 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

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.

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: app1
  5. spec:
  6.   components:
  7.     - name: ns1
  8.       type: k8s-objects
  9.       properties:
  10.         objects:
  11.           - apiVersion: v1
  12.             kind: Namespace
  13.             metadata:
  14.               name: example
  15.     - name: cm1
  16.       type: k8s-objects
  17.       properties:
  18.         objects:
  19.           - apiVersion: v1
  20.             kind: ConfigMap
  21.             metadata:
  22.               name: cm1
  23.               namespace: example
  24.             data:
  25.               key: value1
  26.   policies:
  27.     - name: shared-resource
  28.       type: shared-resource
  29.       properties:
  30.         rules:
  31.           - selector:
  32.               resourceTypes: ["Namespace"]
  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: app2
  5. spec:
  6.   components:
  7.     - name: ns2
  8.       type: k8s-objects
  9.       properties:
  10.         objects:
  11.           - apiVersion: v1
  12.             kind: Namespace
  13.             metadata:
  14.               name: example
  15.     - name: cm2
  16.       type: k8s-objects
  17.       properties:
  18.         objects:
  19.           - apiVersion: v1
  20.             kind: ConfigMap
  21.             metadata:
  22.               name: cm2
  23.               namespace: example
  24.             data:
  25.               key: value2
  26.   policies:
  27.     - name: shared-resource
  28.       type: shared-resource
  29.       properties:
  30.         rules:
  31.           - selector:
  32.               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

Topology

Description

Describe the destination where components should be deployed to.

Examples (topology)

  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: basic-topology
  5.   namespace: examples
  6. spec:
  7.   components:
  8.     - name: nginx-basic
  9.       type: webservice
  10.       properties:
  11.         image: nginx
  12.   policies:
  13.     - name: topology-hangzhou-clusters
  14.       type: topology
  15.       properties:
  16.         clusters: ["hangzhou-1", "hangzhou-2"]
  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: label-selector-topology
  5.   namespace: examples
  6. spec:
  7.   components:
  8.     - name: nginx-label-selector
  9.       type: webservice
  10.       properties:
  11.         image: nginx
  12.   policies:
  13.     - name: topology-hangzhou-clusters
  14.       type: topology
  15.       properties:
  16.         clusterLabelSelector:
  17.           region: hangzhou
  1. apiVersion: core.oam.dev/v1beta1
  2. kind: Application
  3. metadata:
  4.   name: local-ns-topology
  5.   namespace: examples
  6. spec:
  7.   components:
  8.     - name: nginx-local-ns
  9.       type: webservice
  10.       properties:
  11.         image: nginx
  12.   policies:
  13.     - name: topology-local
  14.       type: topology
  15.       properties:
  16.         clusters: ["local"]
  17.         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