Skip to content

ClusterProfile API Overview

This document provides an overview of the ClusterProfile API.

Alt

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.

Terminology

  • Cluster Inventory: A conceptual term referring to a collection of clusters. A cluster inventory may or may not represent a ClusterSet. A cluster inventory is considered a clusterSet if all its member clusters adhere to the namespace sameness 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 SHOULD be owned by exactly one cluster manager (via spec.clusterManager.name and the label x-k8s.io/cluster-manager). A cluster manager may use multiple internal controllers or plugins to update different parts of .status (e.g. version, properties, conditions, accessProviders); when multiple actors write status, use Server-Side Apply with distinct field managers. Controllers select ClusterProfiles by the owning cluster manager name (label or spec).

  • 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

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: ""