Merge pull request #93656 from jeana-redhat/OSDOCS-14739-MAPI-CAPI-conversion-ts

OSDOCS-14739: Troubleshooting MAPI-CAPI migration

Author: jeana-redhat

machine_management/cluster_api_machine_management/cluster-api-disabling.adoc

@@ -12,12 +12,15 @@ To stop using the Cluster API to automate the management of infrastructure resou
 include::snippets/technology-preview.adoc[]
 
 //Migrating Cluster API resources to Machine API resources
-include::modules/mapi-capi-migration-overview.adoc[leveloffset=+1]
+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]
 
+//Authoritative API types of compute machines
+include::modules/machine-set-authoritative-api-machines.adoc[leveloffset=+2]
+
 [role="_additional-resources"]
 .Additional resources
-// * xr3f:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-resource-migration_cluster-api-troubleshooting[Troubleshooting resource migration]
-* xref:../../machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc#capi-mapi-migration-overview_cluster-api-getting-started[Migrating Machine API resources to Cluster API resources]
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-resource-migration_cluster-api-troubleshooting[Troubleshooting resource migration]
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc#mapi-to-capi-migration-overview_cluster-api-getting-started[Migrating Machine API resources to Cluster API resources]

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

@@ -24,7 +24,7 @@ When you install a cluster that supports managing infrastructure resources with
 * One provider-specific infrastructure cluster resource.
 
 On clusters that support migrating Machine API resources to Cluster API resources, a two-way synchronization controller creates these primary resources automatically.
-For more information, see xref:../../machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc#capi-mapi-migration-overview_cluster-api-getting-started[Migrating Machine API resources to Cluster API resources].
+For more information, see xref:../../machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc#mapi-to-capi-migration-overview_cluster-api-getting-started[Migrating Machine API resources to Cluster API resources].
 
 [id="creating-primary-resources_{context}"]
 == Creating the Cluster API primary resources
@@ -57,7 +57,10 @@ include::modules/capi-creating-machine-set.adoc[leveloffset=+2]
 * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-bare-metal.adoc#capi-yaml-machine-set-bare-metal_cluster-api-config-options-bare-metal[Sample YAML for a Cluster API compute machine set resource on bare metal]
 
 //Migrating Machine API resources to Cluster API resources
