OSDOCS#18085: Admonitions to change the auth API separately

machine_management/cluster_api_machine_management/cluster-api-disabling.adoc

@@ -17,6 +17,10 @@ include::modules/capi-to-mapi-migration-overview.adoc[leveloffset=+1]
 //Migrating a Cluster API resource to use the Machine API
 include::modules/migrating-between-capi-mapi.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-migrate-unexpected-behavior_cluster-api-troubleshooting[Unexpected behavior when changing resource configurations]
+
 //Authoritative API types of compute machines
 include::modules/machine-set-authoritative-api-machines.adoc[leveloffset=+2]
 

machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc

@@ -67,6 +67,10 @@ include::modules/machine-set-authoritative-api-machines.adoc[leveloffset=+2]
 //Migrating a Machine API resource to use the Cluster API
 include::modules/migrating-between-capi-mapi.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-migrate-unexpected-behavior_cluster-api-troubleshooting[Unexpected behavior when changing resource configurations]
+
 //Deploying Cluster API compute machines by using a Machine API compute machine set
 include::modules/deploying-capi-machines-via-mapi-machine-sets.adoc[leveloffset=+2]
 

machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc

@@ -22,6 +22,9 @@ include::modules/ts-capi-cli-reference-intended-objects.adoc[leveloffset=+1]
 //Duplicated machine set and machine resources
 include::modules/ts-capi-sync-list-duplicate-resources.adoc[leveloffset=+1]
 
+//Unexpected behavior when changing resource configurations
+include::modules/ts-capi-migrate-unexpected-behavior.adoc[leveloffset=+1]
+
 //Unexpected resource deletion behavior
 include::modules/ts-capi-migrate-unexpected-deletion-behavior.adoc[leveloffset=+1]
 

modules/migrating-between-capi-mapi.adoc

@@ -94,25 +94,42 @@ endif::[]
 [source,yaml,subs="attributes+"]
 ----
 apiVersion: machine.openshift.io/v1beta1
-kind: <resource_kind> <1>
+kind: <resource_kind>
 metadata:
-  name: <resource_name> <2>
+  name: <resource_name>
   [...]
 spec:
-  authoritativeAPI: {to-api-value} <3>
+  authoritativeAPI: {to-api-value}
   [...]
 status:
-  authoritativeAPI: {from-api-value} <4>
+  authoritativeAPI: {from-api-value}
   [...]
 ----
-<1> The resource kind varies depending on the resource kind.
++
+--
+where:
+
+`kind`::
+Specifies the resource kind of the resource that you want to migrate.
 For example, the resource kind for a compute machine set is `MachineSet` and the resource kind for a compute machine is `Machine`.
-<2> The name of the resource that you want to migrate.
-<3> Specify the authoritative API that you want this resource to use.
+`metadata.name`::
+Specifies the name of the resource that you want to migrate.
+`spec.authoritativeAPI`::
+Specifies the authoritative API that you want this resource to use.
 For example, to start migrating a {from-api-name} resource to the {to-api-name}, specify `{to-api-value}`.
-<4> The value for the current authoritative API.
+`status.authoritativeAPI`::
+Specifies the value for the current authoritative API.
 This value indicates which API currently manages this resource.
 Do not change the value in this part of the specification.
+--
++
+[IMPORTANT]
+====
+Do not change other values when you update the value of the `spec.authoritativeAPI` field.
+Because other controllers might process updates to other values before the synchronization controller processes the `spec.authoritativeAPI` field update, changing other values can cause unexpected behavior.
+
+For more information, see "Unexpected behavior when changing resource configurations".
+====
 
 .Verification
 

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

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ts-capi-migrate-unexpected-behavior_{context}"]
+= Unexpected behavior when changing resource configurations
+
+[role="_abstract"]
+On clusters that support migrating resources between the Machine API and the Cluster API, users might experience unexpected resource behavior when updating the authoritative API.
+
+Cause::
+
+In addition to the two-way synchronization controller that manages changes related to migrating between authoritative APIs, other controllers can act on Machine API and Cluster API resources.
++
+If you make other changes while updating the value of the `spec.authoritativeAPI` field, the synchronization controller might not be the first controller to act on the resource when you save the resource specification.
+
+Consequence::
+
+Because other controllers might process updates to other values before the synchronization controller processes the `spec.authoritativeAPI` field update, changing other values can cause unexpected behavior.
++
+For example, if you increase the number of replicas in a machine set specification while updating the value of the `spec.authoritativeAPI` field, the machine set might create machines with the unintended authoritative API.
+
+Workaround::
+
+Do not change other values when you update the value of the `spec.authoritativeAPI` field.
+For more information, see link:https://issues.redhat.com/browse/OCPBUGS-74638[OCPBUGS-74638].