PropagationPolicy and OverridePolicy - Container Service for Kubernetes

Distributed Cloud Container Platform for Kubernetes (ACK One) Fleet instances propagate applications based on the PropagationPolicy and OverridePolicy. The PropagationPolicy is used to define which resources need to be propagated to which clusters. The OverridePolicy is used to define which configurations to be overridden when resources are propagated to different clusters. This topic describes how to configure the PropagationPolicy and OverridePolicy.

PropagationPolicy

You can define the PropagationPolicy and ClusterPropagationPolicy to propagate multi-cluster applications. The PropagationPolicy and ClusterPropagationPolicy are designed based on the open source project Karmada and are compatible with the ClusterPropagationPolicy and PropagationPolicy APIs of Karmada.

ClusterPropagationPolicy: This policy allows you to propagate cluster-wide resources, including PersistentVolume, StorageClass, Namespace, and CustomResourceDefinition. This policy also allows you to propagate resources in any namespace other than the system reserved namespaces. For more information about the role-based access control (RBAC) permissions required for propagating resources, see RBAC permissions on Fleet instances.
PropagationPolicy: This policy allows you to propagate namespace-wide resources. Only resources in the namespace specified by the policy are propagated.

In the following section, the PropagationPolicy that propagates applications based on static weights is used as an example to describe how to configure a propagation policy.

apiVersion: 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 # The ID of your cluster.
      - cxxxxx # The ID of your cluster.
    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 information.	The value is fixed to `one.alibabacloud.com/v1alpha1`.
kind	Yes	The type of the policy. Valid values: `PropagationPolicy` and `ClusterPropagationPolicy`. `ClusterPropagationPolicy`: This policy allows you to propagate cluster-wide applications and applications in any namespace other than the system reserved namespaces. `PropagationPolicy`: This policy allows you to propagate applications only in the namespace specified by the policy.	PropagationPolicy
namespace	No	If you set the `kind` parameter to `PropagationPolicy`, you must specify an existing namespace.	demo
name	No	The name of the propagation policy.	policy-xxxx
resourceSelectors	No	Select one or more Kubernetes resources that you want to propagate. For more information, see resourceSelector.	`resourceSelectors: -apiVersion: apps/v1 kind: Deployment name: nginx -apiVersion: v1 kind: ConfigMap name: cm`
propagateDeps	No	Specify whether referenced resources are automatically propagated to associated clusters. For example, when a Deployment references a ConfigMap, this parameter determines if the ConfigMap is synchronized to the associated clusters.	true
placement	Yes	`clusterAffinity`: specifies the clusters to which applications are propagated. For more information, see clusterAffinity. `replicaScheduling`: specifies the scheduling policy for resources that create pods, such as Deployments and StatefulSets. For more information, see replicaScheduling.	`placement: clusterAffinity: clusterNames: - ${cluster1-id} - ${cluster2-id} replicaScheduling: replicaSchedulingType: Divided replicaDivisionPreference: Weighted weightPreference: staticWeightList: - targetCluster: clusterNames: - ${cluster1-id} weight: 2 - targetCluster: clusterNames: - ${cluster2-id} weight: 1`
dependentOverrides	No	The `overridePolicy` dependencies. Indicate that resource propagation will wait until all dependent `overridePolicy` configurations have taken effect.	`dependentOverrides: - ${overridePolicy1-name} - ${overridePolicy2-name}`
failover	No	The `failover` behavior after application failure. `decisionConditions：TolerationSeconds`: Specifies the tolerance duration (in seconds) for unhealthy application states before triggering failover. Dafault value: `300` seconds. `purgeMode` `Immediately`: Forcibly evict unhealthy pods and immediately create new applications. `Graciously`: Initiate graceful eviction. Cancel eviction if the application recovers to a healthy state within the grace period. `Never`: Retain unhealthy pods without automated intervention. `gracePeriodSeconds`: If `purgeMode` is set to `Graciously`, `600` seconds is set as the maximum wait time for application recovery before enforced eviction by default.	`failover: application: decisionConditions: tolerationSeconds: 30 purgeMode: Immediately`
preserveResourcesOnDeletion	Yes	Specify whether resources propagated by the policy are retained when the policy is deleted. Default value: `true`.	false

resourceSelector

Parameter	Required	Description	Example
apiVersion	Yes	The version of the resource propagation API.	v1
kind	Yes	The type of resource to propagate.	Deployment
namespace	No	The namespace of the propagated resource. Note If you use the `PropagationPolicy`, set the parameter to the namespace specified by the policy. Otherwise, this parameter does not take effect.	demo
name	No	The name of the propagated resource.	Any name
labelSelector	No	Select the resources to be propagated by using a label selector. `matchLabels`: Specify `key`-`value` pairs. `matchExpressions`: Specify an array. Each element consists of the `key`, `operator`, and `values` parameters.	`labelSelector: matchLabels: region: A az: zone0 matchExpressions: - key: app operator: In values: - nginx`

clusterAffinity

Parameter	Required	Description	Example
clusterNames	No	The IDs of the clusters to which you want to propagate resources.	`clusterNames: - cxxxx - cxxxx`
excludeClusters	No	The IDs of the clusters that you want to exclude.	`excludeClusters: - cxxxx - cxxxx`
labelSelector	No	Select clusters by using a label selector.	`labelSelector: matchLabels: region: A az: zone0 matchExpressions: - key: app operator: In values: - nginx`

replicaScheduling

