From 9fb25453854dda525a9c12c98bc8559b7ac943a0 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Thu, 19 Sep 2024 15:07:24 +0200 Subject: [PATCH] Group API reference docs --- docs/book/src/SUMMARY.md | 10 +-- .../api}/crd-relationships.md | 4 +- .../reference/api/labels-and-annotations.md | 59 ++++++++++++++++++ .../api}/metadata-propagation.md | 4 +- .../owner-references.md} | 29 ++++----- docs/book/src/reference/api/reference.md | 17 +++++ docs/book/src/reference/api_reference.md | 9 --- .../src/reference/labels_and_annotations.md | 62 ------------------- .../cluster-class/operate-cluster.md | 2 +- .../machineset-preflight-checks.md | 4 +- 10 files changed, 98 insertions(+), 102 deletions(-) rename docs/book/src/{developer => reference/api}/crd-relationships.md (87%) create mode 100644 docs/book/src/reference/api/labels-and-annotations.md rename docs/book/src/{developer/architecture/controllers => reference/api}/metadata-propagation.md (98%) rename docs/book/src/reference/{owner_references.md => api/owner-references.md} (86%) create mode 100644 docs/book/src/reference/api/reference.md delete mode 100644 docs/book/src/reference/api_reference.md delete mode 100644 docs/book/src/reference/labels_and_annotations.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 80c40d543a93..70693faa13cd 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -83,7 +83,6 @@ - [MachinePool](./developer/architecture/controllers/machine-pool.md) - [ClusterTopology](./developer/architecture/controllers/cluster-topology.md) - [ClusterResourceSet](./developer/architecture/controllers/cluster-resource-set.md) - - [Metadata propagation](./developer/architecture/controllers/metadata-propagation.md) - [Multi-tenancy](./developer/architecture/controllers/multi-tenancy.md) - [Support multiple instances](./developer/architecture/controllers/support-multiple-instances.md) - [Tuning controllers](./developer/architecture/controllers/tuning.md) @@ -105,10 +104,13 @@ - [Webhooks](./developer/providers/webhooks.md) - [Controllers and Reconciliation](./developer/providers/implementers-guide/controllers_and_reconciliation.md) - [Building, Running, Testing](./developer/providers/implementers-guide/building_running_and_testing.md) - - [CustomResourceDefinitions relationships](./developer/crd-relationships.md) - [Troubleshooting](./user/troubleshooting.md) - [Reference](./reference/reference.md) - - [API Reference](./reference/api_reference.md) + - [API Reference](./reference/api/reference.md) + - [Labels and Annotations](reference/api/labels-and-annotations.md) + - [CRD relationships](reference/api/crd-relationships.md) + - [Metadata propagation](reference/api/metadata-propagation.md) + - [Owner References](reference/api/owner-references.md) - [Glossary](./reference/glossary.md) - [Provider List](./reference/providers.md) - [Ports](./reference/ports.md) @@ -117,5 +119,3 @@ - [Jobs](./reference/jobs.md) - [Code Review in Cluster API](./REVIEWING.md) - [Version Support](./reference/versions.md) - - [Supported Labels and Annotations](./reference/labels_and_annotations.md) - - [Owner References](./reference/owner_references.md) diff --git a/docs/book/src/developer/crd-relationships.md b/docs/book/src/reference/api/crd-relationships.md similarity index 87% rename from docs/book/src/developer/crd-relationships.md rename to docs/book/src/reference/api/crd-relationships.md index c8f624be0d70..09b2dada846e 100644 --- a/docs/book/src/developer/crd-relationships.md +++ b/docs/book/src/reference/api/crd-relationships.md @@ -14,8 +14,8 @@ The direction of the arrows indicates the direction of "management" or "referenc ## Control plane machines relationships -![]( ../images/kubeadm-control-plane-machines-resources.png) +![]( ../../images/kubeadm-control-plane-machines-resources.png) ## Worker machines relationships -![]( ../images/worker-machines-resources.png) +![]( ../../images/worker-machines-resources.png) diff --git a/docs/book/src/reference/api/labels-and-annotations.md b/docs/book/src/reference/api/labels-and-annotations.md new file mode 100644 index 000000000000..056744de94ae --- /dev/null +++ b/docs/book/src/reference/api/labels-and-annotations.md @@ -0,0 +1,59 @@ +# Supported Labels + +| Label | Note | Managed by | Applies to | +|:------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------|:--------------------------| +| cluster.x-k8s.io/cluster-name | It is set on machines linked to a cluster and external objects(bootstrap and infrastructure providers). | User | Machines | +| cluster.x-k8s.io/control-plane | It is set on machines or related objects that are part of a control plane. | Cluster API | Machines | +| cluster.x-k8s.io/control-plane-name | It is set on machines if they're controlled by a control plane. The value of this label may be a hash if the control plane name is longer than 63 characters. | Cluster API | Machines | +| cluster.x-k8s.io/deployment-name | It is set on machines if they're controlled by a MachineDeployment. | Cluster API | Machines | +| cluster.x-k8s.io/interruptible | It is used to mark the nodes that run on interruptible instances. | User | Nodes | +| cluster.x-k8s.io/pool-name | It is set on machines if they're controlled by a MachinePool. | Cluster API | Machines | +| cluster.x-k8s.io/provider | It is set on components in the provider manifest. The label allows one to easily identify all the components belonging to a provider. The clusterctl tool uses this label for implementing provider's lifecycle operations. | User | Provider Components | +| cluster.x-k8s.io/set-name | It is set on machines if they're controlled by MachineSet. The value of this label may be a hash if the MachineSet name is longer than 63 characters. | Cluster API | Machines | +| cluster.x-k8s.io/watch-filter | It can be applied to any Cluster API object. Controllers which allow for selective reconciliation may check this label and proceed with reconciliation of the object only if this label and a configured value is present. | Cluster API | All Cluster API objects | +| machine-template-hash | It is applied to Machines in a MachineDeployment containing the hash of the template. | Cluster API | Machine | +| topology.cluster.x-k8s.io/deployment-name | It is set on the generated MachineDeployment objects to track the name of the MachineDeployment topology it represents. | Cluster API | MachineDeployment objects | +| topology.cluster.x-k8s.io/owned | It is set on all the object which are managed as part of a ClusterTopology. | Cluster API | ClusterTopology objects | + +# Supported Annotations + +| Annotation | Note | Managed By | Applies to | +|:-----------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------|:------------------------------------------------| +| cluster.x-k8s.io/cloned-from-groupkind | It is the annotation that stores the group-kind of the template from which the current resource has been cloned from. | Cluster API | Any Cluster API resource cloned from a template | +| cluster.x-k8s.io/cloned-from-name | It is the annotation that stores the name of the template from which the current resource has been cloned from. | Cluster API | Any Cluster API resource cloned from a template | +| cluster.x-k8s.io/cluster-name | It is set on nodes identifying the name of the cluster the node belongs to. | Cluster API | Nodes | +| cluster.x-k8s.io/cluster-namespace | It is set on nodes identifying the namespace of the cluster the node belongs to. | Cluster API | Nodes | +| cluster.x-k8s.io/delete-machine | It marks control plane and worker nodes that will be given priority for deletion when KCP or a MachineSet scales down. It is given top priority on all delete policies. | User | Machines | +| cluster.x-k8s.io/disable-machine-create | It can be used to signal a MachineSet to stop creating new machines. It is utilized in the OnDelete MachineDeploymentStrategy to allow the MachineDeployment controller to scale down older MachineSets when Machines are deleted and add the new replicas to the latest MachineSet. | Cluster API | Machineset | +| cluster.x-k8s.io/managed-by | It can be applied to InfraCluster resources to signify that some external system is managing the cluster infrastructure. Provider InfraCluster controllers will ignore resources with this annotation. An external controller must fulfill the contract of the InfraCluster resource. External infrastructure providers should ensure that the annotation, once set, cannot be removed. | User | InfraCluster resources | +| cluster.x-k8s.io/machine | It is set on nodes identifying the machine the node belongs to. | Cluster API | Nodes | +| cluster.x-k8s.io/owner-kind | It is set on nodes identifying the machine's owner kind the node belongs to. | Cluster API | Nodes | +| cluster.x-k8s.io/owner-name | It is set on nodes identifying the machine's owner name the node belongs to. | Cluster API | Nodes | +| cluster.x-k8s.io/paused | It can be applied to any Cluster API object to prevent a controller from processing a resource. Controllers working with Cluster API objects must check the existence of this annotation on the reconciled object. | User | Any Cluster API resource | +| cluster.x-k8s.io/remediate-machine | It can be applied to a machine to manually mark it for remediation by MachineHealthCheck reconciler. | User | Machine | +| cluster.x-k8s.io/replicas-managed-by | It can be applied to MachinePool resources to signify that some external system is managing infrastructure scaling for that pool. See [the MachinePool documentation](../../developer/architecture/controllers/machine-pool.md#externally-managed-autoscaler) for more details. | Infrastructure Providers | MachinePool resources | +| cluster.x-k8s.io/skip-remediation | It is used to mark the machines that should not be considered for remediation by MachineHealthCheck reconciler. | User | Machines | +| clusterctl.cluster.x-k8s.io/block-move | BlockMoveAnnotation prevents the cluster move operation from starting if it is defined on at least one of the objects in scope. Provider controllers are expected to set the annotation on resources that cannot be instantaneously paused and remove the annotation when the resource has been actually paused. | Providers | Any Cluster API resource | +| clusterctl.cluster.x-k8s.io/delete-for-move | DeleteForMoveAnnotation will be set to objects that are going to be deleted from the source cluster after being moved to the target cluster during the clusterctl move operation. It will help any validation webhook to take decision based on it. | Cluster API | Any Cluster API resource | +| clusterctl.cluster.x-k8s.io/skip-crd-name-preflight-check | Can be placed on provider CRDs, so that clusterctl doesn't emit an error if the CRD doesn't comply with Cluster APIs naming scheme. Only CRDs that are referenced by core Cluster API CRDs have to comply with the naming scheme. | Providers | CRDs | +| controlplane.cluster.x-k8s.io/kubeadm-cluster-configuration | It is a machine annotation that stores the json-marshalled string of KCP ClusterConfiguration. This annotation is used to detect any changes in ClusterConfiguration and trigger machine rollout in KCP. | Cluster API | Machines | +| controlplane.cluster.x-k8s.io/remediation-for | It is a machine annotation that links a new machine to the unhealthy machine it is replacing. | Cluster API | Machines | +| controlplane.cluster.x-k8s.io/remediation-in-progress | It is a KCP annotation that tracks that the system is in between having deleted an unhealthy machine and recreating its replacement. | Cluster API | KubeadmControlPlane | +| controlplane.cluster.x-k8s.io/skip-coredns | It explicitly skips reconciling CoreDNS if set. | User | KubeadmControlPlane | +| controlplane.cluster.x-k8s.io/skip-kube-proxy | It explicitly skips reconciling kube-proxy if set. | User | KubeadmControlPlane | +| machine.cluster.x-k8s.io/certificates-expiry | It captures the expiry date of the machine certificates in RFC3339 format. It is used to trigger rollout of control plane machines before certificates expire. It can be set on BootstrapConfig and Machine objects. The value set on Machine object takes precedence. The annotation is only used by control plane machines. | Cluster API/User | BootstrapConfig/Machine | +| machine.cluster.x-k8s.io/exclude-node-draining | It explicitly skips node draining if set. | User | Machines | +| machine.cluster.x-k8s.io/exclude-wait-for-node-volume-detach | It explicitly skips the waiting for node volume detaching if set. | User | Machines | +| machinedeployment.clusters.x-k8s.io/desired-replicas | It is the desired replicas for a machine deployment recorded as an annotation in its machine sets. Helps in separating scaling events from the rollout process and for determining if the new machine set for a deployment is really saturated. | Cluster API | MachineSets | +| machinedeployment.clusters.x-k8s.io/max-replicas | It is the maximum replicas a deployment can have at a given point, which is machinedeployment.spec.replicas + maxSurge. Used by the underlying machine sets to estimate their proportions in case the deployment has surge replicas. | Cluster API | MachineSets | +| machinedeployment.clusters.x-k8s.io/revision | It is the revision annotation of a machine deployment's machine sets which records its rollout sequence. | Cluster API | MachineSet | +| machinedeployment.clusters.x-k8s.io/revision-history | It maintains the history of all old revisions that a machine set has served for a machine deployment. | Cluster API | MachineSets | +| machineset.cluster.x-k8s.io/skip-preflight-checks | It can be applied on MachineDeployment and MachineSet resources to specify a comma-separated list of preflight checks that should be skipped during MachineSet reconciliation. Supported preflight checks are: All, KubeadmVersionSkew, KubernetesVersionSkew, ControlPlaneIsStable. | User | MachineDeployment and MachineSet resources | +| pre-drain.delete.hook.machine.cluster.x-k8s.io | It specifies the prefix we search each annotation for during the pre-drain.delete lifecycle hook to pause reconciliation of deletion. These hooks will prevent removal of draining the associated node until all are removed. | User | Machines | +| pre-terminate.delete.hook.machine.cluster.x-k8s.io | It specifies the prefix we search each annotation for during the pre-terminate.delete lifecycle hook to pause reconciliation of deletion. These hooks will prevent removal of an instance from an infrastructure provider until all are removed. | User | Machines | +| topology.cluster.x-k8s.io/defer-upgrade | It can be used to defer the Kubernetes upgrade of a single MachineDeployment topology. If the annotation is set on a MachineDeployment topology in Cluster.spec.topology.workers, the Kubernetes upgrade for this MachineDeployment topology is deferred. It doesn't affect other MachineDeployment topologies. | Cluster API | MachineDeployments in Cluster.topology | +| topology.cluster.x-k8s.io/dry-run | It is an annotation that gets set on objects by the topology controller only during a server side dry run apply operation. It is used for validating update webhooks for objects which get updated by template rotation (e.g. InfrastructureMachineTemplate). When the annotation is set and the admission request is a dry run, the webhook should deny validation due to immutability. By that the request will succeed (without any changes to the actual object because it is a dry run) and the topology controller will receive the resulting object. | Cluster API | Template rotation objects | +| topology.cluster.x-k8s.io/hold-upgrade-sequence | It can be used to hold the entire MachineDeployment upgrade sequence. If the annotation is set on a MachineDeployment topology in Cluster.spec.topology.workers, the Kubernetes upgrade for this MachineDeployment topology and all subsequent ones is deferred. | Cluster API | MachineDeployments in Cluster.topology | +| topology.cluster.x-k8s.io/upgrade-concurrency | It can be used to configure the maximum concurrency while upgrading MachineDeployments of a classy Cluster. It is set as a top level annotation on the Cluster object. The value should be >= 1. If unspecified the upgrade concurrency will default to 1. | Cluster API | Cluster | +| unsafe.topology.cluster.x-k8s.io/disable-update-class-name-check | It can be used to disable the webhook check on update that disallows a pre-existing Cluster to be populated with Topology information and Class. | User | Cluster | +| unsafe.topology.cluster.x-k8s.io/disable-update-version-check | It can be used to disable the webhook checks on update that disallows updating the .topology.spec.version on certain conditions. | User | Cluster | diff --git a/docs/book/src/developer/architecture/controllers/metadata-propagation.md b/docs/book/src/reference/api/metadata-propagation.md similarity index 98% rename from docs/book/src/developer/architecture/controllers/metadata-propagation.md rename to docs/book/src/reference/api/metadata-propagation.md index c4fdd909ce21..97948ad80e37 100644 --- a/docs/book/src/developer/architecture/controllers/metadata-propagation.md +++ b/docs/book/src/reference/api/metadata-propagation.md @@ -3,7 +3,7 @@ Cluster API controllers implement consistent metadata (labels & annotations) pro This behaviour tries to be consistent with Kubernetes apps/v1 Deployment and ReplicaSet. New providers should behave accordingly fitting within the following pattern: -![](../../../images/metadata-propagation.jpg) +![](../../images/metadata-propagation.jpg) ## Cluster Topology ControlPlaneTopology labels are labels and annotations are continuously propagated to ControlPlane top-level labels and annotations @@ -67,5 +67,3 @@ Label should meet one of the following criterias to propagate to Node: - Has `node-role.kubernetes.io` as prefix. - Belongs to `node-restriction.kubernetes.io` domain. - Belongs to `node.cluster.x-k8s.io` domain. - - diff --git a/docs/book/src/reference/owner_references.md b/docs/book/src/reference/api/owner-references.md similarity index 86% rename from docs/book/src/reference/owner_references.md rename to docs/book/src/reference/api/owner-references.md index bf01d4a9b8e2..3b42030911da 100644 --- a/docs/book/src/reference/owner_references.md +++ b/docs/book/src/reference/api/owner-references.md @@ -1,28 +1,29 @@ # Owner References - -Cluster API uses [Kubernetes owner references](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) to track relationships between objects. These references are used for Kubernetes garbage collection, which is the basis of Cluster deletion in CAPI. They are also used places where the ownership hierarchy is important, for example when using `clusterctl move`. +Cluster API uses [Kubernetes owner references](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) to track relationships between objects. These references are used +for Kubernetes garbage collection, which is also used for Cluster deletion in CAPI. They are also used places where +the ownership hierarchy is important, for example when using `clusterctl move`. CAPI uses owner references in an opinionated way. The following guidelines should be considered: -1. Objects should always be created with an owner reference to prevent leaking objects. Initial ownerReferences can be replaced later where another object is a more appropriate owner. -2. Owner references should be re-reconciled if they are lost for an object. This is required as some tools - e.g. velero - may delete owner references on objects. +1. Objects should always be created with an owner reference to prevent leaking objects. Initial ownerReferences can be + replaced later where another object is a more appropriate owner. +2. Owner references should be re-reconciled if they are lost for an object. This is required as some tools - e.g. velero - + may delete owner references on objects. 3. Owner references should be kept to the most recent apiVersion. - This ensures garbage collection still works after an old apiVersion is no longer served. 4. Owner references should not be added unless required. - Multiple owner references on a single object should be exceptional. - - - ## Owner reference relationships in Cluster API -The below tables map out the a reference for ownership relationships for the objects in a Cluster API cluster. The tables are identical for classy and non-classy clusters. - +The below tables map out the a reference for ownership relationships for the objects in a Cluster API cluster. The tables +are identical for classy and non-classy clusters. Providers may implement their own ownership relationships which may or may not map directly to the below tables. -These owner references are almost all tested in an [end-to-end test](https://github.com/kubernetes-sigs/cluster-api/blob/caaa74482b51fae777334cd7a29595da1c06481e/test/e2e/quick_start_test.go#L31). Lack of testing is noted where this is not the case. CAPI Providers can take advantage of the e2e test framework to ensure their owner references are predictable, documented and stable. +These owner references are almost all tested in an [end-to-end test](https://github.com/kubernetes-sigs/cluster-api/blob/caaa74482b51fae777334cd7a29595da1c06481e/test/e2e/quick_start_test.go#L31). Lack of testing is noted where this is not the case. +CAPI Providers can take advantage of the e2e test framework to ensure their owner references are predictable, documented and stable. - Kubernetes core types +## Kubernetes core types | type | Owner | Controller | Note | |-----------|---------------------|------------|--------------------------------------------| @@ -44,8 +45,6 @@ These owner references are almost all tested in an [end-to-end test](https://git | Machine | KubeadmControlPlane | yes | When created by KCP | | MachineHealthChecks | Cluster | no | | - - ## Experimental types | type | Owner | Controller | Note | |----------------------------|--------------------|------------|--------------------------| @@ -53,13 +52,11 @@ These owner references are almost all tested in an [end-to-end test](https://git | ClusterResourcesSetBinding | ClusterResourceSet | no | May have many CRS owners | | MachinePool | Cluster | no | | - ## KubeadmControlPlane types | type | Owner | Controller | Note | |-----------------------------|--------------|------------|------| | KubeadmControlPlane | Cluster | yes | | | KubeadmControlPlaneTemplate | ClusterClass | no | | - ## Kubeadm bootstrap types | type | Owner | Controller | Note | @@ -78,5 +75,3 @@ These owner references are almost all tested in an [end-to-end test](https://git | InfrastructureCluster | Cluster | yes | | | InfrastructureClusterTemplate | ClusterClass | no | | | InfrastructureMachinePool | MachinePool | yes | | - - diff --git a/docs/book/src/reference/api/reference.md b/docs/book/src/reference/api/reference.md new file mode 100644 index 000000000000..a41355d535fc --- /dev/null +++ b/docs/book/src/reference/api/reference.md @@ -0,0 +1,17 @@ +# API Reference + +Cluster API currently exposes the following APIs: + +* the Cluster API Custom Resource Definitions (CRDs): [documentation](https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api) + +* Golang APIs: [godoc](https://pkg.go.dev/sigs.k8s.io/cluster-api) + +Following pages provide additional documentation to better understand and use Cluster API types. + +* [Labels and Annotations](labels-and-annotations.md) + +* [CRD relationships](crd-relationships.md) + +* [Metadata propagation](metadata-propagation.md) + +* [Owner References](owner-references.md) diff --git a/docs/book/src/reference/api_reference.md b/docs/book/src/reference/api_reference.md deleted file mode 100644 index 8d2f81417247..000000000000 --- a/docs/book/src/reference/api_reference.md +++ /dev/null @@ -1,9 +0,0 @@ -# API Reference - -Cluster API currently exposes the following APIs: - -* the Cluster API Custom Resource Definitions (CRDs): [documentation](https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api) - -* Golang APIs: [godoc](https://pkg.go.dev/sigs.k8s.io/cluster-api) - -* Supported Labels and Annotations: [documentation](./labels_and_annotations.md) \ No newline at end of file diff --git a/docs/book/src/reference/labels_and_annotations.md b/docs/book/src/reference/labels_and_annotations.md deleted file mode 100644 index cd8810902d31..000000000000 --- a/docs/book/src/reference/labels_and_annotations.md +++ /dev/null @@ -1,62 +0,0 @@ -**Supported Labels:** - - -| Label | Note | Managed by | Applies to | -|:------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------|:--------------------------------------------| -| cluster.x-k8s.io/cluster-name | It is set on machines linked to a cluster and external objects(bootstrap and infrastructure providers). | User | Machines | -| cluster.x-k8s.io/control-plane | It is set on machines or related objects that are part of a control plane. | Cluster API | Machines | -| cluster.x-k8s.io/control-plane-name | It is set on machines if they're controlled by a control plane. The value of this label may be a hash if the control plane name is longer than 63 characters. | Cluster API | Machines | -| cluster.x-k8s.io/deployment-name | It is set on machines if they're controlled by a MachineDeployment. | Cluster API | Machines | -| cluster.x-k8s.io/interruptible | It is used to mark the nodes that run on interruptible instances. | User | Nodes | -| cluster.x-k8s.io/pool-name | It is set on machines if they're controlled by a MachinePool. | Cluster API | Machines | -| cluster.x-k8s.io/provider | It is set on components in the provider manifest. The label allows one to easily identify all the components belonging to a provider. The clusterctl tool uses this label for implementing provider's lifecycle operations. | User | Provider Components | -| cluster.x-k8s.io/set-name | It is set on machines if they're controlled by MachineSet. The value of this label may be a hash if the MachineSet name is longer than 63 characters. | Cluster API | Machines | -| cluster.x-k8s.io/watch-filter | It can be applied to any Cluster API object. Controllers which allow for selective reconciliation may check this label and proceed with reconciliation of the object only if this label and a configured value is present. | Cluster API | All Cluster API objects | -| machine-template-hash | It is applied to Machines in a MachineDeployment containing the hash of the template. | Cluster API | Machine | -| topology.cluster.x-k8s.io/deployment-name | It is set on the generated MachineDeployment objects to track the name of the MachineDeployment topology it represents. | Cluster API | MachineDeployment objects | -| topology.cluster.x-k8s.io/owned | It is set on all the object which are managed as part of a ClusterTopology. | Cluster API | ClusterTopology objects | -
- - -**Supported Annotations:** - -| Annotation | Note | Managed By | Applies to | -|:------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------|:-------------------------------------------| -| cluster.x-k8s.io/cloned-from-groupkind | It is the annotation that stores the group-kind of the template from which the current resource has been cloned from. | Cluster API | Any Cluster API resource cloned from a template | -| cluster.x-k8s.io/cloned-from-name | It is the annotation that stores the name of the template from which the current resource has been cloned from. | Cluster API | Any Cluster API resource cloned from a template | -| cluster.x-k8s.io/cluster-name | It is set on nodes identifying the name of the cluster the node belongs to. | Cluster API | Nodes | -| cluster.x-k8s.io/cluster-namespace | It is set on nodes identifying the namespace of the cluster the node belongs to. | Cluster API | Nodes | -| cluster.x-k8s.io/delete-machine | It marks control plane and worker nodes that will be given priority for deletion when KCP or a MachineSet scales down. It is given top priority on all delete policies. | User | Machines | -| cluster.x-k8s.io/disable-machine-create | It can be used to signal a MachineSet to stop creating new machines. It is utilized in the OnDelete MachineDeploymentStrategy to allow the MachineDeployment controller to scale down older MachineSets when Machines are deleted and add the new replicas to the latest MachineSet. | Cluster API | Machineset | -| cluster.x-k8s.io/managed-by | It can be applied to InfraCluster resources to signify that some external system is managing the cluster infrastructure. Provider InfraCluster controllers will ignore resources with this annotation. An external controller must fulfill the contract of the InfraCluster resource. External infrastructure providers should ensure that the annotation, once set, cannot be removed. | User | InfraCluster resources | -| cluster.x-k8s.io/machine | It is set on nodes identifying the machine the node belongs to. | Cluster API | Nodes | -| cluster.x-k8s.io/owner-kind | It is set on nodes identifying the machine's owner kind the node belongs to. | Cluster API | Nodes | -| cluster.x-k8s.io/owner-name | It is set on nodes identifying the machine's owner name the node belongs to. | Cluster API | Nodes | -| cluster.x-k8s.io/paused | It can be applied to any Cluster API object to prevent a controller from processing a resource. Controllers working with Cluster API objects must check the existence of this annotation on the reconciled object. | User | Any Cluster API resource | -| cluster.x-k8s.io/remediate-machine | It can be applied to a machine to manually mark it for remediation by MachineHealthCheck reconciler. | User | Machine | -| cluster.x-k8s.io/replicas-managed-by | It can be applied to MachinePool resources to signify that some external system is managing infrastructure scaling for that pool. See [the MachinePool documentation](../developer/architecture/controllers/machine-pool.md#externally-managed-autoscaler) for more details. | Infrastructure Providers | MachinePool resources | -| cluster.x-k8s.io/skip-remediation | It is used to mark the machines that should not be considered for remediation by MachineHealthCheck reconciler. | User | Machines | -| clusterctl.cluster.x-k8s.io/block-move | BlockMoveAnnotation prevents the cluster move operation from starting if it is defined on at least one of the objects in scope. Provider controllers are expected to set the annotation on resources that cannot be instantaneously paused and remove the annotation when the resource has been actually paused. | Providers | Any Cluster API resource | -| clusterctl.cluster.x-k8s.io/delete-for-move | DeleteForMoveAnnotation will be set to objects that are going to be deleted from the source cluster after being moved to the target cluster during the clusterctl move operation. It will help any validation webhook to take decision based on it. | Cluster API | Any Cluster API resource | -| clusterctl.cluster.x-k8s.io/skip-crd-name-preflight-check | Can be placed on provider CRDs, so that clusterctl doesn't emit an error if the CRD doesn't comply with Cluster APIs naming scheme. Only CRDs that are referenced by core Cluster API CRDs have to comply with the naming scheme. | Providers | CRDs | -| controlplane.cluster.x-k8s.io/kubeadm-cluster-configuration | It is a machine annotation that stores the json-marshalled string of KCP ClusterConfiguration. This annotation is used to detect any changes in ClusterConfiguration and trigger machine rollout in KCP. | Cluster API | Machines | -| controlplane.cluster.x-k8s.io/remediation-for | It is a machine annotation that links a new machine to the unhealthy machine it is replacing. | Cluster API | Machines | -| controlplane.cluster.x-k8s.io/remediation-in-progress | It is a KCP annotation that tracks that the system is in between having deleted an unhealthy machine and recreating its replacement. | Cluster API | KubeadmControlPlane | -| controlplane.cluster.x-k8s.io/skip-coredns | It explicitly skips reconciling CoreDNS if set. | User | KubeadmControlPlane | -| controlplane.cluster.x-k8s.io/skip-kube-proxy | It explicitly skips reconciling kube-proxy if set. | User | KubeadmControlPlane | -| machine.cluster.x-k8s.io/certificates-expiry | It captures the expiry date of the machine certificates in RFC3339 format. It is used to trigger rollout of control plane machines before certificates expire. It can be set on BootstrapConfig and Machine objects. The value set on Machine object takes precedence. The annotation is only used by control plane machines. | Cluster API/User | BootstrapConfig/Machine | -| machine.cluster.x-k8s.io/exclude-node-draining | It explicitly skips node draining if set. | User | Machines | -| machine.cluster.x-k8s.io/exclude-wait-for-node-volume-detach | It explicitly skips the waiting for node volume detaching if set. | User | Machines | -| machinedeployment.clusters.x-k8s.io/desired-replicas | It is the desired replicas for a machine deployment recorded as an annotation in its machine sets. Helps in separating scaling events from the rollout process and for determining if the new machine set for a deployment is really saturated. | Cluster API | MachineSets | -| machinedeployment.clusters.x-k8s.io/max-replicas | It is the maximum replicas a deployment can have at a given point, which is machinedeployment.spec.replicas + maxSurge. Used by the underlying machine sets to estimate their proportions in case the deployment has surge replicas. | Cluster API | MachineSets | -| machinedeployment.clusters.x-k8s.io/revision | It is the revision annotation of a machine deployment's machine sets which records its rollout sequence. | Cluster API | MachineSet | -| machinedeployment.clusters.x-k8s.io/revision-history | It maintains the history of all old revisions that a machine set has served for a machine deployment. | Cluster API | MachineSets | -| machineset.cluster.x-k8s.io/skip-preflight-checks | It can be applied on MachineDeployment and MachineSet resources to specify a comma-separated list of preflight checks that should be skipped during MachineSet reconciliation. Supported preflight checks are: All, KubeadmVersionSkew, KubernetesVersionSkew, ControlPlaneIsStable. | User | MachineDeployment and MachineSet resources | -| pre-drain.delete.hook.machine.cluster.x-k8s.io | It specifies the prefix we search each annotation for during the pre-drain.delete lifecycle hook to pause reconciliation of deletion. These hooks will prevent removal of draining the associated node until all are removed. | User | Machines | -| pre-terminate.delete.hook.machine.cluster.x-k8s.io | It specifies the prefix we search each annotation for during the pre-terminate.delete lifecycle hook to pause reconciliation of deletion. These hooks will prevent removal of an instance from an infrastructure provider until all are removed. | User | Machines | -| topology.cluster.x-k8s.io/defer-upgrade | It can be used to defer the Kubernetes upgrade of a single MachineDeployment topology. If the annotation is set on a MachineDeployment topology in Cluster.spec.topology.workers, the Kubernetes upgrade for this MachineDeployment topology is deferred. It doesn't affect other MachineDeployment topologies. | Cluster API | MachineDeployments in Cluster.topology | -| topology.cluster.x-k8s.io/dry-run | It is an annotation that gets set on objects by the topology controller only during a server side dry run apply operation. It is used for validating update webhooks for objects which get updated by template rotation (e.g. InfrastructureMachineTemplate). When the annotation is set and the admission request is a dry run, the webhook should deny validation due to immutability. By that the request will succeed (without any changes to the actual object because it is a dry run) and the topology controller will receive the resulting object. | Cluster API | Template rotation objects | -| topology.cluster.x-k8s.io/hold-upgrade-sequence | It can be used to hold the entire MachineDeployment upgrade sequence. If the annotation is set on a MachineDeployment topology in Cluster.spec.topology.workers, the Kubernetes upgrade for this MachineDeployment topology and all subsequent ones is deferred. | Cluster API | MachineDeployments in Cluster.topology | -| topology.cluster.x-k8s.io/upgrade-concurrency | It can be used to configure the maximum concurrency while upgrading MachineDeployments of a classy Cluster. It is set as a top level annotation on the Cluster object. The value should be >= 1. If unspecified the upgrade concurrency will default to 1. | Cluster API | Cluster | -| unsafe.topology.cluster.x-k8s.io/disable-update-class-name-check | It can be used to disable the webhook check on update that disallows a pre-existing Cluster to be populated with Topology information and Class. | User | Cluster | -| unsafe.topology.cluster.x-k8s.io/disable-update-version-check | It can be used to disable the webhook checks on update that disallows updating the .topology.spec.version on certain conditions. | User | Cluster | diff --git a/docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md b/docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md index 05f9a88a20c2..dd2e4a383f82 100644 --- a/docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md +++ b/docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md @@ -230,7 +230,7 @@ Following recommendation apply: from one machine to the other. - Keep machine labels and annotation stable, because changing those values requires machines rollouts; also, please note that machine labels and annotation are not propagated to Kubernetes nodes; see - [metadata propagation](../../../developer/architecture/controllers/metadata-propagation.md). + [metadata propagation](../../../reference/api/metadata-propagation.md). - While upgrading a Cluster, if possible avoid any other concurrent change to the Cluster; please note that you can rely on [version-aware patches](write-clusterclass.md#version-aware-patches) to ensure the Cluster adapts to the new Kubernetes version in sync with the upgrade workflow. diff --git a/docs/book/src/tasks/experimental-features/machineset-preflight-checks.md b/docs/book/src/tasks/experimental-features/machineset-preflight-checks.md index ad003dc5bd10..a24b94b977d8 100644 --- a/docs/book/src/tasks/experimental-features/machineset-preflight-checks.md +++ b/docs/book/src/tasks/experimental-features/machineset-preflight-checks.md @@ -55,9 +55,7 @@ Examples:

Pro-tip: Set annotation through MachineDeployment

-Because of the [metadata propagation](../../developer/architecture/controllers/metadata-propagation.md#machinedeployment) rules in Cluster API you can set the `machineset.cluster.x-k8s.io/skip-preflight-checks` annotation +Because of the [metadata propagation](../../reference/api/metadata-propagation.md#machinedeployment) rules in Cluster API you can set the `machineset.cluster.x-k8s.io/skip-preflight-checks` annotation on a MachineDeployment and it will be automatically set on the MachineSets of that MachineDeployment, including any new MachineSets created when the MachineDeployment performs a rollout. - -