Improve ClusterClass documentation

[sbueringer]

User Story

As a user and ClusterClass author I would like to have great documentation which makes it easier to adopt and use ClusterClass!

Detailed Description

This issue proposes some changes / extensions of the current ClusterClass documentation.

The documentation should be structured like this:

• For ClusterClass authors:
  • Writing a ClusterClass
  • Changing a ClusterClass
  • Publishing a ClusterClass for clusterctl usage: clusterctl Provider contract
• For Cluster operators:
  • Creating a Cluster: Quick Start guide
  • Operating a Cluster
  • Planning topology rollouts

Some notes about the individual docs (& task list)

• Introduce basic structure (@sbueringer): 📖 ClusterClass: restructure documentation #5954

• Writing a ClusterClass (@sbueringer): 📖 book: add Writing a ClusterClass doc #5997

  • Message: the value of a ClusterClass is linked to its capacity to support many variants of Clusters
    => Let's provide information for strategies how this can be done
  • Basic ClusterClass (simple case including workers)
  • Show basic variability (without patches): topology fields (including MD classes)
  • Note: clusterctl topology plan is a huge help when writing ClusterClasses (link)
  • Some recommendations:
    • don't reuse templates across ClusterClasses
    • naming conventions / best practices: ClusterClass name, template name/prefix, short, consistent, versioning in names (xref change doc)
  • Advanced:
    • MHC
    • Variables and patches:
      • basics
      • advanced:
        • variable templates
        • complex objects
        • optional patches
        • MD variables
      • Tips & tricks
      • Caveats / Limitations (mention Unexpected behavior in "append" to array patch operation #5944)

• Changing a ClusterClass: (@fabriziopandini): 📖 Document how to change a ClusterClass #5978

  • Review the current doc regarding the introduction of managed fields
  • Add advice on when to change ClusterClass in-place vs. creating a new ClusterClass
  • Split user tasks vs. what the reconciler will do
  • Add user task: changing template of a ClusterClass: explain rotation vs. in-place update, recommend rotation
    • rotation is recommended because of: consistency, rollbacks/history are possible, clear rollout behavior

• clusterctl Provider contract (@killianmuldoon)

  • Should be fine, let's just review it again if everything is up-to-date.

• Creating a cluster (@killianmuldoon): 📖 Add note on where to find ClusterClass specific Cluster creation commands #6033

  • Should be fine, let's just review and test it again if everything is up-to-date (based on beta/RC release).

• Operating a Cluster: (@killianmuldoon): 📖 Extend Operating a Managed Cluster doc #6026

  • Some text about single control point (cf. similar text in proposal)
  • Showcase basic operations: changes to topology fields (including MD modifications)
  • Show special case: upgrade (doc already exists, let's just make sure it fits in the new structure of that doc)
  • Show how to rebase (link the Changing a ClusterClass doc)
  • Show changing variables and setting MD variable overrides

• clusterctl topology plan (@ykakarap): 📖 documentation for clusterctl alpha topology plan #6009

  • Add the doc and make it great! (no further brainstorming done atm)
  • Some notes:
    • Set expectations and provide examples
    • Let's mention the limitations, e.g.:
      • defaulting of the ClusterClass templates and defaulting of the managed objects is not considered (and to what differences between the command and reality this can lead for the user)
      • some changes might not be possible in reality like changing immutable KCPTemplate fields
    • Let's mention how some of those limitations can be avoided by the user (e.g., apply ClusterClass and templates and them get them and use that as basis for changes)

General ideas:

• Let's try to provide context for users
• Don't add too much details
• Look at it from a user-perspective
• Add examples when useful

/kind documentation
/area topology

[ykakarap]

I can work on the "clusterctl topology plan" document :)

[fabriziopandini]

I'm taking Changing a ClusterClass given that I'm co-responsible for the previous version of it

[killianmuldoon]

I'll take Operating a Cluster, and I'll review the clusterctl and creating a cluster docs too.

[sbueringer]

I'll take Operating a Cluster, and I'll review the clusterctl and creating a cluster docs too.

Perfect. Thank you!

[fabriziopandini]

/re-open
not all the tasks are completed

[fabriziopandini]

/reopen

[k8s-ci-robot]

@fabriziopandini: Reopened this issue.

In response to this:

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[killianmuldoon]

clusterctl Provider contract looks good to me. The create a clusterclass documentation is a little less clear though. Our top-level ClusterClass page links to the quick start, but in the quick start the clusterclass section is sort of hidden behind a docker infra tab. I think we should add a short guide to creating a Cluster with ClusterClass wdyt?

[fabriziopandini]

I think we should add a short guide to creating a Cluster with ClusterClass wdyt?

I'm ok if we point out that the general quick start sequence worka with ClusterClass if the provider has templates using it (and eventually pointing to clusterctl doc explaining how this works behind the scenes), but long term hopefully all the providers are going to use ClusterClass in the ClusterClass

[sbueringer]

I would really prefer to not have a separate guide for ClusterClass

[killianmuldoon]

I don't mean a separate guide - just a section on the existing quick start would do. Right now we're linking to the quick start but there's nothing obvious about ClusterClass there - ctrl-f doesn't turn up anything except enabling the flag. I think. simple section would be clear enough to get people started.

[sbueringer]

Depending on how the section looks like - sounds fine to me :).

As far as I'm aware all you have to do is enable the feature and then pick a template which uses ClusterClass. If there's a way to make that more obvious, it sounds fine to me in general.

[fabriziopandini]

I'm not opposed to adding a short note on the quick start, but things were designed to make things work seamlessly, no matter if we are using ClusterClass or not.

[killianmuldoon]

The alternative is to remove the link to the quick start from https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/index.html I think. I'll do a PR adding in a note and we'll see what the best path is.

[sbueringer]

Thx everyone, great work!

/close

[k8s-ci-robot]

@sbueringer: Closing this issue.

In response to this:

Thx everyone, great work!

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.