diff --git a/docs/proposals/20210526-cluster-class-and-managed-topologies.md b/docs/proposals/20210526-cluster-class-and-managed-topologies.md index 1ea7188ef8e5..be2992e3c3d0 100644 --- a/docs/proposals/20210526-cluster-class-and-managed-topologies.md +++ b/docs/proposals/20210526-cluster-class-and-managed-topologies.md @@ -25,48 +25,43 @@ status: provisional - [ClusterClass and Managed Topologies](#clusterclass-and-managed-topologies) - [Table of Contents](#table-of-contents) - [Glossary](#glossary) - - [ClusterClass](#clusterclass) - - [Topology](#topology) - - [Worker class](#workerclass) + - [ClusterClass](#clusterclass) + - [Topology](#topology) - [Summary](#summary) - [Motivation](#motivation) - - [Goals](#goals) - - [Prospective future Work](#prospective-future-work) + - [Goals](#goals) + - [Prospective future Work](#prospective-future-work) - [Proposal](#proposal) - - [User Stories](#user-stories) - - [Story 1 - Use ClusterClass to easily stamp clusters](#story-1---use-clusterclass-to-easily-stamp-clusters) - - [Story 2 - Easier UX for kubernetes version upgrades](#story-2---easier-ux-for-kubernetes-version-upgrades) - - [Story 3 - Easier UX for scaling workers nodes](#story-3---easier-ux-for-scaling-workers-nodes) - - [Story 4 - Ability to customize individual clusters](#story-4---use-clusterclass-to-easily-modify-clusters-in-bulk) - - [Story 5 - Provide powerful and flexible options to define ClusterClass customizations](#story-5---ability-to-define-clusterclass-customizations) - - [Story 6 - Ability to customize individual Clusters via variables](#story-6---ability-to-customize-individual-clusters-via-variables) - - [Story 7 - Ability to mutate variables](#story-7---ability-to-mutate-variables) - - - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) - - [New API types](#new-api-types) - - [ClusterClass](#clusterclass-1) - - [Modification to existing API Types](#modification-to-existing-api-types) - - [Cluster](#cluster) - - [Builtin variables](#builtin-variables) - - [Validations](#validations) - - [ClusterClass](#clusterclass-2) - - [Cluster](#cluster-1) - - [ClusterClass compatibility](#clusterclass-compatibility) - - [Basic behaviors](#basic-behaviors) - - [Create a new Cluster using ClusterClass object](#create-a-new-cluster-using-clusterclass-object) - - [Update an existing Cluster using ClusterClass](#update-an-existing-cluster-using-clusterclass) - - [Behavior with patches](#behavior-with-patches) - - [Create a new ClusterClass with patches](#create-a-new-clusterclass-with-patches) - - [Create a new Cluster with patches](#create-a-new-cluster-with-patches) - - [Provider implementation](#provider-implementation) - - [Conventions for template types implementation](#conventions-for-template-types-implementation) - - [Notes on template <-> object reconciliation](#notes-on-template---object-reconciliation) - - [Risks and Mitigations](#risks-and-mitigations) + - [User Stories](#user-stories) + - [Story 1 - Use ClusterClass to easily stamp Clusters](#story-1---use-clusterclass-to-easily-stamp-clusters) + - [Story 2 - Easier UX for Kubernetes version upgrades](#story-2---easier-ux-for-kubernetes-version-upgrades) + - [Story 3 - Easier UX for scaling workers nodes](#story-3---easier-ux-for-scaling-workers-nodes) + - [Story 4 - Use ClusterClass to easily modify Clusters in bulk](#story-4---use-clusterclass-to-easily-modify-clusters-in-bulk) + - [Story 5 - Ability to define ClusterClass customizations](#story-5---ability-to-define-clusterclass-customizations) + - [Story 6 - Ability to customize individual Clusters via variables](#story-6---ability-to-customize-individual-clusters-via-variables) + - [Story 7 - Ability to mutate variables](#story-7---ability-to-mutate-variables) + - [Story 8 - Easy UX for MachineHealthChecks](#story-8---easy-ux-for-machinehealthchecks) + - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) + - [New API types](#new-api-types) + - [ClusterClass](#clusterclass-1) + - [Modification to existing API Types](#modification-to-existing-api-types) + - [Cluster](#cluster) + - [Validation and Defailting](#validation-and-defailting) + - [Basic behaviors](#basic-behaviors) + - [Create a new Cluster using ClusterClass object](#create-a-new-cluster-using-clusterclass-object) + - [Update an existing Cluster using ClusterClass](#update-an-existing-cluster-using-clusterclass) + - [Behavior with patches](#behavior-with-patches) + - [Create a new ClusterClass with patches](#create-a-new-clusterclass-with-patches) + - [Create a new Cluster with patches](#create-a-new-cluster-with-patches) + - [Provider implementation](#provider-implementation) + - [Conventions for template types implementation](#conventions-for-template-types-implementation) + - [Notes on template \<-\> object reconciliation](#notes-on-template---object-reconciliation) + - [Risks and Mitigations](#risks-and-mitigations) - [Alternatives](#alternatives) - [Upgrade Strategy](#upgrade-strategy) - [Additional Details](#additional-details) - - [Test Plan [optional]](#test-plan-optional) - - [Graduation Criteria [optional]](#graduation-criteria-optional) + - [Test Plan \[optional\]](#test-plan-optional) + - [Graduation Criteria \[optional\]](#graduation-criteria-optional) - [Implementation History](#implementation-history) ## Glossary @@ -215,8 +210,7 @@ be found in [writing a ClusterClass](https://cluster-api.sigs.k8s.io/tasks/exper **ClusterClass variable definitions** -Each variable will be defined by providing an Open API schema using a type inspired from the [Open API schema](https://github.com/kubernetes/apiextensions-apiserver/blob/master/pkg/apis/apiextensions/types_jsonschema.go) -which is embedded in Kubernetes CRDs definition. +Each variable can be defined by providing its own OpenAPI schema definition. The OpenAPI schema used is inspired from the [schema](https://github.com/kubernetes/apiextensions-apiserver/blob/master/pkg/apis/apiextensions/types_jsonschema.go) used in Custom Resource Definitions in Kubernetes. To keep the implementation as easy and user-friendly as possible variable definition in ClusterClass is restricted to: - Basic types: boolean, integer, number, string @@ -263,8 +257,8 @@ More info in [writing a ClusterClass](https://cluster-api.sigs.k8s.io/tasks/expe #### Validation and Defailting -Both the new field in the Cluster CRD and the new ClusterClass CRD type will be validated according to what specified in the -API definitions; additionally please consider that +Both the new field in the Cluster CRD and the new ClusterClass CRD type will be validated according to what is specified in the +API definitions; additionally please consider the following: **ClusterClass** @@ -281,10 +275,10 @@ is not yet implemented as of today. **Cluster** -- Variables are defaulted according to what defined in the corresponding ClusterClass definition; After dafaulting happens, values +- Variables are defaulted according to what defined in the corresponding ClusterClass definition; After dafaulting is applied, values can be changed by the user only (they are not affected by change of the default value in the ClusterClass). - All required variables must exist and match the schema defined in the corresponding variable definition in the ClusterClass. -- When changing the cluster class in use by a cluster, the validation ensures that the operation cannot change apiGroup or Kind +- When changing the cluster class in use by a cluster, the validation ensures that the new ClusterClass is compatible, i.e. the operation cannot change apiGroup or Kind for the referenced templates (with the only exception of the bootstrap templates). #### Basic behaviors @@ -292,7 +286,7 @@ is not yet implemented as of today. This section lists out the basic behavior for Cluster objects using a ClusterClass in case of creates and updates. The following examples intentionally use resources without patches and variables to focus on the simplest case. -more info in [writing a ClusterClass](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/write-clusterclass.html) +More info in [writing a ClusterClass](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/write-clusterclass.html) as well as in - [changing a ClusterClass](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/change-clusterclass.html) - [operating a managed Cluster](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/operate-cluster.html) @@ -507,7 +501,7 @@ like e.g. a different HTTP proxy configuration, a different image to be used for During reconciliation the cluster topology controller uses the templates referenced in the ClusterClass. However, in order to compute the desired state of the InfrastructureCluster, ControlPlane, BootstrapTemplates and -InfrastructureMachineTemplates also patches will be considered. +InfrastructureMachineTemplates the patches will be considered. Most specifically patches are applied in the order in which they are defined in the ClusterClass; the resulting templates are the used as a input for creating or updating the Cluster as described in previous paragraphs. @@ -574,8 +568,8 @@ topology when necessary. More specifically, the topology controller uses [Server Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/) to write/patch topology owned objects; using SSA allows other controllers to co-author the generated objects. -However, this requires providers to pay attention on lists that are expected to contain values from ClusterClass/Variables, -and thus managed by the CAPI topology controller, and values from the infrastructure provider itself, like e.g. adding info for subnets in CAPA. +However, this requires providers to pay attention on lists that are co-owned by multiple controller, for example lists that are expected to contain values from ClusterClass/Variables, +and thus managed by the CAPI topology controller, and values from the infrastructure provider itself, like e.g. subnets in CAPA. In this cases for ServerSideApply to work properly it is required to ensure the proper annotation exists on the CRD types definitions, like +MapType or +MapTypeKey.