PropagationPolicy & OverridePolicy Overview for Multi-Cluster Workloads - ACK One

ACK One uses propagation policies and override policies to distribute applications across a fleet. A propagation policy defines which resources are distributed to which clusters. An override policy applies cluster-specific configuration overrides to those resources.

Propagation policies

A propagation policy selects Kubernetes resources and distributes them to one or more member clusters. Define a PropagationPolicy or ClusterPropagationPolicy — both are based on the open source Karmada project and are compatible with the Karmada API.

`PropagationPolicy`: Distributes namespace-level resources. Applies only within the namespace where the policy is defined.
`ClusterPropagationPolicy`: Distributes cluster-scoped resources (PersistentVolume, StorageClass, Namespace, CustomResourceDefinition) and namespace-level resources in any namespace except system namespaces. Role-Based Access Control (RBAC) for resource distribution is governed by multi-cluster fleet RBAC permissions.

The following example distributes a Deployment and a ConfigMap to two clusters with static replica weights:

apiVersion: policy.one.alibabacloud.com/v1alpha1
kind: PropagationPolicy
metadata:
  name: web-demo
  namespace: demo
spec:
  resourceSelectors:
  - apiVersion: apps/v1
    kind: Deployment
    name: web-demo
  - apiVersion: v1
    kind: ConfigMap
    name: cm-demo
  - apiVersion: apps/v1
    kind: Deployment
    labelSelector:
      matchExpressions:
      - key: app
        operator: In
        values:
        - xxxx
  preserveResourcesOnDeletion: true
  placement:
    clusterAffinity:
      clusterNames:
      - cxxxxx # Your cluster ID.
      - cxxxxx # Your cluster ID.
    replicaScheduling:
      replicaSchedulingType: Divided
      replicaDivisionPreference: Weighted
      weightPreference:
        staticWeightList:
        - targetCluster:
            clusterNames:
            - cxxxxx
          weight: 2
        - targetCluster:
            clusterNames:
            - cxxxxxx
          weight: 1

Parameters

Parameter	Required	Description	Example
`apiVersion`	Yes	The API version.	`policy.one.alibabacloud.com/v1alpha1`
`kind`	Yes	The policy scope. `PropagationPolicy` distributes resources within its own namespace. `ClusterPropagationPolicy` distributes cluster-scoped resources and resources in any non-system namespace.	`PropagationPolicy`
`namespace`	No	Required when `kind` is `PropagationPolicy`. Specify an existing namespace.	`demo`
`name`	No	The name of the propagation policy.	`policy-xxxx`
`resourceSelectors`	No	Selects the Kubernetes resources to distribute. If omitted, no resources are selected. See resourceSelector parameters.	—
`propagateDeps`	No	Specifies whether to automatically distribute resources that the selected workload depends on (for example, a ConfigMap referenced by a Deployment).	`true`
`placement`	Yes	Specifies target clusters and replica scheduling. Contains `clusterAffinity` and `replicaScheduling`. See clusterAffinity parameters and replicaScheduling parameters.	—
`dependentOverrides`	No	Lists `OverridePolicy` objects that must be applied before resources are distributed.	`- overridePolicy1`
`failover`	No	Controls behavior when an application becomes unhealthy. See Failover configuration.	—
`preserveResourcesOnDeletion`	Yes	Specifies whether to keep distributed resources in member clusters after the policy is deleted. Default: `true`.	`false`

resourceSelector parameters

Parameter	Required	Description	Example
`apiVersion`	Yes	The API version of the resource to distribute.	`v1`
`kind`	Yes	The resource type.	`Deployment`
`namespace`	No	The namespace of the resource. When using `PropagationPolicy`, this must match the namespace where the policy is defined — other values have no effect.	`demo`
`name`	No	The name of the resource.	`web-demo`
`labelSelector`	No	Selects resources by labels. Supports `matchLabels` (key-value pairs) and `matchExpressions` (expressions with `key`, `operator`, and `values`). If omitted, all resources of the specified `kind` in the namespace are selected.	—

clusterAffinity parameters

Specify target clusters using any combination of the following fields:

By cluster ID

clusterAffinity:
  clusterNames:
  - cxxxx
  - cxxxx

By label selector

clusterAffinity:
  labelSelector:
    matchLabels:
      region: A
      az: zone0
    matchExpressions:
    - key: app
      operator: In
      values:
      - nginx

By exclusion

clusterAffinity:
  excludeClusters:
  - cxxxx
  - cxxxx

Parameter	Required	Description
`clusterNames`	No	Cluster IDs to include.
`excludeClusters`	No	Cluster IDs to exclude.
`labelSelector`	No	Selects clusters by label.

replicaScheduling parameters

Parameter	Required	Description	Example
`replicaSchedulingType`	No	How replicas are distributed across clusters. `Duplicated` runs the full replica count on each cluster. `Divided` splits replicas across clusters so the total matches the count specified in the workload spec.	`Divided`
`customSchedulingType`	No	Custom scheduling policy. Currently only `Gang` scheduling is supported, for job workloads.	`Gang`
`replicaDivisionPreference`	No	Used when `replicaSchedulingType` is `Divided`. `Weighted` splits replicas by weight. `Aggregated` concentrates replicas on higher-scored clusters.	`Weighted`
`weightPreference`	No	Specifies static or dynamic weights for `Weighted` division. See examples below.	—

Static weight example — with weight: 2 on Cluster1 and weight: 1 on Cluster2, three total replicas are scheduled as two on Cluster1 and one on Cluster2:

