Override Policy

The OverridePolicy and ClusterOverridePolicy are used to declare override rules for resources when they are propagating to different clusters.

Difference between OverridePolicy and ClusterOverridePolicy

ClusterOverridePolicy represents the cluster-wide policy that overrides a group of resources to one or more clusters while OverridePolicy will apply to resources in the same namespace as the namespace-wide policy. For cluster scoped resources, apply ClusterOverridePolicy by policies name in ascending. For namespaced scoped resources, first apply ClusterOverridePolicy, then apply OverridePolicy.

Resource Selector

ResourceSelectors restricts resource types that this override policy applies to. If you ignore this field it means matching all resources.

Resource Selector required apiVersion field which represents the API version of the target resources and kind which represents the Kind of the target resources. The allowed selectors are as follows:

  • namespace: namespace of the target resource.
  • name: name of the target resource
  • labelSelector: A label query over a set of resources.

Examples

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   resourceSelectors:
  7.     - apiVersion: apps/v1
  8.       kind: Deployment
  9.       name: nginx
  10.       namespace: test
  11.       labelSelector:
  12.         matchLabels:
  13.           app: nginx
  14.   overrideRules:
  15.   #...

It means override rules above will only be applied to Deployment which is named nginx in test namespace and has labels with app: nginx.

Target Cluster

Target Cluster defines restrictions on the override policy that only applies to resources propagated to the matching clusters. If you ignore this field it means matching all clusters.

The allowed selectors are as follows:

  • labelSelector: a filter to select member clusters by labels.
  • fieldSelector: a filter to select member clusters by fields. Currently only three fields of provider(cluster.spec.provider), zone(cluster.spec.zone), and region(cluster.spec.region) are supported.
  • clusterNames: the list of clusters to be selected.
  • exclude: the list of clusters to be ignored.

labelSelector

Examples

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - targetCluster:
  9.         labelSelector:
  10.           matchLabels:
  11.             cluster: member1 
  12.       overriders:
  13.       #...

It means override rules above will only be applied to those resources propagated to clusters which has cluster: member1 label.

fieldSelector

Examples

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - targetCluster:
  9.         fieldSelector:
  10.           matchExpressions:
  11.             - key: region
  12.               operator: In
  13.               values:
  14.                 - cn-north-1
  15.       overriders:
  16.       #...

It means override rules above will only be applied to those resources propagated to clusters which has the spec.region field with values in [cn-north-1].

Examples

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - targetCluster:
  9.         fieldSelector:
  10.           matchExpressions:
  11.             - key: provider
  12.               operator: In
  13.               values:
  14.                 - aws
  15.       overriders:
  16.       #...

It means override rules above will only be applied to those resources propagated to clusters which has the spec.provider field with values in [aws].

Examples

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - targetCluster:
  9.         fieldSelector:
  10.           matchExpressions:
  11.             - key: zone
  12.               operator: In
  13.               values:
  14.                 - us
  15.       overriders:
  16.       #...

It means override rules above will only be applied to those resources propagated to clusters which has the spec.zone field with values in [us].

clusterNames

Examples

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - targetCluster:
  9.         clusterNames:
  10.           - member1
  11.       overriders:
  12.       #...

It means override rules above will only be applied to those resources propagated to clusters whose clusterNames are member1.

exclude

Examples

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - targetCluster:
  9.         exclude:
  10.           - member1
  11.       overriders:
  12.       #...

It means override rules above will only be applied to those resources propagated to clusters whose clusterNames are not member1.

Overriders

Karmada offers various alternatives to declare the override rules:

  • ImageOverrider: overrides images for workloads.
  • CommandOverrider: overrides commands for workloads.
  • ArgsOverrider: overrides args for workloads.
  • LabelsOverrider: overrides labels for workloads.
  • AnnotationsOverrider: overrides annotations for workloads.
  • PlaintextOverrider: a general-purpose tool to override any kind of resources.
  • FieldOverrider: partially override values inside JSON and YAML fields.

ImageOverrider

The ImageOverrider is a refined tool to override images with format [registry/]repository[:tag|@digest](e.g./spec/template/spec/containers/0/image) for workloads such as Deployment.

The allowed operations are as follows:

  • add: appends the registry, repository or tag/digest to the image from containers.
  • remove: removes the registry, repository or tag/digest from the image from containers.
  • replace: replaces the registry, repository or tag/digest of the image from containers.

Examples

Suppose we create a deployment named myapp.

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: myapp
  5.   #...
  6. spec:
  7.   template:
  8.     spec:
  9.       containers:
  10.         - image: myapp:1.0.0
  11.           name: myapp

Example 1: Add the registry when workloads are propagating to specific clusters.

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         imageOverrider:
  10.           - component: Registry
  11.             operator: add
  12.             value: test-repo

It means add a registrytest-repo to the image of myapp.

After the policy is applied for myapp, the image will be:

  1.       containers:
  2.         - image: test-repo/myapp:1.0.0
  3.           name: myapp

Example 2: replace the repository when workloads are propagating to specific clusters.

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         imageOverrider:
  10.           - component: Repository
  11.             operator: replace
  12.             value: myapp2

It means replace the repository from myapp to myapp2.

After the policy is applied for myapp, the image will be:

  1.       containers:
  2.         - image: myapp2:1.0.0
  3.           name: myapp

