docs: add adr for v1 to v3 controller migration

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

@@ -0,0 +1,56 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [10. Migrate to v3 cluster resource](#10-migrate-to-v3-cluster-resource)
+  - [Context](#context)
+  - [Decision](#decision)
+  - [Consequences](#consequences)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# 10. Migrate to v3 cluster resource
+
+- Status: proposed
+- Date: 2024-06-12
+- Authors: @alexander-demicev @salasberryfin
+- Deciders: @Danil-Grigorev @furkatgofurov7 @yiannistri @mjura
+
+## Context
+
+The current 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 labeled for import.
+A new controller was introduced recenty 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. For now, Turtles continues to use the original controller and the new implementation is sitting behind a disabled feature gate.
+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?
+
+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.
+
+This means that, if the new controller we'll be migrating to is able to identify a 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.
+
+**WIP** - TBD
+...
+...
+Need to explain a bit further how to apply labels to clusters: migration script?
+How do we protect clusters if users don't follow the correct migration process?
+
+## Consequences
+
+-