weightPreference:
  staticWeightList:
  - targetCluster:
      clusterNames:
      - cxxxxx  # Cluster1 ID
    weight: 2
  - targetCluster:
      clusterNames:
      - cxxxxxx  # Cluster2 ID
    weight: 1

Dynamic weight example — distributes replicas proportionally based on each cluster's available capacity:

weightPreference:
  dynamicWeight: AvailableReplicas

Failover configuration

Configure the failover field to control how ACK One responds when an application becomes unhealthy:

failover:
  application:
    decisionConditions:
      tolerationSeconds: 30
    purgeMode: Immediately

Parameter	Description	Default
`decisionConditions.tolerationSeconds`	How long to wait before treating an unhealthy application as failed.	`300s`
`purgeMode`	What to do with the unhealthy application. `Immediately` evicts it and schedules a replacement. `Graciously` waits for the application to recover; if it recovers within `gracePeriodSeconds`, eviction is cancelled. `Never` leaves the application in place and requires manual intervention.	—
`gracePeriodSeconds`	Maximum wait time for graceful eviction when `purgeMode` is `Graciously`.	`600s`

Override policies

An override policy applies cluster-specific configuration to resources that a propagation policy has already selected for distribution. Define a ClusterOverridePolicy or OverridePolicy — both are based on the open source Karmada project and are compatible with Karmada's ClusterOverridePolicy and OverridePolicy interfaces.

`OverridePolicy`: Overrides namespace-level resources within its own namespace.
`ClusterOverridePolicy`: Overrides cluster-scoped resources (PersistentVolume, StorageClass, Namespace, CustomResourceDefinition) and resources in any non-system namespace.

The following example overrides the replica count and image registry for a Deployment in a specific cluster:

apiVersion: policy.one.alibabacloud.com/v1alpha1
kind: OverridePolicy
metadata:
  name: demo
  namespace: demo
spec:
  resourceSelectors:
    - apiVersion: apps/v1
      kind: Deployment
      name: example
  overrideRules:
    - targetCluster:
        clusterNames:
          - cxxxxx  # Your cluster ID
      overriders:
        plaintext:
          - operator: replace
            path: /spec/replicas
            value: 1
        imageOverrider:
          - component: Registry
            operator: add
            value: registry.cn-hangzhou.aliyuncs.com/xxxx

Main parameters

Parameter	Required	Description	Example
`apiVersion`	Yes	The API version.	`policy.one.alibabacloud.com/v1alpha1`
`kind`	Yes	The policy scope. `OverridePolicy` applies within its own namespace. `ClusterOverridePolicy` applies to cluster-scoped resources and resources in any non-system namespace.	`OverridePolicy`
`namespace`	No	Required when `kind` is `OverridePolicy`. Specify an existing namespace.	`demo`
`name`	Yes	The name of the override policy.	`demo`
`resourceSelectors`	Yes	Selects the resources to override. See resourceSelector parameters.	—
`overrideRules`	Yes	An array of override rules, each targeting specific clusters and specifying overrides to apply. See overrideRules parameters.	—

resourceSelector parameters

Parameter	Required	Description	Example
`apiVersion`	Yes	The API version of the resource.	`v1`
`kind`	Yes	The resource type.	`Deployment`
`namespace`	No	The namespace of the resource. When using `OverridePolicy`, this must match the policy's namespace.	`demo`
`name`	No	The resource name.	`example`
`labelSelector`	No	Selects resources by label. If omitted, all resources of the specified `kind` in the namespace are selected.	—

overrideRules parameters

Each entry in overrideRules contains a targetCluster and an overriders block:

Parameter	Required	Description
`targetCluster`	Yes	Specifies which clusters the override applies to, using the same `clusterAffinity` structure as propagation policies. See clusterAffinity parameters.
`overriders`	Yes	Defines what to override. Supports `imageOverrider` and `plaintext`. When both are specified in the same rule, `imageOverrider` is applied first, then `plaintext`.

overriders parameters

imageOverrider — modifies the image registry, repository, or tag:

Parameter	Required	Description
`predicate`	No	The path to the specific image field to modify (for example, `/spec/template/spec/containers/0/image`). If omitted, all images in the resource are modified.
`component`	Yes	The image component to modify. Valid values: `Registry`, `Repository`, `Tag`. The image format is `[registry/]repository[:tag]`.
`operator`	Yes	The operation. Valid values: `add`, `replace`, `remove`.
`value`	Conditional	The new value. Required when `operator` is `add` or `replace`.

Example — prepend a registry to all container images:

imageOverrider:
  - component: Registry
    operator: add
    value: registry.cn-hangzhou.aliyuncs.com

Result: an image originally specified as nginx:latest becomes registry.cn-hangzhou.aliyuncs.com/nginx:latest.

plaintext — modifies any resource field using a JSON Patch (RFC 6902):

Parameter	Required	Description
`path`	Yes	The JSON Patch path to the target field (for example, `/spec/replicas`).
`value`	Conditional	The new value. Required when `operator` is `add` or `replace`. Omit when `operator` is `remove`.
`operator`	Yes	The operation. Valid values: `add`, `replace`, `remove`.

Example — set replica count to 1 in a specific cluster:

plaintext:
  - operator: replace
    path: /spec/replicas
    value: 1

Result: the Deployment's spec.replicas field is changed from its original value to 1 in the target cluster.

What's next

For an end-to-end walkthrough of creating an application in a fleet instance and configuring propagation and override policies for multi-cluster distribution, see Application distribution quick start.