OverridePolicy

Overview

OverridePolicy is one of the core APIs of UCS cluster federation. It is used to define policies that override a group of resources to one or more clusters. It allows flexible configuration adjustment for different cluster environments without changing the core resource configuration.

Override policy features:

• Multi-cluster override: Configuration differences can be overridden to multiple target clusters.
• Multiple overriders: There are image, label, annotation, command, parameter, and common plaintext overriders.
• Flexible selection: You can select a target cluster by label, field, or name.
• Layered policy: There are namespace- and cluster-wide override policies.

Override policy types:

• OverridePolicy: overrides namespace-scoped resources. For details, see What Are Namespace-Scoped Resources?
• ClusterOverridePolicy: overrides cluster-scoped resources (such as PVs, storage classes, and CRDs) and resources in any namespace (excluding system namespaces). For details, see What Are Cluster-Scoped Resources?

OverridePolicy vs. PropagationPolicy:

• PropagationPolicy: defines how resources are propagated to clusters.
• OverridePolicy: defines differentiated configuration after resources are propagated to clusters.

API Specifications

Basic information:

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy  # ClusterOverridePolicy

Application scope:

• OverridePolicy: namespace-wide policy. This policy allows you to override only resources in the namespace specified by this policy.
• ClusterOverridePolicy: cluster-wide policy. This policy allows you to override cluster-wide resources and resources in any namespace.

Resource Format

OverridePolicy YAML template:

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy
metadata:
  name: <string>
  namespace: <string>
spec:
  resourceSelectors: <[]ResourceSelector>
  overrideRules: <[]RuleWithCluster>

ClusterOverridePolicy YAML template:

apiVersion: policy.karmada.io/v1alpha1
kind: ClusterOverridePolicy
metadata:
  name: <string>
spec:
  resourceSelectors: <[]ResourceSelector>
  overrideRules: <[]RuleWithCluster>

Parameter Description

1. metadata: standard Kubernetes resource metadata, which contains the following fields:
   • name: OverridePolicy name
   • namespace: namespace (required only for OverridePolicy)
   • labels: label selector
   • annotations: annotation information

2. spec: OverridePolicy specification, which contains the following fields:
   • resourceSelectors (mandatory): Select the set of resources to which the override policy is applied.

     resourceSelectors:
     - apiVersion: <string>          # API version of the target resource, for example, apps/v1
       kind: <string>                # Target resource type, for example, Deployment
       namespace: <string>           # (Optional) Namespace of the target resource
       name: <string>                # (Optional) Name of the target resource
       labelSelector:                # Label selector
         matchLabels: <map[string]string>
         matchExpressions: <[]LabelSelectorRequirement>

   • overrideRules: defines the override rule array. The recommended override rule definition mode is as follows:

     overrideRules:
     - targetCluster: <ClusterAffinity>    # Target cluster
       overriders: <Overriders>             # Override rules

Overrider Types

1. imageOverrider: modifies the components of a container image.

imageOverrider:
- component: <string>          # Image components: registry, repository, and tag
  operator: <string>           # Operations: add, remove, and replace
  predicate:                   # (Optional) Image filter criteria
    path: <string>             # Image field path, for example, /spec/template/spec/containers/0/image
  value: <string>              # New value (mandatory for the add and replace operations).

2. labelsOverrider: modifies workload labels.

labelsOverrider:
- operator: <string>           # Operations: add, remove, and replace
  value: <map[string]string>   # Label key-value pair

3. annotationsOverrider: modifies workload annotations.

annotationsOverrider:
- operator: <string>           # Operations: add, remove, and replace
  value: <map[string]string>   # Annotation key-value pair

4. commandOverrider: modifies container startup commands.

commandOverrider:
- containerName: <string>      # (Mandatory) Container name
  operator: <string>           # Operations: add and remove
  value: <[]string>            # Command array

5. argsOverrider: modifies container startup parameters.

argsOverrider:
- containerName: <string>      # (Mandatory) Container name
  operator: <string>           # Operations: add and remove
  value: <[]string>            # Parameter array

6. plaintext: modifies any field using JSON Patch.

plaintext:
- operator: <string>           # Operations: add, remove, and replace
  path: <string>               # Target field path, for example, /spec/replicas.
  value: <interface{}>         # New value (empty for the remove operation.)

Cluster Selection Modes

ClusterAffinity structure

clusterNames: <[]string>       # Cluster name list
exclude: <[]string>            # List of excluded clusters
fieldSelector:                 # Field selector
  matchExpressions: <[]LabelSelectorRequirement>
labelSelector:                 # Label selector
  matchLabels: <map[string]string>
  matchExpressions: <[]LabelSelectorRequirement>

Selection modes

