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)

Name	Description	Type	Required	Default
enable	Whether to enable apply-once for the whole application.	bool	false	false
rules	Specify the rules for configuring apply-once policy in resource level.	[]rules	false

rules (apply-once)

Name	Description	Type	Required	Default
selector	Specify how to select the targets of the rule.	selector	false
strategy	Specify the strategy for configuring the resource level configuration drift behaviour.	strategy	true

selector (apply-once)

Name	Description	Type	Required
componentNames	Select resources by component names.	[]string	false
componentTypes	Select resources by component types.	[]string	false
oamTypes	Select resources by oamTypes (COMPONENT or TRAIT).	[]string	false
traitTypes	Select resources by trait types.	[]string	false
resourceTypes	Select resources by resource types (like Deployment).	[]string	false
resourceNames	Select resources by their names.	[]string	false

strategy (apply-once)

Name	Description	Type	Required	Default
affect	When the strategy takes effect,e.g. onUpdate、onStateKeep.	string	false
path	Specify the path of the resource that allow configuration drift.	[]string	true

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)

Name	Description	Type	Required	Default
applicationRevisionLimit	If set, it will override the default revision limit number and customize this number for the current application.	int	false
keepLegacyResource	If is set, outdated versioned resourcetracker will not be recycled automatically, outdated resources will be kept until resourcetracker be deleted manually.	bool	false	false
continueOnFailure	If is set, continue to execute gc when the workflow fails, by default gc will be executed only after the workflow succeeds.	bool	false	false
rules	Specify the list of rules to control gc strategy at resource level, if one resource is controlled by multiple rules, first rule will be used.	[]rules	false

rules (garbage-collect)

Name	Description	Type	Required	Default
selector	Specify how to select the targets of the rule.	selector	true
strategy	Specify the strategy for target resource to recycle.	"onAppUpdate" or "onAppDelete" or "never"	false	onAppUpdate
propagation	Specify the deletion propagation strategy for target resource to delete.	"orphan" or "cascading"	false

selector (garbage-collect)

Name	Description	Type	Required
componentNames	Select resources by component names.	[]string	false
componentTypes	Select resources by component types.	[]string	false
oamTypes	Select resources by oamTypes (COMPONENT or TRAIT).	[]string	false
traitTypes	Select resources by trait types.	[]string	false
resourceTypes	Select resources by resource types (like Deployment).	[]string	false
resourceNames	Select resources by their names.	[]string	false

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)

Name	Description	Type	Required	Default
components	Specify the overridden component configuration.	[]components	true
selector	Specify a list of component names to use, if empty, all components will be selected.	[]string	false

components (override)

Name	Description	Type	Required
name	Specify the name of the patch component, if empty, all components will be merged.	string	false
type	Specify the type of the patch component.	string	false
properties	Specify the properties to override.	map[string]_	false
traits	Specify the traits to override.	[]traits	false

traits (override)

Name	Description	Type	Required	Default
type	Specify the type of the trait to be patched.	string	true
properties	Specify the properties to override.	map[string]_	false
disable	Specify if the trait should be remove, default false.	bool	false	false

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)

Name	Description	Type	Required	Default
rules	Specify the list of rules to control read only strategy at resource level.	[]rules	false

rules (read-only)

Name	Description	Type	Required	Default
selector	Specify how to select the targets of the rule.	selector	true

selector (read-only)

Name	Description	Type	Required
componentNames	Select resources by component names.	[]string	false
componentTypes	Select resources by component types.	[]string	false
oamTypes	Select resources by oamTypes (COMPONENT or TRAIT).	[]string	false
traitTypes	Select resources by trait types.	[]string	false
resourceTypes	Select resources by resource types (like Deployment).	[]string	false
resourceNames	Select resources by their names.	[]string	false

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)

Name	Description	Type	Required	Default
keys	Spicify the keys of replication. Every key coresponds to a replication components.	[]string	true
selector	Specify the components which will be replicated.	[]string	false

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)

Name	Description	Type	Required	Default
rules	Specify the list of rules to control resource update strategy at resource level.	[]rules	false

rules (resource-update)

Name	Description	Type	Required	Default
selector	Specify how to select the targets of the rule.	selector	true
strategy	The update strategy for the target resources.	strategy	true

selector (resource-update)

