From 2724b561f841cbc892e3086a227aa39459dea239 Mon Sep 17 00:00:00 2001 From: Jeana Routh Date: Thu, 1 May 2025 14:26:58 -0400 Subject: [PATCH] OSDOCS-14521: Converting between MAPI and CAPI resources --- _topic_maps/_topic_map.yml | 4 +- .../cluster-api-disabling.adoc | 16 +- .../cluster-api-getting-started.adoc | 38 +++- modules/capi-mapi-migration-overview.adoc | 64 +++++++ ...g-capi-machines-via-mapi-machine-sets.adoc | 95 ++++++++++ modules/mapi-capi-migration-overview.adoc | 47 +++++ modules/migrating-between-capi-mapi.adoc | 167 ++++++++++++++++++ 7 files changed, 423 insertions(+), 8 deletions(-) create mode 100644 modules/capi-mapi-migration-overview.adoc create mode 100644 modules/deploying-capi-machines-via-mapi-machine-sets.adoc create mode 100644 modules/mapi-capi-migration-overview.adoc create mode 100644 modules/migrating-between-capi-mapi.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 7275296bbc..01f350ebbc 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2424,8 +2424,8 @@ Topics: # File: cluster-api-resiliency - Name: Troubleshooting Cluster API clusters File: cluster-api-troubleshooting -# - Name: Disabling Cluster API machine sets -# File: cluster-api-disabling + - Name: Disabling the Cluster API + File: cluster-api-disabling - Name: Deploying machine health checks File: deploying-machine-health-checks --- 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 9161919b9e..126593070e 100644 --- a/machine_management/cluster_api_machine_management/cluster-api-disabling.adoc +++ b/machine_management/cluster_api_machine_management/cluster-api-disabling.adoc @@ -1,13 +1,23 @@ :_mod-docs-content-type: ASSEMBLY [id="cluster-api-disabling"] -= Disabling Cluster API machine sets += Disabling the Cluster API include::_attributes/common-attributes.adoc[] :context: cluster-api-disabling toc::[] +To stop using the Cluster API to automate the management of infrastructure resources on your {product-title} cluster, convert any Cluster API resources on your cluster to equivalent Machine API resources. + :FeatureName: Managing machines with the Cluster API include::snippets/technology-preview.adoc[] -//Placeholder assembly, commented out in the topic map. -//how to disable, clean up, verify, and reenable \ No newline at end of file +//Migrating Cluster API resources to Machine API resources +include::modules/mapi-capi-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 +// * 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] \ No newline at end of file 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 0ef0e56cd4..d3bd2bb953 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 @@ -6,15 +6,33 @@ include::_attributes/common-attributes.adoc[] toc::[] +The Machine API and Cluster API are distinct API groups that have similar resources. +You can use these API groups to automate the management of infrastructure resources on your {product-title} cluster. + :FeatureName: Managing machines with the Cluster API include::snippets/technology-preview.adoc[] -For the Cluster API Technology Preview, you must manually create some of the primary resources that the Cluster API requires. +When you install a standard {product-title} cluster that has three control plane nodes, three compute nodes, and uses the default configuration options, the installation program provisions the following infrastructure resources in the `openshift-machine-api` namespace + +* One control plane machine set that manages three control plane machines. +* One or more compute machine sets that manage three compute machines. +* One machine health check that manages spot instances. + +When you install a cluster that supports managing infrastructure resources with the Cluster API, the installation program provisions the following resources in the `openshift-cluster-api` namespace: + +* One cluster resource. +* 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]. [id="creating-primary-resources_{context}"] == Creating the Cluster API primary resources -You can create the Cluster API primary resources manually by creating YAML manifest files and applying them with the {oc-first}. +For clusters that do not support migrating Machine API resources to Cluster API resources, you must manually create the following Cluster API resources in the `openshift-cluster-api` namespace: + +* One or more machine templates that correspond to compute machine sets. +* One or more compute machine sets that manage three compute machines. //Creating a Cluster API machine template include::modules/capi-creating-machine-template.adoc[leveloffset=+2] @@ -36,4 +54,18 @@ include::modules/capi-creating-machine-set.adoc[leveloffset=+2] * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-azure.adoc#capi-yaml-machine-set-azure_cluster-api-config-options-azure[Sample YAML for a Cluster API compute machine set resource on {azure-full}] * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-rhosp.adoc#capi-yaml-machine-set-rhosp_cluster-api-config-options-rhosp[Sample YAML for a Cluster API compute machine set resource on {rh-openstack}] * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-vsphere.adoc#capi-yaml-machine-set-vsphere_cluster-api-config-options-vsphere[Sample YAML for a Cluster API compute machine set resource on {vmw-full}] -* 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] \ No newline at end of file +* 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] + +//Migrating a Machine API resource to use the Cluster API +include::modules/migrating-between-capi-mapi.adoc[leveloffset=+2] + +//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] + +[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] diff --git a/modules/capi-mapi-migration-overview.adoc b/modules/capi-mapi-migration-overview.adoc new file mode 100644 index 0000000000..93c1fda2f5 --- /dev/null +++ b/modules/capi-mapi-migration-overview.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc + +:_mod-docs-content-type: CONCEPT +[id="capi-mapi-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: + +* One or more machine templates that correspond to compute machine sets. +* One or more compute machine sets that manage three compute machines. +* One or more Cluster API compute machines that correspond to each Machine API compute machine. + +[NOTE] +==== +The two-way synchronization controller only operates on clusters with the `MachineAPIMigration` feature gate in the `TechPreviewNoUpgrade` feature set enabled. +==== + +These Cluster API resources correspond to the resources that the installation program provisions in the `openshift-machine-api` namespace for a cluster that uses the default configuration options. +The Cluster API resources have the same names as their Machine API counterparts and appear in the output of commands, such as `oc get`, that list resources. +The synchronization controller creates the Cluster API resources in an unprovisioned (`Paused`) state to prevent unintended reconciliation. + +For supported configurations, you can migrate a Machine API resource to the equivalent Cluster API resource by changing which API it considers authoritative. +When you migrate a Machine API resources to the Cluster API, you transfer management of the resource to the Cluster API. + +By migrating a Machine API resource to use the Cluster API, you can verify that everything works as expected before deciding to use the Cluster API in production clusters. +After migrating a Machine API resource to an equivalent Cluster API resource, you can examine the new resource to verify that the features and configuration match the original Machine API resource. + +When you change the authoritative API for a compute machine set, any existing compute machines that the compute machine set manages retain their original authoritative API. +As a result, a compute machine set that manages machines that use different authoritative APIs is a valid and expected occurrence in clusters that support migrating between these API types. + +When you change the authoritative API for a compute machine, the instance on the underlying infrastructure that backs the machine is not recreated or reprovisioned. +In-place changes, such as modifying labels, tags, taints, or annotations, are the only changes that the API group can make to the underlying instance that backs the machine. + +[NOTE] +==== +You can only migrate some resources on supported infrastructure types. +==== + +.Supported resource conversions +[cols="6",options="header"] +|=== +|Infrastructure +|Compute machine +|Compute machine set +|Machine health check +|Control plane machine set +|Cluster autoscaler + +|{aws-short} +|Technology Preview +|Technology Preview +|Not Available +|Not Available +|Not Available + +|All other infrastructure types +|Not Available +|Not Available +|Not Available +|Not Available +|Not Available +|=== \ No newline at end of file diff --git a/modules/deploying-capi-machines-via-mapi-machine-sets.adoc b/modules/deploying-capi-machines-via-mapi-machine-sets.adoc new file mode 100644 index 0000000000..4131dc225a --- /dev/null +++ b/modules/deploying-capi-machines-via-mapi-machine-sets.adoc @@ -0,0 +1,95 @@ +// Module included in the following assemblies: +// +// * machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="deploying-capi-machines-via-mapi-machine-sets_{context}"] += Deploying Cluster API compute machines by using a Machine API compute machine set + +You can configure a Machine API compute machine set to deploy Cluster API compute machines. +With this process, you can test the Cluster API compute machine creation workflow without creating and scaling a Cluster API compute machine set. + +A Machine API compute machine set with this configuration creates nonauthoritative Machine API compute machines that use the Cluster API as authoritative. +The two-way synchronization controller then creates corresponding authoritative Cluster API machines that provision on the underlying infrastructure. + +:FeatureName: Deploying Cluster API compute machines by using a Machine API compute machine set +include::snippets/technology-preview.adoc[] + +.Prerequisites + +* You have deployed an {product-title} cluster on a supported infrastructure type. + +* You have enabled the use of the Cluster API. + +* You have enabled the `MachineAPIMigration` feature gate in the `TechPreviewNoUpgrade` feature set. + +* You have access to the cluster using an account with `cluster-admin` permissions. + +* You have installed the {oc-first}. + +.Procedure + +. List the Machine API compute machine sets in your cluster by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ oc get machineset.machine.openshift.io -n openshift-machine-api +---- + +. Edit the resource specification by running the following command: ++ +[source,terminal] +---- +$ oc edit machineset.machine.openshift.io \ + -n openshift-machine-api +---- ++ +where `` is the name of the Machine API compute machine set that you want to configure to deploy Cluster API compute machines. + +. In the resource specification, update the value of the `spec.template.spec.authoritativeAPI` field: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: machine.openshift.io/v1beta1 +kind: MachineSet +metadata: + [...] + name: + [...] +spec: + authoritativeAPI: MachineAPI <1> + [...] + template: + [...] + spec: + authoritativeAPI: ClusterAPI <2> +status: + authoritativeAPI: MachineAPI <3> + [...] +---- +<1> The unconverted value for the Machine API compute machine set. +Do not change the value in this part of the specification. +<2> Specify `ClusterAPI` to configure the compute machine set to deploy Cluster API compute machines. +<3> The current value for the Machine API compute machine set. +Do not change the value in this part of the specification. + +.Verification + +. List the machines that are managed by the updated compute machine set by running the following command: ++ +[source,terminal] +---- +$ oc get machines.machine.openshift.io \ + -n openshift-machine-api \ + -l machine.openshift.io/cluster-api-machineset= +---- + +. To verify that a machine created by the updated machine set has the correct configuration, examine the `status.authoritativeAPI` field in the CR for one of the new machines by running the following command: ++ +[source,terminal] +---- +$ oc describe machines.machine.openshift.io \ + -n openshift-machine-api +---- ++ +For a Cluster API compute machine, the value of the field is `ClusterAPI`. diff --git a/modules/mapi-capi-migration-overview.adoc b/modules/mapi-capi-migration-overview.adoc new file mode 100644 index 0000000000..4ad60f3f6f --- /dev/null +++ b/modules/mapi-capi-migration-overview.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * machine_management/cluster_api_machine_management/cluster-api-disabling.adoc + +:_mod-docs-content-type: CONCEPT +[id="mapi-capi-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. + +[NOTE] +==== +The two-way synchronization controller only operates on clusters with the `MachineAPIMigration` feature gate in the `TechPreviewNoUpgrade` feature set enabled. +==== + +You can migrate resources that you originally migrated from the Machine API to the Cluster API, or resources that you created as Cluster API resources initially. +Migrating an original Machine API resource to a Cluster API resource and then migrating it back provides an opportunity to verify that the migration process works as expected. + +[NOTE] +==== +You can only migrate some resources on supported infrastructure types. +==== + +.Supported resource conversions +[cols="6",options="header"] +|=== +|Infrastructure +|Compute machine +|Compute machine set +|Machine health check +|Control plane machine set +|Cluster autoscaler + +|{aws-short} +|Technology Preview +|Technology Preview +|Not Available +|Not Available +|Not Available + +|All other infrastructure types +|Not Available +|Not Available +|Not Available +|Not Available +|Not Available +|=== \ No newline at end of file diff --git a/modules/migrating-between-capi-mapi.adoc b/modules/migrating-between-capi-mapi.adoc new file mode 100644 index 0000000000..8524a11d21 --- /dev/null +++ b/modules/migrating-between-capi-mapi.adoc @@ -0,0 +1,167 @@ +// 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 + +ifeval::["{context}" == "cluster-api-getting-started"] +:machine-to-cluster: +endif::[] +ifeval::["{context}" == "cluster-api-disabling"] +:cluster-to-machine: +endif::[] + +ifdef::machine-to-cluster[] +:from-api-name: Machine API +:to-api-name: Cluster API +:from-api-value: MachineAPI +:to-api-value: ClusterAPI +:from-api-group: machine.openshift.io +:to-api-group: cluster.x-k8s.io +:from-namespace: openshift-machine-api +endif::[] + +ifdef::cluster-to-machine[] +:from-api-name: Cluster API +:to-api-name: Machine API +:from-api-value: ClusterAPI +:to-api-value: MachineAPI +:from-api-group: cluster.x-k8s.io +:to-api-group: machine.openshift.io +:from-namespace: openshift-cluster-api +endif::[] + +:_mod-docs-content-type: PROCEDURE +[id="migrating-between-capi-mapi_{context}"] += Migrating a {from-api-name} resource to use the {to-api-name} + +You can migrate individual {from-api-name} objects to equivalent {to-api-name} objects. + +:FeatureName: Migrating a {from-api-name} resource to use the {to-api-name} +include::snippets/technology-preview.adoc[] + +.Prerequisites + +* You have deployed an {product-title} cluster on a supported infrastructure type. + +ifdef::machine-to-cluster[] +* You have enabled the use of the Cluster API. +endif::[] + +* You have enabled the `MachineAPIMigration` feature gate in the `TechPreviewNoUpgrade` feature set. + +* You have access to the cluster using an account with `cluster-admin` permissions. + +* You have installed the {oc-first}. + +.Procedure + +. Identify the {from-api-name} resource that you want to migrate to a {to-api-name} resource by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ oc get -n {from-namespace} +---- ++ +-- +where `` is one of the following values: + +`machine.{from-api-group}`:: The fully qualified name of the resource kind for a compute or control plane machine. + +`machineset.{from-api-group}`:: The fully qualified name of the resource kind for a compute machine set. +-- + +. Edit the resource specification by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ oc edit / -n openshift-machine-api +---- ++ +-- +where: + +``:: Specifies a compute machine with `machine.machine.openshift.io` or compute machine set with `machineset.machine.openshift.io`. +ifdef::machine-to-cluster[] +``:: Specifies the name of the Machine API resource that you want to migrate to a Cluster API resource. +endif::[] +ifdef::cluster-to-machine[] +``:: Specifies the name of the Machine API resource that corresponds to the Cluster API resource that you want to migrate to the Machine API. +endif::[] +-- + +. In the resource specification, update the value of the `spec.authoritativeAPI` field: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: machine.openshift.io/v1beta1 +kind: <1> +metadata: + name: <2> + [...] +spec: + authoritativeAPI: {to-api-value} <3> + [...] +status: + authoritativeAPI: {from-api-value} <4> + [...] +---- +<1> The resource kind varies depending on the resource kind. +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. +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. +This value indicates which API currently manages this resource. +Do not change the value in this part of the specification. + +.Verification + +* Check the status of the conversion by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ oc -n openshift-machine-api get / -o json | jq .status.authoritativeAPI +---- ++ +-- +where: + +``:: Specifies a compute machine with `machine.machine.openshift.io` or compute machine set with `machineset.machine.openshift.io`. +ifdef::machine-to-cluster[] +``:: Specifies the name of the Machine API resource that you want to migrate to a Cluster API resource. +endif::[] +ifdef::cluster-to-machine[] +``:: Specifies the name of the Machine API resource that corresponds to the Cluster API resource that you want to migrate to the Machine API. +endif::[] +-- ++ +-- +* While the conversion progresses, this command returns a value of `Migrating`. +If this value persists for a long time, check the logs for the `cluster-capi-operator` deployment in the `openshift-cluster-api` namespace for more information and to identify potential issues. +* When the conversion is complete, this command returns a value of `{to-api-value}`. +-- ++ +ifdef::cluster-to-machine[] +[IMPORTANT] +==== +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. +==== +endif::[] + +:!from-api-name: +:!to-api-name: +:!from-api-value: +:!to-api-value: +:!from-api-group: +:!to-api-group: +:!from-namespace: + +ifeval::["{context}" == "cluster-api-getting-started"] +:!machine-to-cluster: +endif::[] +ifeval::["{context}" == "cluster-api-disabling"] +:!cluster-to-machine: +endif::[]