kubernetes-sigs / kubernetes-sigs/cluster-inventory-api
Adoption Guide for ClusterProfile API
- Dominant language
- Go
- Stars
- 96
- Forks
- 23
- Avg merge
- 4h 56m
- Merged PRs (30d)
- 1
Description
## Adoption Guide for ClusterProfile API
The ClusterProfile API now has real implementations,OCM and GKE Fleet as cluster managers, and Kueue, Knative Operator, multicluster-runtime, and Argo CD (in review) as consumers. The implementations page (https://multicluster.sigs.k8s.io/implementations/cluster-inventory-api-implementations/) does a good job listing what exists, but there's no step-by-step guide for someone new who wants to either produce or consume ClusterProfile objects. It would be great to have something like MCS-API's getting-started material but tailored for the two roles people play with this API.
### For cluster manager implementers (producers)
The guide should walk through: installing the CRDs from `config/crd/bases/`, importing the Go module (`sigs.k8s.io/cluster-inventory-api`) and using the generated clientset, creating a ClusterProfile with the required `spec.clusterManager.name` field, choosing a namespace strategy, and applying the recommended `x-k8s.io/cluster-manager` label. Then it should cover maintaining the status — updating `status.conditions` (especially `ControlPlaneHealthy`), populating `status.version.kubernetes`, publishing `status.properties` with well-known KEP-2149 property names, and configuring `status.accessProviders` with server URL, CA data, and exec plugin extensions per KEP-5339. It would be worth including a section on setting up the credential plugin mechanism with the built-in plugins (`secretreader`, `kubeconfig-secretreader`) and how to write a provider config file. The `examples/controller-example/` in this repo is a good starting point to reference, along with OCM's reconciler as a real-world example.
### For ClusterProfile consumers
The guide should cover: listing and watching ClusterProfile objects across namespaces, filtering by labels, reading properties for scheduling decisions, and most importantly connecting to member clusters using `pkg/access.BuildConfigFromCP()` with a provider config file. It would help to show integration patterns for the common consumer types — controller-runtime based controllers (reference: multicluster-runtime), batch schedulers (reference: Kueue MultiKueue), GitOps tools (reference: Argo CD proposal in argoproj/argo-cd#24509), and serverless platforms (reference: Knative Operator). A minimal end-to-end code example that discovers clusters and connects to one would go a long way.
### Migration notes
It would also be useful to include brief migration notes for projects coming from proprietary cluster registry APIs — what the field mapping looks like from OCM's ManagedCluster, Karmada's Cluster, or Fleet's MemberCluster. Nothing exhaustive, just enough to help someone figure out the mapping.
### Where this should live
In the `docs` folder alongside the PlacementDecision adoption guide.
### References
- ClusterProfile types: `apis/v1alpha1/clusterprofile_types.go`
- Access library: `pkg/access/`
- Controller example: `examples/controller-example/`
- KEP-4322: https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/4322-cluster-inventory/README.md
- KEP-5339: https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/5339-clusterprofile-credentials-plugin/README.md
- Current implementations page: https://multicluster.sigs.k8s.io/implementations/cluster-inventory-api-implementations/
- MCS implementations page (for reference on structure): https://multicluster.sigs.k8s.io/implementations/mcs-implementations/
/sig multicluster
Contributor guide
Assessment
This issue has not been assessed yet.