Parameter	Required	Description	Example
replicaSchedulingType	No	The pod scheduling policy. Valid values: `Duplicated` or `Divided`. `Duplicated`: replicates pods to each cluster. `Divided`: schedules pods based on the weight of each cluster. The total number of pods in all associated clusters is equal to the number of pods specified in `spec` of the application on the Fleet instance.	Duplicated
customSchedulingType	No	The custom scheduling strategy. Only Gang scheduling is supported for workloads.	Gang
replicaDivisionPreference	No	Specify how pods are divided across clusters: `Weighted`: distributes pods proportionally based on predefined weights. `Aggregated`: prioritizes clusters with higher scheduling scores to maximize resource utilization.	weighted
weightPreference	No	Specify whether to use dynamic or static weighting for pod propagation: `dynamicWeight`: `AvailableReplicas` are supported to dynamically adjust pod allocation based on real-time resource availability in associated clusters. `staticWeightList` is an array. Each element consists of the `clusterAffinity` and `weight` parameters. `clusterAffinity`: specifies the clusters to which applications are propagated. For more information, see clusterAffinity. `weight`: specifies the weight of the selected cluster. A larger value indicates that a larger number of pods are scheduled to the cluster.	The following example shows that the weight of Cluster1 is 2 and the weight of Cluster2 is 1. If the total number of pods is three, two pods are scheduled to Cluster1 and one pod is scheduled to Cluster2. `weightPreference: staticWeightList: - targetCluster: clusterNames: - ${cluster1-id} weight: 2 - targetCluster: clusterNames: - ${cluster2-id} weight: 1` The following example uses `dynamicWeight`: `weightPreference: dynamicWeight: AvailableReplicas`

OverridePolicy

During application propagation, some clusters may require different configurations. The OverridePolicy can be used to override resources that are propagated to different clusters. You can define the ClusterOverridePolicy and OverridePolicy. The ClusterOverridePolicy and OverridePolicy are designed based on the open source project Karmada and are compatible with the ClusterOverridePolicy

and OverridePolicy APIs of Karmada.

ClusterOverridePolicy: This policy allows you to override cluster-side resources, including PersistentVolume, StorageClass, Namespace, and CustomResourceDefinition. You can also override resources in any namespace other than the system reserved namespaces.
OverridePolicy: This policy allows you to override namespace-wide resources. You can override only resources in the namespace specified by the policy.

In the following section, the OverridePolicy is used as an example to describe how to configure an override policy.

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

Parameters

Parameter	Required	Description	Example
apiVersion	Yes	The API version information.	The value is fixed to `one.alibabacloud.com/v1alpha1`.
kind	Yes	The type of the override policy. Valid values: `ClusterOverridePolicy` and `OverridePolicy`. `ClusterOverridePolicy`: This policy allows you to override cluster-wide resources and resources in any namespace other than the system reserved namespaces. `OverridePolicy`: This policy allows you to override only resources in the namespace specified by the policy.	OverridePolicy
namespace	No	If you set the `kind` parameter to `OverridePolicy`, you must specify an existing namespace.	demo
name	Yes	The name of the override policy.	Any name
resourceSelectors	Yes	The resourceSelector array. For more information, see resourceSelector.	`resourceSelectors: -apiVersion: apps/v1 kind: Deployment name: nginx -apiVersion: v1 kind: ConfigMap name: cm`
overrideRules	Yes	The ruleWithCluster array. For more information, see ruleWithCluster.	`overrideRules: - targetCluster: clusterNames: - ${cluster1-id} overriders: imageOverrider: - component: Registry operator: add value: registry.cn-hangzhou.aliyuncs.com`

resourceSelector

Parameter	Required	Description	Example
apiVersion	Yes	Set to the `apiVersion` of the resource propagation API.	v1
kind	Yes	The type of resource to propagate.	Deployment
namespace	No	The namespace of the propagated resource. Note If you use the `OverridePolicy`, set the parameter to the namespace specified by the policy. Otherwise, this parameter does not take effect.	demo
name	No	The name of the propagated resource.	Any name
labelSelector	No	Select the resources that you want to propagate by using a label selector.	`labelSelector: matchLabels: region: A az: zone0 matchExpressions: - key: app operator: In values: - nginx`

clusterAffinity

Parameter	Required	Description	Example
clusterNames	No	The IDs of the clusters to which you want to propagate resources.	`clusterNames: - cxxxx - cxxxx`
excludeClusters	No	The IDs of the clusters that you want to exclude.	`excludeClusters: - cxxxx - cxxxx`
labelSelector	No	Select clusters by using a label selector.	`labelSelector: matchLabels: region: A az: zone0 matchExpressions: - key: app operator: In values: - nginx`

ruleWithCluster

Parameter

Required

Description

Example

targetCluster

Yes

Select clusters based on the clusterAffinity parameter. For more information, see resourceSelector.

  clusterAffinity:
      clusterNames:
      -cxxxxx # The ID of your cluster. 
      -cxxxxx # The ID of your cluster.

overriders

Yes

The overriders array, which contains override rules. Valid values: image and plaintext. For more information, see overriders.

plaintext: You can override resources by using the path, value, and operator parameters of JSONPatch.
imageOverrider: You can override images.

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

overriders

Parameter

Required

Description

Example

imageOverrider

The method used to override images.

predicate: Optional. The path of the image that you want to override, such as /spec/template/spec/containers/0/image. If you leave this parameter empty, all images are overridden.
component: Use one of the following methods to override images: Registry, Repository, and Tag. Images are specified in the [registry/]repository[:tag] format.
operator: You can set this parameter to remove, add, or replace.
value: If the operator parameter is set to replace or add, the value is new.

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

plaintext

Override resources by using JSONPatch.

path: the path of the field to be overridden.
value: the value of the field. If the operator parameter is set to remove, leave this parameter empty.
operator: You can set this parameter to remove, add, or replace.

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

References

For more information about how to create an application on a Fleet instance and how to propagate the application to multiple clusters by configuring the PropagationPolicy or OverridePolicy, see Get started with application distribution.