1. By cluster name

targetCluster:
  clusterNames:
  - "cluster-1"
  - "cluster-2"
  exclude:
  - "cluster-3"

2. Field selector

targetCluster:
  fieldSelector:
    matchExpressions:
    - key: provider
      operator: In
      values: ["aws", "azure"]
    - key: region
      operator: NotIn
      values: ["cn-north-1"]

3. Label selector

targetCluster:
  labelSelector:
    matchLabels:
      environment: production
    matchExpressions:
    - key: tier
      operator: In
      values: ["frontend", "backend"]

Application Sequence

The overriders are applied in the following sequence:

1. ImageOverrider (applied first)
2. CommandOverrider
3. ArgsOverrider
4. LabelsOverrider
5. AnnotationsOverrider
6. Plaintext (applied at last)
   

   This sequence ensures that more specific overriders (such as image overrider) are applied before general overriders (such as plaintext overrider).

Examples

Example 1: basic image override

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy
metadata:
  name: image-override-demo
  namespace: demo
spec:
  resourceSelectors:
  - apiVersion: apps/v1
    kind: Deployment
    namespace: demo
    name: nginx-app
  overrideRules:
  - targetCluster:
      clusterNames:
      - "cluster-beijing"
      - "cluster-shanghai"
    overriders:
      imageOverrider:
      - component: registry
        operator: replace
        value: "registry.internal.com"
      - component: tag
        operator: replace
        value: "v1.0.0"

Example 2: multi-cluster differentiated configuration

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy
metadata:
  name: multi-cluster-config
  namespace: production
spec:
  resourceSelectors:
  - apiVersion: apps/v1
    kind: Deployment
    namespace: production
    labelSelector:
      matchLabels:
        app: web-service
  overrideRules:
  # Production cluster configuration
  - targetCluster:
      labelSelector:
        matchLabels:
          environment: production
    overriders:
      imageOverrider:
      - component: registry
        operator: replace
        value: "registry.internal.com"
      plaintext:
      - operator: replace
        path: "/spec/replicas"
        value: 10
      labelsOverrider:
      - operator: add
        value:
          monitoring: "enabled"
          version: "stable"

  # Test cluster configuration
  - targetCluster:
      labelSelector:
        matchLabels:
          environment: testing
    overriders:
      plaintext:
      - operator: replace
        path: "/spec/replicas"
        value: 2
      labelsOverrider:
      - operator: add
        value:
          monitoring: "disabled"
          version: "beta"

Example 3: container command override

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy
metadata:
  name: command-override
  namespace: backend
spec:
  resourceSelectors:
  - apiVersion: apps/v1
    kind: StatefulSet
    namespace: backend
    name: redis-cluster
  overrideRules:
  - targetCluster:
      clusterNames:
      - "high-perf-cluster"
    overriders:
      commandOverrider:
      - containerName: "redis"
        operator: replace
        value: ["redis-server", "--maxmemory", "4gb", "--maxmemory-policy", "allkeys-lru"]
      argsOverrider:
      - containerName: "redis"
        operator: add
        value: ["--appendonly", "yes"]

Example 4: label and annotation overrides

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy
metadata:
  name: labels-annotations-demo
  namespace: app
spec:
  resourceSelectors:
  - apiVersion: apps/v1
    kind: Deployment
    namespace: app
  overrideRules:
  - targetCluster:
      fieldSelector:
        matchExpressions:
        - key: region
          operator: In
          values: ["us-west", "us-east"]
    overriders:
      labelsOverrider:
      - operator: add
        value:
          deployment-zone: "us"
          cost-optimized: "true"
      - operator: replace
        value:
          team: "us-team"
      annotationsOverrider:
      - operator: add
        value:
          deployment.kubernetes.io/revision: "1"
          prometheus.io/scrape: "true"
          prometheus.io/port: "8080"

Example 5: complex plaintext override

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy
metadata:
  name: complex-plaintext-override
  namespace: infrastructure
spec:
  resourceSelectors:
  - apiVersion: apps/v1
    kind: DaemonSet
    namespace: kube-system
    name: "node-exporter"
  overrideRules:
  - targetCluster:
      labelSelector:
        matchLabels:
          node-type: "worker"
    overriders:
      plaintext:
      # Change the number of replicas.
      - operator: replace
        path: "/spec/updateStrategy/type"
        value: "RollingUpdate"
      # Modify environment variables.
      - operator: add
        path: "/spec/template/spec/containers/0/env"
        value:
        - name: "NODE_NAME"
          valueFrom:
            fieldRef:
              fieldPath: "spec.nodeName"
      # Modify the resource configuration.
      - operator: replace
        path: "/spec/template/spec/containers/0/resources"
        value:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"