ClusterClass gives Cluster API a reusable cluster topology

A declarative cluster definition can still require an operator to coordinate several objects manually. Cluster API's ClusterClass design addresses that problem by collecting reusable templates and letting one Cluster object express the desired topology. The controller then manages the resources needed to realize it.

The 8 October introduction presents ClusterClass and managed topologies as the next step in Cluster API's user experience. It describes implementation work and says the community is working toward delivery of the first version later this year. This is an introduction to that design, not a claim that every provider already offers a completed production capability.

I am particularly interested in this use of Kubernetes' API machinery. The controller model becomes more useful when it represents the operation an administrator intends, including the relationship between a cluster version and its worker pools. Merely storing several related objects does not remove the need to coordinate them.

The existing definition spreads intent across resources

The May design proposal explains the problem. A user creates a control-plane resource, MachineDeployments, and the bootstrap and infrastructure templates they reference. Those objects collectively describe the cluster.

That arrangement provides extensibility. Different infrastructure and control-plane providers can implement their own resource types. The cost is that a single operational change, such as a Kubernetes version upgrade, can require changes in several places.

Creating another cluster with a similar shape repeats much of this configuration. The desired difference might be a replica count or a cluster name, while most of the provider-specific arrangement remains the same. Copying the full collection makes the common policy harder to identify.

ClusterClass separates the reusable arrangement from each cluster's choices. A class groups template references for cluster infrastructure, the control plane, and worker types. A Cluster selects the class and declares its topology.

A class describes the available shapes

The introduction's class example references a KubeadmControlPlaneTemplate and a template for its machines. It also names two worker classes, each with bootstrap and machine infrastructure templates. The class includes a cluster infrastructure template as well.

These are references to provider resources, not replacements for the providers. A reusable class still needs concrete definitions for the infrastructure it will create. The class groups those definitions so each cluster does not need to restate the complete relationship.

A worker class is also distinct from a worker pool instance. The class describes the template combination available for workers. A Cluster can instantiate a named pool using that class and choose the replica count for that pool.

That distinction permits repetition without duplication of the underlying worker definition. Two pools can use the same worker class while retaining their own names and sizes. The proposal describes that relationship explicitly in its topology model.

Managed topology supplies the per-cluster intent

The introduction uses this form for a Cluster referring to an existing class. This shortened example assumes that the named class and all of its referenced templates have already been created in the appropriate namespace.

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: example-cluster
  namespace: bar
spec:
  topology:
    class: my-amazing-cluster-class
    version: v1.21.2
    controlPlane:
      replicas: 3
    workers:
      machineDeployments:
        - class: type1-workers
          name: general-workers
          replicas: 5

The version belongs to the topology, and the worker entry supplies a class, a pool name, and a desired size. It is a smaller expression of the operational intent because the reusable provider configuration lives in the class's template collection.

The proposal describes the controller deriving the infrastructure cluster and control-plane resource from those templates. It also constructs the MachineDeployments for the declared worker entries and supplies their requested version and replica information.

Updating topology then becomes the input for changing the derived resources. The controller compares the requested worker sets with the managed set and adds or removes MachineDeployments as needed. It also propagates the relevant version and replica changes.

That separation also affects how configuration is reviewed. A class change concerns the reusable definition, while a topology change concerns the desired instance. Understanding the relationship requires following the class reference, but the repeated cluster configuration no longer needs to be copied into every instance merely to express a different worker count.

This does not mean a single API write makes every machine change simultaneously. It changes where the desired relationship is declared. Existing lifecycle controllers and providers still carry out the operations required to reach that state.

Provider contracts remain necessary

The proposal identifies requirements for control-plane providers. They need a template type and support for the version fields used by managed topology. Reporting the minimum API-server version through status is also part of the expected control-plane contract.

Other capabilities can vary. The proposal accommodates providers with and without machine infrastructure support, and with and without a configurable replica field. A common Cluster topology therefore operates within the capabilities a provider actually implements.

This is a useful limit on the abstraction. Grouping templates does not make infrastructure-specific details disappear. It allows a platform to choose and package those details while presenting a smaller set of choices to cluster users.

The October introduction also identifies future work on per-cluster customization. Examples include selecting machine images for a version and region or injecting proxy configuration. Those needs demonstrate why a reusable class must eventually handle variation as well as repetition.

The design changes who manages the relationship

My preference is for a controller to own an explicit desired relationship when that relationship can be modeled reliably. A class and topology can express that a particular worker pool uses a particular template family and shares a cluster's requested version. That gives the reconciliation logic a defined source of intent.

The proposal still treats advanced lifecycle work, adoption of existing clusters, and some transformation behavior as areas requiring further design. These are substantive limitations of an initial iteration. They should not be replaced with an assumption that every existing cluster can immediately be converted.

The immediate contribution is a clearer division between reusable cluster configuration and per-cluster topology. Provider templates retain the detailed implementation, while the Cluster object becomes the point where an operator expresses version and worker-pool intent for the controller to manage.