Merge pull request #22 from zhiying-lin/profile-doc

Add clusterProfile docs

Author: k8s-ci-robot

mkdocs.yml

@@ -39,6 +39,7 @@ nav:
       About API Overview: concepts/about-api.md
       Multicluster Services API Overview: concepts/multicluster-services-api.md
       Work API Overview: concepts/work-api.md
+      ClusterProfile API Overview: concepts/cluster-profile-api.md
   - Guides:
     - Index: guides/index.md
     - Implementation Guidelines: guides/guidelines.md

site-src/concepts/cluster-profile-api.md

@@ -0,0 +1,62 @@
+# ClusterProfile API Overview
+
+This document provides an overview of the [ClusterProfile API](https://github.com/kubernetes-sigs/cluster-inventory-api?tab=readme-ov-file#cluster-profile-api).
+
+![Alt](../images/cluster-profile-api.png "ClusterProfile API")
+
+A Cluster Profile is a namespace-level resource and essentially represents an individual member of the Cluster Inventory
+that details properties and status of a cluster. This API proposes a standardized interface that defines how cluster information should be presented
+and interacted with across different platforms and implementations.
+
+You can read more details about the API in the [KEP-4322](https://github.com/kubernetes/enhancements/blob/master/keps/sig-multicluster/4322-cluster-inventory/README.md).
+
+## Terminology
+
+- **Cluster Inventory**: A conceptual term referring to a collection of clusters. A cluster inventory may or may not represent
+a [ClusterSet](../api-types/cluster-set.md). A cluster inventory is considered a clusterSet if all its member clusters adhere to the 
+[namespace sameness](https://github.com/kubernetes/community/blob/master/sig-multicluster/namespace-sameness-position-statement.md) principle.
+
+- **Cluster Manager**: An entity that creates the ClusterProfile API object per member cluster,
+  and keeps their status up-to-date. Each cluster manager MUST be identified with a unique name.  
+  Each ClusterProfile resource SHOULD be managed by only one cluster manager. A cluster manager SHOULD
+  have sufficient permission to access the member cluster to fetch the information so it can update the status
+  of the ClusterProfile API resource.
+
+- **ClusterProfile API Consumer**: the person running the cluster managers
+  or the person developing extensions for cluster managers for the purpose of
+  workload distribution, operation management etc.
+
+## API Example
+
+[CRD definition](https://github.com/kubernetes-sigs/cluster-inventory-api/blob/main/config/crd/bases/multicluster.x-k8s.io_clusterprofiles.yaml)
+
+```yaml
+apiVersion: multicluster.x-k8s.io/v1alpha1
+kind: ClusterProfile
+metadata:
+ name: some-cluster-name
+ namespace: fleet-system
+ labels:
+   x-k8s.io/cluster-manager: some-cluster-manager
+spec:
+  displayName: some-cluster
+  clusterManager:
+    name: some-cluster-manager
+status:
+ version:
+   kubernetes: 1.28.0
+ properties:
+   - name: clusterset.k8s.io
+     value: some-clusterset
+   - name: location
+     value: apac
+ conditions:
+   - type: ControlPlaneHealthy
+     status: True
+     lastTransitionTime: "2023-05-08T07:56:55Z"
+     message: ""
+   - type: Joined
+     status: True
+     lastTransitionTime: "2023-05-08T07:58:55Z"
+     message: ""
+```

site-src/contributing/index.md

@@ -14,6 +14,7 @@ Bug reports should be filed as Github Issues on their respective subproject repo
 * [Open an issue for a bug with the About API][about-api-issues]
 * [Open an issue for a bug with the MCS API][mcs-api-issues]
 * [Open an issue for a bug with the Work API][work-api-issues]
+* [Open an issue for a bug with the ClusterProfile API][clusterprofile-api-issues]
 
 **NOTE**: If you're reporting a bug that applies to a specific implementation of
 a SIG-MC sponsored API and not the API specification itself, please check our
@@ -22,6 +23,7 @@ you can get help with your specific implementation.
 [about-api-issues]: https://github.com/kubernetes-sigs/about-api/issues
 [mcs-api-issues]: https://github.com/kubernetes-sigs/mcs-api/issues
 [work-api-issues]: https://github.com/kubernetes-sigs/work-api/issues
+[clusterprofile-api-issues]: https://github.com/kubernetes-sigs/cluster-inventory-api/issues
 [implementations]: ../guides/index.md
 
 ## Communications

site-src/images/cluster-profile-api.png

@@ -50,17 +50,18 @@ The following charter defines the scope and governance of the [Multicluster Spec
 
 ## Approach
 
-To meet the goals listed above, the SIG-Multicluster team has worked to define three different APIs:
+To meet the goals listed above, the SIG-Multicluster team has worked to define four different APIs:
 
 * [About API][about-api-reference]: allows to uniquely identify clusters within a set of clusters ([clusterset][clusterset-definition])
 * [Multicluster Services API][mc-api-reference]: allows to expose services across clusters which are part of a given [clusterset][clusterset-definition].
 * [Work API][work-api-reference]: allows to define the workloads to be deployed across clusters which are part of a given [clusterset][clusterset-definition].
-* [ClusterInventory API](https://github.com/kubernetes/enhancements/pull/4323/): simplifies the discovery and management of clusters, offering a comprehensive status overview for both applications and human operators. Work in progress.
+* [ClusterProfile API][clusterprofile-reference]: simplifies the discovery and management of clusters, offering a comprehensive status overview for both applications and human operators.
 
 [about-api-reference]: ./concepts/about-api.md
 [mc-api-reference]: ./concepts/multicluster-services-api.md
 [work-api-reference]: ./concepts/work-api.md
 [clusterset-definition]: ./api-types/cluster-set.md
+[clusterprofile-reference]: ./concepts/cluster-profile-api.md
 
 To leave room for implementation, SIG-Multicluster does not focus on the implementation of the mechanisms that rely on those APIs. For example, no reference implementation is provided for a cluster registry or for service discovery itself.