openshift-docs/modules/migrating-between-capi-mapi.adoc

// 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 <resource_kind> -n {from-namespace}
----
+
--
where `<resource_kind>` 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 <resource_kind>/<resource_name> -n openshift-machine-api
----
+
--
where:

`<resource_kind>`:: Specifies a compute machine with `machine.machine.openshift.io` or compute machine set with `machineset.machine.openshift.io`.
ifdef::machine-to-cluster[]
`<resource_name>`:: Specifies the name of the Machine API resource that you want to migrate to a Cluster API resource.
endif::[]
ifdef::cluster-to-machine[]
`<resource_name>`:: 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: <resource_kind>
metadata:
  name: <resource_name>
  [...]
spec:
  authoritativeAPI: {to-api-value}
  [...]
status:
  authoritativeAPI: {from-api-value}
  [...]
----
+
--
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`.
`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}`.
`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

* Check the status of the conversion by running the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc -n openshift-machine-api get <resource_kind>/<resource_name> -o json | jq .status.authoritativeAPI
----
+
--
where:

`<resource_kind>`:: Specifies a compute machine with `machine.machine.openshift.io` or compute machine set with `machineset.machine.openshift.io`.
ifdef::machine-to-cluster[]
`<resource_name>`:: Specifies the name of the Machine API resource that you want to migrate to a Cluster API resource.
endif::[]
ifdef::cluster-to-machine[]
`<resource_name>`:: 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 migration_ 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::[]