How Does OCM Placement Dynamically Schedule Multi‑Cluster Workloads?

ManagedClusterSet

ManagedClusterSet is a concept from the Kubernetes SIG Multi‑Cluster Service API that groups ManagedCluster objects sharing the same attributes. It enables soft tenant isolation and namespace‑based access control for different teams or applications within Open Cluster Management (OCM).

Placement

Placement is an OCM API that selects a set of ManagedCluster objects from one or more ManagedClusterSet resources. When the Placement is valid, the controller creates a PlacementDecision CR that lists the selected clusters.

PlacementSpec fields

numberOfClusters : Desired number of clusters to select.

clusterSets : Names of the ManagedClusterSets to consider.

predicates : Pre‑selection rules using labelSelector or claimSelector. Each predicate is combined with OR logic.

prioritizerPolicy : Scoring configuration. It contains a mode (e.g., Exact or Additive) and a list of configurations that specify a scoreCoordinate (built‑in or AddOn) and an optional weight. Weights are integers in the range -10 to 10; the default weight is 1.

Scheduling process

The framework gathers candidate clusters from the referenced ManagedClusterSets.

Filter plugins apply the predicates to narrow the candidate list.

Prioritizer plugins score each remaining cluster according to the configured prioritizerPolicy .

The top numberOfClusters clusters (highest total score) are written to a PlacementDecision resource.

Example Placement manifest

apiVersion: cluster.open-cluster-management.io/v1alpha1
kind: Placement
metadata:
  name: placement
  namespace: ns1
spec:
  numberOfClusters: 4
  clusterSets:
    - clusterset1
    - clusterset2
  predicates:
    - requiredClusterSelector:
        labelSelector:
          matchLabels:
            vendor: OpenShift
  prioritizerPolicy:
    mode: Exact
    configurations:
      - scoreCoordinate:
          builtIn: ResourceAllocatableMemory
      - scoreCoordinate:
          builtIn: Steady
        weight: 3
      - scoreCoordinate:
          type: AddOn
          addOn:
            resourceName: default
            scoreName: cpuratio

Built‑in prioritizer plugins

Balance : Balances the number of PlacementDecisions per cluster. Clusters with many decisions receive a low score (‑100), clusters with none receive the highest score (+100).

Steady : Gives the highest score (100) to clusters already selected in a previous decision, encouraging stability.

ResourceAllocatableCPU / ResourceAllocatableMemory : Score is proportional to the amount of allocatable CPU or memory. The cluster with the most resources gets +100, the one with the least gets ‑100.

AddOn : Allows third‑party controllers to provide custom scores via the AddOnPlacementScore API. The custom score is combined with other prioritizers using the configured weight.

Practical scenarios

Scenario 1 – Choose clusters with the most allocatable memory

apiVersion: cluster.open-cluster-management.io/v1alpha1
kind: Placement
metadata:
  name: demo
  namespace: ns1
spec:
  numberOfClusters: 2
  prioritizerPolicy:
    configurations:
      - scoreCoordinate:
          builtIn: ResourceAllocatableMemory

Run oc describe placement demo -n ns1 to view scoring events and the selected clusters.

Scenario 2 – Make scheduling sensitive to memory changes

apiVersion: cluster.open-cluster-management.io/v1alpha1
kind: Placement
metadata:
  name: placement7
  namespace: ns1
spec:
  numberOfClusters: 2
  prioritizerPolicy:
    configurations:
      - scoreCoordinate:
          builtIn: ResourceAllocatableMemory
        weight: 3

Increasing the weight of the memory prioritizer causes the decision to be updated when a new cluster with significantly more memory appears.

Scenario 3 – Keep decisions stable while still preferring memory

apiVersion: cluster.open-cluster-management.io/v1alpha1
kind: Placement
metadata:
  name: demo
  namespace: ns1
spec:
  numberOfClusters: 2
  prioritizerPolicy:
    configurations:
      - scoreCoordinate:
          builtIn: ResourceAllocatableMemory
      - scoreCoordinate:
          builtIn: Steady
        weight: 3

A high weight on Steady retains the original clusters even when a new cluster with more memory is added.

Scoring formula

The total score for a cluster is the sum of each prioritizer's score multiplied by its weight:

totalScore = Σ (weight_i * score_i)

For example, with the default weight 1 for Balance, Steady and a custom AddOn, the formula becomes:

totalScore = 1*balanceScore + 1*steadyScore + 1*addOnScore

Extensibility

OCM v0.6.0 introduced the AddOnPlacementScore API, which lets external controllers publish custom scores (e.g., CPU‑to‑memory ratio) that are consumed by the AddOn prioritizer.

Integration points

ArgoCD can reference a PlacementDecision via an ApplicationSet generator ( clusterDecisionResource) to automatically distribute applications across selected clusters.

KubeVela uses the Placement API as its underlying multi‑cluster scheduler.

Implementation notes

If the spec is empty, all clusters in the referenced ManagedClusterSets become candidates.

PlacementDecision objects are paginated to avoid CRD size limits when many clusters match.

The controller watches ManagedCluster resources; any change in allocatable resources triggers a re‑evaluation according to the configured weights.

Reference URLs (plain text)

ManagedCluster and ManagedClusterSet concepts: https://open-cluster-management.io/concepts/managedcluster/

Placement documentation: https://open-cluster-management.io/concepts/placement/

PlacementSpec source code: https://github.com/open-cluster-management-io/api/blob/main/cluster/v1alpha1/types.go

Extensible scheduling design: https://github.com/open-cluster-management-io/enhancements/blob/main/enhancements/sig-architecture/32-extensiblescheduling/32-extensiblescheduling.md

Open Cluster Management community issues: https://github.com/open-cluster-management-io/community/issues