OSDOCS-14739: Troubleshooting MAPI-CAPI deletion behavior

Author: jeana-redhat

machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc

@@ -21,8 +21,7 @@ include::modules/ts-capi-cli-reference-intended-objects.adoc[leveloffset=+1]
 include::modules/ts-capi-sync-list-duplicate-resources.adoc[leveloffset=+1]
 
 //Unexpected resource deletion behavior
-//Draft to be completed
-//include::modules/ts-capi-migrate-unexpected-deletion-behavior.adoc[leveloffset=+1]
+include::modules/ts-capi-migrate-unexpected-deletion-behavior.adoc[leveloffset=+1]
 
 [id="ts-capi-resource-migration_{context}"]
 == Troubleshooting resource migration

modules/ts-capi-migrate-unexpected-deletion-behavior.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ts-capi-migrate-unexpected-deletion-behavior_{context}"]
+= Unexpected resource deletion behavior
+
+On clusters that support migrating resources between the Machine API and the Cluster API, users might experience unexpected behavior when deleting Cluster API resources on a cluster where the Machine API is authoritative.
+
+Cause::
+
+For any resource that uses the authoritative API, the two-way synchronization controller creates and maintains corresponding resources that do not use the current authoritative API.
++
+The deletion behavior for resources that do not use the current authoritative API depends on which API is authoritative.
++
+--
+* When you delete a Cluster API resource on a cluster where the Machine API is authoritative, the synchronization controller deletes the corresponding Machine API resource.
+
+* When you delete a Machine API resource on a cluster where the Cluster API is authoritative, the synchronization controller does not delete the corresponding Cluster API resource.
+This difference in behavior supports migration from using the Machine API to using the Cluster API.
+--
++
+This behavior occurs when deleting resources directly and when performing scale-down operations.
+
+Consequence::
+
+This different behavior depending on which API is authoritative has the following consequences:
++
+--
+* For clusters on which the Cluster API is authoritative, you can remove Machine API resources with no impact to the corresponding Cluster API resources.
+
+* For clusters on which the Machine API is authoritative, you cannot remove Cluster API resources without also deleting the corresponding Machine API resources.
+--
+
+Workaround::
+
+For clusters on which the Machine API is authoritative, do not delete any Cluster API resource unless you want to delete the corresponding Machine API resource.