Example 3: remove the tag when workloads are propagating to specific clusters.

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         imageOverrider:
  10.           - component: Tag
  11.             operator: remove

It means remove the tag of the image myapp.

After the policy is applied for myapp, the image will be:

  1.       containers:
  2.         - image: myapp
  3.           name: myapp

CommandOverrider

The CommandOverrider is a refined tool to override commands(e.g./spec/template/spec/containers/0/command) for workloads, such as Deployment.

The allowed operations are as follows:

  • add: appends one or more flags to the command list.
  • remove: removes one or more flags from the command list.

Examples

Suppose we create a deployment named myapp.

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: myapp
  5.   #...
  6. spec:
  7.   template:
  8.     spec:
  9.       containers:
  10.         - image: myapp
  11.           name: myapp
  12.           command:
  13.             - ./myapp
  14.             - --parameter1=foo
  15.             - --parameter2=bar

Example 1: Add flags when workloads are propagating to specific clusters.

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         commandOverrider:
  10.           - containerName: myapp
  11.             operator: add
  12.             value:
  13.               - --cluster=member1

It means add(appending) a new flag --cluster=member1 to the myapp.

After the policy is applied for myapp, the command list will be:

  1.       containers:
  2.         - image: myapp
  3.           name: myapp
  4.           command:
  5.             - ./myapp
  6.             - --parameter1=foo
  7.             - --parameter2=bar
  8.             - --cluster=member1

Example 2: Remove flags when workloads are propagating to specific clusters.

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         commandOverrider:
  10.           - containerName: myapp
  11.             operator: remove
  12.             value:
  13.               - --parameter1=foo

It means remove the flag --parameter1=foo from the command list.

After the policy is applied for myapp, the command will be:

  1.       containers:
  2.         - image: myapp
  3.           name: myapp
  4.           command:
  5.             - ./myapp
  6.             - --parameter2=bar

ArgsOverrider

The ArgsOverrider is a refined tool to override args(such as /spec/template/spec/containers/0/args) for workloads, such as Deployments.

The allowed operations are as follows:

  • add: appends one or more args to the command list.
  • remove: removes one or more args from the command list.

Note: ArgsOverrider functions the similar way as CommandOverrider. You can refer to the CommandOverrider examples.

LabelsOverrider

The allowed operations are as follows:

  • add: The items in value will be appended to labels.
  • remove: If the item in value matches the item in labels, the former will be deleted. If they do not match, nothing will be done.
  • replace: If the key in value matches the key in the label, the former will be replaced. If they do not match, nothing will be done.

Examples

Suppose we create a deployment named myapp.

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: myapp
  5.   labels: 
  6.     foo: foo
  7.     baz: baz
  8.   #...
  9. spec:
  10.   template:
  11.     spec:
  12.       containers:
  13.         - image: myapp:1.0.0
  14.           name: myapp

Example 1: add/remove/replace labels

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         labelsOverrider:
  10.           - operator: add
  11.             value: 
  12.               bar: bar  # It will be added to labels
  13.           - operator: replace
  14.             value: 
  15.               foo: exist # "foo: foo" will be replaced by "foo: exist"
  16.           - operator: remove
  17.             value: 
  18.               baz: baz   # It will be removed from labels

AnnotationsOverrider

Note: AnnotationsOverrider functions the similar way as LabelsOverrider. You can refer to the LabelsOverrider examples.

FieldOverrider

The FieldOverrider allows users to partially override values inside JSON and YAML fields.

The allowed operations are as follows:

  • add: appends new key-value pairs at the specified sub path.
  • remove: removes specific key-value pairs at the specified sub path.
  • replace: replaces existing values with new values at the specified sub path.

Suppose we have a ConfigMap named myconfigmap that contains some nested YAML data:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: myconfigmap
  5. data:
  6.   config.yaml: |
  7.     app:
  8.       database:
  9.         port: 5432

Example 1: Replace the database port within the ConfigMap using YAML Patch operations.

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         fieldOverrider:
  10.           - fieldPath: /data/config.yaml
  11.             yaml:
  12.               - subPath: /app/database/port
  13.                 operator: replace
  14.                 value: "3306"

After applying this OverridePolicy, the ConfigMap will be updated as follows:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: myconfigmap
  5. data:
  6.   config.yaml: |
  7.     app:
  8.       database:
  9.         port: 3306

PlaintextOverrider

The PlaintextOverrider is a simple overrider that overrides target fields according to path, operator and value, just like kubectl patch.

The allowed operations are as follows:

  • add: appends one or more elements to the resources.
  • remove: removes one or more elements from the resources.
  • replace: replaces one or more elements from the resources.

Suppose we create a configmap named myconfigmap.

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: myconfigmap
  5.   #...
  6. data:
  7.   example: 1

Example 1: replace data of the configmap when resources are propagating to specific clusters.

  1. apiVersion: policy.karmada.io/v1alpha1
  2. kind: OverridePolicy
  3. metadata:
  4.   name: example
  5. spec:
  6.   #...
  7.   overrideRules:
  8.     - overriders:
  9.         plaintext:
  10.           - path: /data/example
  11.             operator: replace
  12.             value: 2

It means replace data of the configmap from example: 1 to the example: 2.

After the policy is applied for myconfigmap, the configmap will be:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: myconfigmap
  5.   #...
  6. data:
  7.   example: 2