docs: add adr for v1 to v3 controller migration (#573)

Signed-off-by: Carlos Salas <carlos.salas@suse.com>

docs/adr/0010-migrate-to-v3-cluster-resource.md

@@ -0,0 +1,70 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [10. Manually migrate to v3 cluster resource](#10-manually-migrate-to-v3-cluster-resource)
+  - [Context](#context)
+  - [Decision](#decision)
+  - [Consequences](#consequences)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# 10. Manually migrate to v3 cluster resource
+
+- Status: proposed
+- Date: 2024-06-12
+- Authors: @alexander-demicev @salasberryfin
+- Deciders: @Danil-Grigorev @furkatgofurov7 @yiannistri @mjura
+
+## Context
+
+> **_NOTE:_** this ADR refers specifically to manual migration. You can read the ADR on automatic migration [ADR #11](./0011-v1-to-v3-migration.md), which is the preferred migration method.
+
+The intial implementation of the import process via Turtles is based on creating a `clusters.provisioning.cattle.io` (also referred to as v1 clusters) resource that represents the Rancher cluster. The controller will watch CAPI cluster resources and trigger the creation of a `clusters.provisioning.cattle.io` when a cluster or the cluster's namespace is labelled for import.
+A new controller was introduced recently that would follow an equivalent procedure for import but would use `clusters.management.cattle.io` (also referred to as v3 clusters) resources to represent Rancher clusters. The import logic used by this controller was presented in [ADR 8](./0008-managementv3-clusters-support.md). Both controllers have been supported for a few months but the `v1` option has remained the default import mechanism.
+The goal of this ADR is to describe the procedure to migrate to the new controller, which will become the default cluster import mechanism, and, eventually, deprecate the old logic. As users who have already provisioned CAPI clusters will already have v1 cluster resources associated with CAPI clusters, we must ensure that we make a safe transition to the new import mechanism, avoiding resource duplicates or deletions that may cause problems to end users.
+
+## Decision
+
+An initial assessment of the requirements for the migration suggested that we should define a procedure based on deleting existing Rancher cluster resources, migrating to new controller, and letting this new controller take care of creating new Rancher cluster resources for imported clusters that align with the pre-migration configuration.
+
+After some investigation, we realized that this approach can end up causing a Rancher cluster resource duplication. While testing this proof-of-concept, it is important to note the differences between the Rancher cluster resources created when importing a cluster to Rancher:
+- Both v1 and v3 clusters are created to represent every Rancher clusters.
+- In the case of the current controller, we generate a v1 and let Rancher take care of v3.
+- When migrating to the newer controller, we generate a v3 and let Rancher take care of v1.
+
+#### So, what is the difference between both controllers?
+
+Refer to the [original v3 controller ADR](./0008-managementv3-clusters-support.md) if you want to dive into details of how the import controller works. The following is just a summary for contextualizing this ADR specifically.
+
+The main difference in terms of logic is that, while watching v1 resources, we can use the name of the clusters to identify whether there is an existing resource that represents the CAPI-provisioned cluster.
+
+This means that the resource itself is easily linked to a CAPI cluster via name.
+
+Alternatively, when watching v3 clusters in the new controller, the name of the resource is a semi-random string automatically generated by Kubernetes, which forces us to find a different approach to find the resource of interest. Additionally, v3 clusters are not namespaced but global.
+To simplify the watcher on v3 clusters, we add two labels to the resource to reference the `name` and `namespace` of the CAPI cluster it is linked to.
+
+#### And, what is the difference between v3 clusters for each controller?
+
+Now that we now how we link Rancher cluster -> CAPI cluster, we know that the difference between v3 clusters in both controllers is the existence of the CAPI cluster `name` and `namespace` labels. There is an extra label that marks that the resource is a CAPI cluster `cluster-api.cattle.io/owned`, which is also used by the selector on the controller to filter resources and is inherited from the v1 import controller.
+
+This means that, if the new controller we'll be migrating to is able to identify v3 clusters with the required labels, we can simply switch controllers and expect everything to be unchanged and Rancher clusters to maintain the same configuration.
+
+#### How does this affect import controllers?
+
+With the current import mechanism, Rancher automatically creates a v3 clusters that links to the v1 cluster generated by Turtles. As stated before, this means that no new resources need to be created for the new import controller to operate normally.
+During migration Turtles needs to be aware of the existing imported clusters and apply labels accordingly so these resources can be reused. As part of the migration guide, we will provide a migration script that allows users to prepare imported clusters for migration in batches, which will simplify the migration process (you can refer to [this PR](https://github.com/rancher/turtles/pull/574)). During this process, there needs to be a mechanism to identify which clusters are actually managed by Turtles: this can simply be done by looking for the `-capi` suffix in the resource name, which is added to all Rancher cluster resources created from Turtles. Additionally, after resources have been prepared for migration, they must be marked to avoid repeating the process on the same resource more than once. An annotation on the `clusters.provisioning.cattle.io` will be used for this:
+```
+cluster-api.cattle.io/migrated
+```
+
+When the new controller is running, it validates that the v1 cluster resource has been marked as migrated before proceeding with reconciliation.
+
+## Consequences
+
+- The current import controller will be replaced by the new controller which switches to creating `clusters.management.cattle.io` resource for representing CAPI clusters in Rancher via Turtles.
+- Already imported clusters (via original mechanism) are represented by both `clusters.provisioning.cattle.io` and `clusters.management.cattle.io` (v1 and v3) resources and we can reuse these while maintaining their imported status.
+- The new controller filters imported clusters on labels: this means that existing clusters will need to be updated and corresponding labels added.
+- Suggestion for users is to use migration script to update prepare imported clusters for controller migration.
+- After clusters are prepared for migration, they are marked via annotation.
+- The new controller will validate watched resources to avoid duplication.
+- Additionally, we will document the migration procedure and provide manual commands for users that want to apply them directly.