diff --git a/docs/book/src/developer/core/controllers/cluster.md b/docs/book/src/developer/core/controllers/cluster.md index 046cd39a6f9c..89d8bfef45a4 100644 --- a/docs/book/src/developer/core/controllers/cluster.md +++ b/docs/book/src/developer/core/controllers/cluster.md @@ -20,7 +20,7 @@ an ControlPlane object, e.g. KubeadmControlPlane, EKSControlPlane etc. Among those rules: - ControlPlane SHOULD report a [controlplane endpoint](../../providers/contracts/control-plane.md#controlplane-endpoint) for the Cluster -- ControlPlane MUST report when Cluster's infrastructure is [fully provisioned](../../providers/contracts/control-plane.md#controlplane-initialization-completed) +- ControlPlane MUST report when Cluster's control plane is [fully provisioned](../../providers/contracts/control-plane.md#controlplane-initialization-completed) - ControlPlane MUST manage a [KubeConfig secret](../../providers/contracts/control-plane.md#cluster-kubeconfig-management) - ControlPlane SHOULD report [conditions](../../providers/contracts/control-plane.md#controlplane-conditions) - ControlPlane SHOULD report [terminal failures](../../providers/contracts/control-plane.md#controlplane-terminal-failures) diff --git a/docs/book/src/developer/providers/contracts/bootstrap-config.md b/docs/book/src/developer/providers/contracts/bootstrap-config.md index f37bb6482861..965b8b5bf6d5 100644 --- a/docs/book/src/developer/providers/contracts/bootstrap-config.md +++ b/docs/book/src/developer/providers/contracts/bootstrap-config.md @@ -287,12 +287,6 @@ the implication of this choice which are described both in the document above an -### BootstrapConfig: pausing - -Providers SHOULD implement the pause behaviour for every object with a reconciliation loop. This is done by checking if `spec.paused` is set on the Cluster object and by checking for the `cluster.x-k8s.io/paused` annotation on the BootstrapConfig object. - -If implementing the pause behavior, providers SHOULD surface the paused status of an object using the Paused condition: `Status.Conditions[Paused]`. - ### BootstrapConfig: terminal failures Each BootstrapConfig SHOULD report when BootstrapConfig's enter in a state that cannot be recovered (terminal failure) by diff --git a/docs/book/src/developer/providers/contracts/control-plane.md b/docs/book/src/developer/providers/contracts/control-plane.md index 7fbb335624c0..0f98b61957ac 100644 --- a/docs/book/src/developer/providers/contracts/control-plane.md +++ b/docs/book/src/developer/providers/contracts/control-plane.md @@ -1,8 +1,8 @@ # Contract rules for ControlPlane -Control plane providers MUST implement an ControlPlane resource. +Control plane providers MUST implement a ControlPlane resource. -The goal of an ControlPlane resource is to instantiate a Kubernetes control plane; a Kubernetes control plane +The goal of a ControlPlane resource is to instantiate a Kubernetes control plane; a Kubernetes control plane at least contains the following components: - Kubernetes API Server - Kubernetes Controller Manager @@ -14,7 +14,7 @@ Optional control plane components are - Cluster DNS (e.g. CoreDNS) - Service proxy (e.g. kube-proxy) -Instead, CNI should be left to user to apply once control plane is instantiated. +Instead, CNI should be left to users to apply once the control plane is instantiated. The ControlPlane resource will be referenced by one of the Cluster API core resources, Cluster. @@ -43,7 +43,7 @@ When developing a provider, you MUST consider any Cluster API behaviour that is as a Cluster API internal implementation detail, and internal implementation details can change at any time. Accordingly, in order to not expose users to the risk that your provider breaks when the Cluster API internal behavior -changes, you MUST NOT rely on any Cluster API internal behaviour when implementing an ControlPlane resource. +changes, you MUST NOT rely on any Cluster API internal behaviour when implementing a ControlPlane resource. Instead, whenever you need something more from the Cluster API contract, you MUST engage the community. @@ -57,28 +57,28 @@ repo or add an item to the agenda in the [Cluster API community meeting](https:/ ## Rules (contract version v1beta1) -| Rule | Mandatory | Note | -|----------------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------| -| [All resources: scope] | Yes | | -| [All resources: `TypeMeta` and `ObjectMeta`field] | Yes | | -| [All resources: `APIVersion` field value] | Yes | | -| [ControlPlane, ControlPlaneList resource definition] | Yes | | -| [ControlPlane: endpoint] | No | Mandatory if control plane endpoint is not provided by other means. | -| [ControlPlane: replicas] | No | Mandatory if control plane as a notion of number of instances; also mandatory for cluster class support. | -| [ControlPlane: version] | No | Mandatory if control plane allows direct management of the Kubernetes version in use; Mandatory for cluster class support. | -| [ControlPlane: machines] | No | Mandatory if control plane instances are represented with a set of Cluster API Machines; also mandatory for cluster class support. | -| [ControlPlane: initialization completed] | Yes | | -| [ControlPlane: conditions] | No | | -| [ControlPlane: terminal failures] | No | | -| [ControlPlaneTemplate, ControlPlaneTemplateList resource definition] | No | Mandatory for ClusterClasses support | -| [Cluster kubeconfig management] | Yes | | -| [Cluster certificate management] | No | | -| [Machine placement] | No | | -| [Metadata propagation] | No | | -| [MinReadySeconds and UpToDate propagation] | No | | -| [Support for running multiple instances] | No | Mandatory for clusterctl CLI support | -| [Clusterctl support] | No | Mandatory for clusterctl CLI support | -| [ControlPlane: pausing] | No | | +| Rule | Mandatory | Note | +|----------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------| +| [All resources: scope] | Yes | | +| [All resources: `TypeMeta` and `ObjectMeta`field] | Yes | | +| [All resources: `APIVersion` field value] | Yes | | +| [ControlPlane, ControlPlaneList resource definition] | Yes | | +| [ControlPlane: endpoint] | No | Mandatory if control plane endpoint is not provided by other means. | +| [ControlPlane: replicas] | No | Mandatory if control plane has a notion of number of instances. | +| [ControlPlane: version] | No | Mandatory if control plane allows direct management of the Kubernetes version in use; Mandatory for cluster class support. | +| [ControlPlane: machines] | No | Mandatory if control plane instances are represented with a set of Cluster API Machines. | +| [ControlPlane: initialization completed] | Yes | | +| [ControlPlane: conditions] | No | | +| [ControlPlane: terminal failures] | No | | +| [ControlPlaneTemplate, ControlPlaneTemplateList resource definition] | No | Mandatory for ClusterClasses support | +| [Cluster kubeconfig management] | Yes | | +| [Cluster certificate management] | No | | +| [Machine placement] | No | | +| [Metadata propagation] | No | | +| [MinReadySeconds and UpToDate propagation] | No | | +| [Support for running multiple instances] | No | Mandatory for clusterctl CLI support | +| [Clusterctl support] | No | Mandatory for clusterctl CLI support | +| [ControlPlane: pausing] | No | | ### All resources: scope @@ -116,7 +116,6 @@ rules: - controlplane.foo.com resources: - foocontrolplanes - - foocontrolplanetemplates verbs: - create - delete @@ -125,10 +124,21 @@ rules: - patch - update - watch +- apiGroups: + - infrastructure.foo.com + resources: + - foocontrolplanetemplates + verbs: + - get + - list + - patch + - update + - watch ``` Note: The write permissions allow the Cluster controller to set owner references and labels on the ControlPlane resources; -when using ClusterClass and managed topologies, also ControlPlaneTemplates are managed directly by Cluster API. +write permissions are not used for general mutations of ControlPlane resources, unless specifically required (e.g. when +using ClusterClass and managed topologies). #### All resources: version @@ -507,7 +517,7 @@ type FooControlPlaneStatus struct { Once `status.initialized` and `status.ready` are set, the Cluster "core" controller will bubbles up those info in Cluster's `status.controlPlaneReady` field and in the `ControlPlaneInitialized` condition. -If defined, also InfraCluster's `spec.controlPlaneEndpoint` will be surfaced on Cluster's corresponding fields at the same time. +If defined, also ControlPlane's `spec.controlPlaneEndpoint` will be surfaced on Cluster's corresponding fields at the same time. -### InfraMachine: pausing - -Providers SHOULD implement the pause behaviour for every object with a reconciliation loop. This is done by checking if `spec.paused` is set on the Cluster object and by checking for the `cluster.x-k8s.io/paused` annotation on the InfraMachine object. - -If implementing the pause behavior, providers SHOULD surface the paused status of an object using the Paused condition: `Status.Conditions[Paused]`. - ### InfraMachineTemplate, InfraMachineTemplateList resource definition For a given InfraMachine resource, you MUST also add a corresponding InfraMachineTemplate resources in order to use it @@ -492,6 +486,12 @@ Please, read carefully the page linked above to fully understand implications an The clusterctl command is designed to work with all the providers compliant with the rules defined in the [clusterctl provider contract]. +### InfraMachine: pausing + +Providers SHOULD implement the pause behaviour for every object with a reconciliation loop. This is done by checking if `spec.paused` is set on the Cluster object and by checking for the `cluster.x-k8s.io/paused` annotation on the InfraMachine object. + +If implementing the pause behavior, providers SHOULD surface the paused status of an object using the Paused condition: `Status.Conditions[Paused]`. + ## Typical InfraMachine reconciliation workflow A machine infrastructure provider must respond to changes to its InfraMachine resources. This process is