diff --git a/machine_management/cluster_api_machine_management/cluster-api-disabling.adoc b/machine_management/cluster_api_machine_management/cluster-api-disabling.adoc index 884ee91ad7..c07f64ffdc 100644 --- a/machine_management/cluster_api_machine_management/cluster-api-disabling.adoc +++ b/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] diff --git a/machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc b/machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc index f629e4e17b..a0e68bc6ce 100644 --- a/machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc +++ b/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] diff --git a/machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc b/machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc index 8b0c6e05e2..576694fd51 100644 --- a/machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc +++ b/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] diff --git a/modules/migrating-between-capi-mapi.adoc b/modules/migrating-between-capi-mapi.adoc index d06495db30..c26b1830b3 100644 --- a/modules/migrating-between-capi-mapi.adoc +++ b/modules/migrating-between-capi-mapi.adoc @@ -94,25 +94,42 @@ endif::[] [source,yaml,subs="attributes+"] ---- apiVersion: machine.openshift.io/v1beta1 -kind: <1> +kind: metadata: - name: <2> + 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 diff --git a/modules/ts-capi-migrate-unexpected-behavior.adoc b/modules/ts-capi-migrate-unexpected-behavior.adoc new file mode 100644 index 0000000000..442fb1e833 --- /dev/null +++ b/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]. \ No newline at end of file