Name	Description	Type	Required
componentNames	Select resources by component names.	[]string	false
componentTypes	Select resources by component types.	[]string	false
oamTypes	Select resources by oamTypes (COMPONENT or TRAIT).	[]string	false
traitTypes	Select resources by trait types.	[]string	false
resourceTypes	Select resources by resource types (like Deployment).	[]string	false
resourceNames	Select resources by their names.	[]string	false

strategy (resource-update)

Name	Description	Type	Required	Default
op	Specify the op for updating target resources.	"patch" or "replace"	false	patch
recreateFields	Specify which fields would trigger recreation when updated.	[]string	false

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)

Name	Description	Type	Required	Default
rules	Specify the list of rules to control shared-resource strategy at resource level.	[]rules	false

rules (shared-resource)

Name	Description	Type	Required	Default
selector	Specify how to select the targets of the rule.	selector	true

selector (shared-resource)

Name	Description	Type	Required
componentNames	Select resources by component names.	[]string	false
componentTypes	Select resources by component types.	[]string	false
oamTypes	Select resources by oamTypes (COMPONENT or TRAIT).	[]string	false
traitTypes	Select resources by trait types.	[]string	false
resourceTypes	Select resources by resource types (like Deployment).	[]string	false
resourceNames	Select resources by their names.	[]string	false

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)

Name	Description	Type	Required	Default
rules	Specify the list of rules to control take over strategy at resource level.	[]rules	false

rules (take-over)

Name	Description	Type	Required	Default
selector	Specify how to select the targets of the rule.	selector	true

selector (take-over)

Name	Description	Type	Required
componentNames	Select resources by component names.	[]string	false
componentTypes	Select resources by component types.	[]string	false
oamTypes	Select resources by oamTypes (COMPONENT or TRAIT).	[]string	false
traitTypes	Select resources by trait types.	[]string	false
resourceTypes	Select resources by resource types (like Deployment).	[]string	false
resourceNames	Select resources by their names.	[]string	false

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)

Name	Description	Type	Required
clusters	Specify the names of the clusters to select.	[]string	false
clusterLabelSelector	Specify the label selector for clusters.	map[string]string	false
allowEmpty	Ignore empty cluster error.	bool	false
clusterSelector	Deprecated: Use clusterLabelSelector instead.	map[string]string	false
namespace	Specify the target namespace to deploy in the selected clusters, default inherit the original namespace.	string	false

Apply-Once​

Description​

Examples (apply-once)​

Specification (apply-once)​

rules (apply-once)​

selector (apply-once)​

strategy (apply-once)​

Garbage-Collect​

Description​

Examples (garbage-collect)​

Specification (garbage-collect)​

rules (garbage-collect)​

selector (garbage-collect)​

Override​

Description​

Examples (override)​

Specification (override)​

components (override)​

traits (override)​

Read-Only​

Description​

Examples (read-only)​

Specification (read-only)​

rules (read-only)​

selector (read-only)​

Replication​

Description​

Examples (replication)​

Background​

Usage​

Specification (replication)​

Resource-Update​

Description​

Examples (resource-update)​

Specification (resource-update)​

rules (resource-update)​

selector (resource-update)​

strategy (resource-update)​

Shared-Resource​

Description​

Examples (shared-resource)​

Specification (shared-resource)​

rules (shared-resource)​

selector (shared-resource)​

Take-Over​

Description​

Examples (take-over)​

Specification (take-over)​

rules (take-over)​

selector (take-over)​

Topology​

Description​

Examples (topology)​

Specification (topology)​

Apply-Once

Description

Examples (apply-once)

Specification (apply-once)

rules (apply-once)

selector (apply-once)

strategy (apply-once)

Garbage-Collect

Description

Examples (garbage-collect)

Specification (garbage-collect)

rules (garbage-collect)

selector (garbage-collect)

Override

Description

Examples (override)

Specification (override)

components (override)

traits (override)

Read-Only

Description

Examples (read-only)

Specification (read-only)

rules (read-only)

selector (read-only)

Replication

Description

Examples (replication)

Background

Usage

Specification (replication)

Resource-Update

Description

Examples (resource-update)

Specification (resource-update)

rules (resource-update)

selector (resource-update)

strategy (resource-update)

Shared-Resource

Description

Examples (shared-resource)

Specification (shared-resource)

rules (shared-resource)

selector (shared-resource)

Take-Over

Description

Examples (take-over)

Specification (take-over)

rules (take-over)

selector (take-over)

Topology

Description

Examples (topology)

Specification (topology)