-include::modules/capi-mapi-migration-overview.adoc[leveloffset=+1]
+include::modules/mapi-to-capi-migration-overview.adoc[leveloffset=+1]
+
+//Authoritative API types of compute machines
+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]
@@ -67,5 +70,5 @@ include::modules/deploying-capi-machines-via-mapi-machine-sets.adoc[leveloffset=
 
 [role="_additional-resources"]
 .Additional resources
-//* xr3f:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-resource-migration_cluster-api-troubleshooting[Troubleshooting resource migration]
-* xref:../../machine_management/cluster_api_machine_management/cluster-api-disabling.adoc#mapi-capi-migration-overview_cluster-api-disabling[Migrating Cluster API resources to Machine API resources]
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-resource-migration_cluster-api-troubleshooting[Troubleshooting resource migration]
+* xref:../../machine_management/cluster_api_machine_management/cluster-api-disabling.adoc#capi-to-mapi-migration-overview_cluster-api-disabling[Migrating Cluster API resources to Machine API resources]

machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc

@@ -15,4 +15,33 @@ Generally, troubleshooting steps for problems with the Cluster API are similar t
 The {cluster-capi-operator} and its operands are provisioned in the `openshift-cluster-api` namespace, whereas the Machine API uses the `openshift-machine-api` namespace. When using `oc` commands that reference a namespace, be sure to reference the correct one.
 
 //Returning the intended machines when using the CLI
-include::modules/ts-capi-cli-reference-intended-objects.adoc[leveloffset=+1]
+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 resource deletion behavior
+//Draft to be completed
+//include::modules/ts-capi-migrate-unexpected-deletion-behavior.adoc[leveloffset=+1]
+
+[id="ts-capi-resource-migration_{context}"]
+== Troubleshooting resource migration
+
+When you migrate a resource to use a different authoritative API, you might encounter issues during the migration process.
+You might also notice unexpected behavior due to differences between the Cluster API and the Machine API.
+
+//Authoritative API types of compute machines
+include::modules/machine-set-authoritative-api-machines.adoc[leveloffset=+2]
+
+//Unexpected machine counts after scaling
+include::modules/ts-capi-migrate-unexpected-machine-counts-scaling.adoc[leveloffset=+2]
+
+//Incomplete synchronization of labels and annotations 
+include::modules/ts-capi-migrate-sync-label-annotation.adoc[leveloffset=+2]
+
+//Migrating {aws-short} cloud credentials
+//KCS draft not ready for publication
+//include::modules/ts-capi-migrate-aws-creds.adoc[leveloffset=+2]
+
+//Unsupported configuration options
+include::modules/ts-capi-migrate-unsupported-features.adoc[leveloffset=+2]

modules/mapi-capi-migration-overview.adoc renamed to modules/capi-to-mapi-migration-overview.adoc

@@ -3,7 +3,7 @@
 // * machine_management/cluster_api_machine_management/cluster-api-disabling.adoc
 
 :_mod-docs-content-type: CONCEPT
-[id="mapi-capi-migration-overview_{context}"]
+[id="capi-to-mapi-migration-overview_{context}"]
 = Migrating Cluster API resources to Machine API resources
 
 On clusters that support migrating between Machine API and Cluster API resources, the two-way synchronization controller supports converting a Cluster API resource to a Machine API resource.

modules/machine-set-authoritative-api-machines.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster-api-disabling.adoc
+// * machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc
+// * machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="machine-set-authoritative-api-machines_{context}"]
+= Authoritative API types of compute machines
+
+The authoritative API of a compute machine depends on the values of the `.spec.authoritativeAPI` and `.spec.template.spec.authoritativeAPI` fields in the Machine API compute machine set that creates it.
+
+.Interaction of `authoritativeAPI` fields when creating compute machines
+[cols="h,1,1,1,1"]
+|===
+|`.spec.authoritativeAPI` value
+|`ClusterAPI`
+|`ClusterAPI`
+|`MachineAPI`
+|`MachineAPI`
+
+|`.spec.template.spec.authoritativeAPI` value
+|`ClusterAPI`
+|`MachineAPI`
+|`MachineAPI`
+|`ClusterAPI`
+
+|`authoritativeAPI` value for new compute machines
+|`ClusterAPI`
+|`ClusterAPI`
+|`MachineAPI`
+|`ClusterAPI`
+|===
+
+[NOTE]
+====
+When the `.spec.authoritativeAPI` value is `ClusterAPI`, the Machine API machine set is not authoritative and the `.spec.template.spec.authoritativeAPI` value is not used.
+As a result, the only combination that creates a compute machine with the Machine API as authoritative is where the `.spec.authoritativeAPI` and `.spec.template.spec.authoritativeAPI` values are `MachineAPI`.
+====

modules/capi-mapi-migration-overview.adoc renamed to modules/mapi-to-capi-migration-overview.adoc

@@ -3,7 +3,7 @@
 // * machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc
 
 :_mod-docs-content-type: CONCEPT
-[id="capi-mapi-migration-overview_{context}"]
+[id="mapi-to-capi-migration-overview_{context}"]
 = Migrating Machine API resources to Cluster API resources
 
 On clusters that support migrating Machine API resources to Cluster API resources, a two-way synchronization controller creates the following Cluster API resources in the `openshift-cluster-api` namespace:

modules/migrating-between-capi-mapi.adoc

@@ -147,7 +147,7 @@ ifdef::cluster-to-machine[]
 Do not delete any nonauthoritative resource that does not use the current authoritative API unless you want to delete the corresponding resource that does use the current authoritative API.
 
 When you delete a nonauthoritative resource that does not use the current authoritative API, the synchronization controller deletes the corresponding resource that does use the current authoritative API.
-//For more information, see "Unexpected resource deletion behavior" in the _Troubleshooting resource conversion_ content.
+For more information, see "Unexpected resource deletion behavior" in the _Troubleshooting resource migration_ content.
 ====
 endif::[]
 

modules/ts-capi-migrate-aws-creds.adoc

@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ts-capi-migrate-aws-creds_{context}"]
+= Migrating {aws-short} cloud credentials
+
+//KCS draft not ready for publication
+
+The two-way synchronization controller that maintains changes between Machine API and Cluster API resources does not automatically copy {aws-first} credential secrets. 
+For more information, see the Red{nbsp}Hat Knowledgebase article link:https://access.redhat.com/articles/7116313[Migrate AWS cloud credentials between Machine API and Cluster API].

modules/ts-capi-migrate-sync-label-annotation.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ts-capi-migrate-sync-label-annotation_{context}"]
+= Incomplete synchronization of labels and annotations
+
+The label and annotation synchronization behavior differs between the Machine API and the Cluster API.
+In some cases, these differences cause the two-way synchronization controller to overwrite labels on a Cluster API machine during migration.
+
+Cause::
+
+With the Machine API, changes to machine set labels and annotations do not propagate to existing machines and nodes.
+These changes only apply to machines deployed after the update. 
++
+With the Cluster API, changes to machine set labels and annotations propagate to existing machines and nodes.
+When the authoritative API for a machine set changes from Machine API to Cluster API, its labels propagate to the Cluster API machines that it manages.
+The propagation happens before the Cluster API machine is marked as authoritative.
+
+Consequence::
+
+The two-way synchronization controller overwrites any propagated labels and annotations with the earlier value, leading to an inconsistency.
+This outcome only occurs when removing a label or annotation.
+Updates and additional labels or annotations do not cause this inconsistency.
+
+Workaround::
+
+There is no workaround for this issue.
+For more information, see link:https://issues.redhat.com/browse/OCPBUGS-54333[OCPBUGS-54333].

modules/ts-capi-migrate-unexpected-machine-counts-scaling.adoc

@@ -0,0 +1,46 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ts-capi-migrate-unexpected-machine-counts-scaling_{context}"]
+= Unexpected machine counts after scaling
+
+On clusters that support migrating resources between the Machine API and the Cluster API, users might experience unexpected behavior when scaling the number of compute machines.
+The output of the `oc get` command for a compute machine set that does not use the authoritative API might contain inaccurate values in the `CURRENT`, `READY`, and `AVAILABLE` columns. 
+
+Cause::
+
+The values that populate the `CURRENT`, `READY`, and `AVAILABLE` columns originate in the `.status` stanza of a compute machine set.
+The two-way synchronization controller that handles resource conversion between authoritative API types does not currently synchronize values in the `.status` stanza.
++
+The value in the `DESIRED` column reflects the `.spec.replicas` value of a compute machine set.
+The two-way synchronization controller synchronizes values in the `.spec` stanza.
+
+Consequence::
+
+Users can expect to see the following behavior when scaling migrated machine sets:
++
+--
+. Start with a compute machine set with existing machines.
+. Migrate the machine set to use a different authoritative API.
+. Scale the now authoritative machine set up by setting a larger value in the `.spec.replicas` field.
+. The machine set creates machines with the current authoritative API to satisfy the number of requested replicas.
+. Scale the authoritative machine set down such that one of the following conditions causes the deletion of machines that do not use the current authoritative API:
+** The total number of replicas requested is fewer than the number of machines that do not use the current authoritative API.
+** The machine deletion policy for the machine set selects machines that do not use the current authoritative API.
+. Check the status of the nonauthoritative compute machine set by running the `oc get` command.
+** The value in the `DESIRED` column in the output reflects the `.spec.replicas` value.
+** The values in the `CURRENT`, `READY`, and `AVAILABLE` columns reflect the original number of replicas that existed before scaling the machine set.
+--
+
+Workaround::
+
+To verify that a scale-down operation successfully deleted the compute machines that do not use the current authoritative API, run the `oc get` command that lists the nonauthoritative compute machines.
+
+Result::
+
+If the scale-down operation succeeded, the count in the output of the `oc get` command for the nonauthoritative compute machines reflects the `.spec.replicas` value of the machine set.
+
+//OCPCLOUD-2994
+//OCPCLOUD-2995