Adoption Guide for PlacementDecision API
The PlacementDecision API (KEP-5313) gives schedulers a standard way to publish which clusters were chosen for a workload, and gives consumers a single API to watch instead of integrating with each scheduler individually. OCM is tracking support for producing these objects (open-cluster-management-io/ocm#1373), but there's currently no guide explaining how to actually use the API from either side. It would be helpful to have a practical adoption guide covering both producer and consumer roles.
For scheduler implementers (producers)
The guide should walk through: installing the CRDs, importing the generated clientset, creating a PlacementDecision with decisions[] entries that reference ClusterProfile objects via clusterProfileRef, setting schedulerName to identify the producing scheduler, and optionally populating decisions[].reason for audit/debug purposes. An important section would be the multi-slice pattern, when a placement selects more than 100 clusters, you need to split across multiple PlacementDecision objects using the multicluster.x-k8s.io/decision-key label (same value on all slices), multicluster.x-k8s.io/decision-index for ordering, and optionally multicluster.x-k8s.io/placement-key to link back to the originating workload. This is essentially the same pattern as EndpointSlice and is worth explaining with examples. The guide should also cover lifecycle management — updating decisions when scheduling changes, cleaning up when the originating placement request is deleted, and using ownerReferences appropriately.
For workload consumers
The guide should cover: watching PlacementDecision objects in relevant namespaces, filtering by schedulerName or label selectors, correlating multi-slice decisions by decision-key and decision-index, and resolving each clusterProfileRef to a ClusterProfile and then to a live cluster connection via pkg/access.BuildConfigFromCP(). It should discuss how to react to decision changes — diffing old vs new decisions to figure out which clusters were added or removed, and what to do about workload migration. Some integration pattern examples would be useful: GitOps tools watching decisions and syncing apps to decided clusters, batch systems dispatching jobs, operators deploying components. A minimal consumer code example that watches a PlacementDecision and deploys something simple (like a ConfigMap) to each decided cluster would make things concrete.
End-to-end walkthrough
It would be really helpful to have a combined walkthrough that ties both APIs together: a cluster manager creates ClusterProfile objects for a few clusters, a scheduler reads the profiles and selects a subset, writes a PlacementDecision referencing the chosen clusters, and then a consumer watches the decision and deploys workloads. This gives people the full picture of how the pieces fit together and is something the repo's existing examples/controller-example/ partially demonstrates for the ClusterProfile side but doesn't cover for PlacementDecision yet.
Where this should live
In the docs folder alongside the ClusterProfile adoption guide.
References
/sig multicluster
Adoption Guide for PlacementDecision API
The PlacementDecision API (KEP-5313) gives schedulers a standard way to publish which clusters were chosen for a workload, and gives consumers a single API to watch instead of integrating with each scheduler individually. OCM is tracking support for producing these objects (open-cluster-management-io/ocm#1373), but there's currently no guide explaining how to actually use the API from either side. It would be helpful to have a practical adoption guide covering both producer and consumer roles.
For scheduler implementers (producers)
The guide should walk through: installing the CRDs, importing the generated clientset, creating a PlacementDecision with
decisions[]entries that reference ClusterProfile objects viaclusterProfileRef, settingschedulerNameto identify the producing scheduler, and optionally populatingdecisions[].reasonfor audit/debug purposes. An important section would be the multi-slice pattern, when a placement selects more than 100 clusters, you need to split across multiple PlacementDecision objects using themulticluster.x-k8s.io/decision-keylabel (same value on all slices),multicluster.x-k8s.io/decision-indexfor ordering, and optionallymulticluster.x-k8s.io/placement-keyto link back to the originating workload. This is essentially the same pattern as EndpointSlice and is worth explaining with examples. The guide should also cover lifecycle management — updating decisions when scheduling changes, cleaning up when the originating placement request is deleted, and using ownerReferences appropriately.For workload consumers
The guide should cover: watching PlacementDecision objects in relevant namespaces, filtering by
schedulerNameor label selectors, correlating multi-slice decisions bydecision-keyanddecision-index, and resolving eachclusterProfileRefto a ClusterProfile and then to a live cluster connection viapkg/access.BuildConfigFromCP(). It should discuss how to react to decision changes — diffing old vs new decisions to figure out which clusters were added or removed, and what to do about workload migration. Some integration pattern examples would be useful: GitOps tools watching decisions and syncing apps to decided clusters, batch systems dispatching jobs, operators deploying components. A minimal consumer code example that watches a PlacementDecision and deploys something simple (like a ConfigMap) to each decided cluster would make things concrete.End-to-end walkthrough
It would be really helpful to have a combined walkthrough that ties both APIs together: a cluster manager creates ClusterProfile objects for a few clusters, a scheduler reads the profiles and selects a subset, writes a PlacementDecision referencing the chosen clusters, and then a consumer watches the decision and deploys workloads. This gives people the full picture of how the pieces fit together and is something the repo's existing
examples/controller-example/partially demonstrates for the ClusterProfile side but doesn't cover for PlacementDecision yet.Where this should live
In the
docsfolder alongside the ClusterProfile adoption guide.References
apis/v1alpha1/placementdecision_types.gotest/integration/placementdecision_test.goclient/clientset/versioned/typed/apis/v1alpha1//sig multicluster