Skip to content

Commit a9b5386

Browse files
jeana-redhatjeana-redhat
authored
Merge pull request #93633 from jeana-redhat/OSDOCS-14521-MAPI-CAPI-conversion
OSDOCS-14521: Migrating between MAPI and CAPI resources
2 parents 4dca81b + a030e49 commit a9b5386

File tree

7 files changed

+423
-8
lines changed

7 files changed

+423
-8
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2425,8 +2425,8 @@ Topics:
24252425
# File: cluster-api-resiliency
24262426
- Name: Troubleshooting Cluster API clusters
24272427
File: cluster-api-troubleshooting
2428-
# - Name: Disabling Cluster API machine sets
2429-
# File: cluster-api-disabling
2428+
- Name: Disabling the Cluster API
2429+
File: cluster-api-disabling
24302430
- Name: Deploying machine health checks
24312431
File: deploying-machine-health-checks
24322432
---

‎machine_management/cluster_api_machine_management/cluster-api-disabling.adoc

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,23 @@
11
:_mod-docs-content-type: ASSEMBLY
22
[id="cluster-api-disabling"]
3-
= Disabling Cluster API machine sets
3+
= Disabling the Cluster API
44
include::_attributes/common-attributes.adoc[]
55
:context: cluster-api-disabling
66

77
toc::[]
88

9+
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.
10+
911
:FeatureName: Managing machines with the Cluster API
1012
include::snippets/technology-preview.adoc[]
1113

12-
//Placeholder assembly, commented out in the topic map.
13-
//how to disable, clean up, verify, and reenable
14+
//Migrating Cluster API resources to Machine API resources
15+
include::modules/mapi-capi-migration-overview.adoc[leveloffset=+1]
16+
17+
//Migrating a Cluster API resource to use the Machine API
18+
include::modules/migrating-between-capi-mapi.adoc[leveloffset=+2]
19+
20+
[role="_additional-resources"]
21+
.Additional resources
22+
// * xr3f:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-resource-migration_cluster-api-troubleshooting[Troubleshooting resource migration]
23+
* 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]

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

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,33 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9+
The Machine API and Cluster API are distinct API groups that have similar resources.
10+
You can use these API groups to automate the management of infrastructure resources on your {product-title} cluster.
11+
912
:FeatureName: Managing machines with the Cluster API
1013
include::snippets/technology-preview.adoc[]
1114

12-
For the Cluster API Technology Preview, you must manually create some of the primary resources that the Cluster API requires.
15+
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
16+
17+
* One control plane machine set that manages three control plane machines.
18+
* One or more compute machine sets that manage three compute machines.
19+
* One machine health check that manages spot instances.
20+
21+
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:
22+
23+
* One cluster resource.
24+
* One provider-specific infrastructure cluster resource.
25+
26+
On clusters that support migrating Machine API resources to Cluster API resources, a two-way synchronization controller creates these primary resources automatically.
27+
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].
1328

1429
[id="creating-primary-resources_{context}"]
1530
== Creating the Cluster API primary resources
1631

17-
You can create the Cluster API primary resources manually by creating YAML manifest files and applying them with the {oc-first}.
32+
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:
33+
34+
* One or more machine templates that correspond to compute machine sets.
35+
* One or more compute machine sets that manage three compute machines.
1836

1937
//Creating a Cluster API machine template
2038
include::modules/capi-creating-machine-template.adoc[leveloffset=+2]
@@ -36,4 +54,18 @@ include::modules/capi-creating-machine-set.adoc[leveloffset=+2]
3654
* 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}]
3755
* 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}]
3856
* 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}]
39-
* 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]
57+
* 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]
58+
59+
//Migrating Machine API resources to Cluster API resources
60+
include::modules/capi-mapi-migration-overview.adoc[leveloffset=+1]
61+
62+
//Migrating a Machine API resource to use the Cluster API
63+
include::modules/migrating-between-capi-mapi.adoc[leveloffset=+2]
64+
65+
//Deploying Cluster API compute machines by using a Machine API compute machine set
66+
include::modules/deploying-capi-machines-via-mapi-machine-sets.adoc[leveloffset=+2]
67+
68+
[role="_additional-resources"]
69+
.Additional resources
70+
//* xr3f:../../machine_management/cluster_api_machine_management/cluster-api-troubleshooting.adoc#ts-capi-resource-migration_cluster-api-troubleshooting[Troubleshooting resource migration]
71+
* 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]

‎modules/capi-mapi-migration-overview.adoc

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="capi-mapi-migration-overview_{context}"]
7+
= Migrating Machine API resources to Cluster API resources
8+
9+
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:
10+
11+
* One or more machine templates that correspond to compute machine sets.
12+
* One or more compute machine sets that manage three compute machines.
13+
* One or more Cluster API compute machines that correspond to each Machine API compute machine.
14+
15+
[NOTE]
16+
====
17+
The two-way synchronization controller only operates on clusters with the `MachineAPIMigration` feature gate in the `TechPreviewNoUpgrade` feature set enabled.
18+
====
19+
20+
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.
21+
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.
22+
The synchronization controller creates the Cluster API resources in an unprovisioned (`Paused`) state to prevent unintended reconciliation.
23+
24+
For supported configurations, you can migrate a Machine API resource to the equivalent Cluster API resource by changing which API it considers authoritative.
25+
When you migrate a Machine API resources to the Cluster API, you transfer management of the resource to the Cluster API.
26+
27+
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.
28+
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.
29+
30+
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.
31+
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.
32+
33+
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.
34+
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.
35+
36+
[NOTE]
37+
====
38+
You can only migrate some resources on supported infrastructure types.
39+
====
40+
41+
.Supported resource conversions
42+
[cols="6",options="header"]
43+
|===
44+
|Infrastructure
45+
|Compute machine
46+
|Compute machine set
47+
|Machine health check
48+
|Control plane machine set
49+
|Cluster autoscaler
50+
51+
|{aws-short}
52+
|Technology Preview
53+
|Technology Preview
54+
|Not Available
55+
|Not Available
56+
|Not Available
57+
58+
|All other infrastructure types
59+
|Not Available
60+
|Not Available
61+
|Not Available
62+
|Not Available
63+
|Not Available
64+
|===

‎modules/deploying-capi-machines-via-mapi-machine-sets.adoc

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * machine_management/cluster_api_machine_management/cluster-api-getting-started.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="deploying-capi-machines-via-mapi-machine-sets_{context}"]
7+
= Deploying Cluster API compute machines by using a Machine API compute machine set
8+
9+
You can configure a Machine API compute machine set to deploy Cluster API compute machines.
10+
With this process, you can test the Cluster API compute machine creation workflow without creating and scaling a Cluster API compute machine set.
11+
12+
A Machine API compute machine set with this configuration creates nonauthoritative Machine API compute machines that use the Cluster API as authoritative.
13+
The two-way synchronization controller then creates corresponding authoritative Cluster API machines that provision on the underlying infrastructure.
14+
15+
:FeatureName: Deploying Cluster API compute machines by using a Machine API compute machine set
16+
include::snippets/technology-preview.adoc[]
17+
18+
.Prerequisites
19+
20+
* You have deployed an {product-title} cluster on a supported infrastructure type.
21+
22+
* You have enabled the use of the Cluster API.
23+
24+
* You have enabled the `MachineAPIMigration` feature gate in the `TechPreviewNoUpgrade` feature set.
25+
26+
* You have access to the cluster using an account with `cluster-admin` permissions.
27+
28+
* You have installed the {oc-first}.
29+
30+
.Procedure
31+
32+
. List the Machine API compute machine sets in your cluster by running the following command:
33+
+
34+
[source,terminal,subs="attributes+"]
35+
----
36+
$ oc get machineset.machine.openshift.io -n openshift-machine-api
37+
----
38+
39+
. Edit the resource specification by running the following command:
40+
+
41+
[source,terminal]
42+
----
43+
$ oc edit machineset.machine.openshift.io <machine_set_name> \
44+
-n openshift-machine-api
45+
----
46+
+
47+
where `<machine_set_name>` is the name of the Machine API compute machine set that you want to configure to deploy Cluster API compute machines.
48+
49+
. In the resource specification, update the value of the `spec.template.spec.authoritativeAPI` field:
50+
+
51+
[source,yaml,subs="attributes+"]
52+
----
53+
apiVersion: machine.openshift.io/v1beta1
54+
kind: MachineSet
55+
metadata:
56+
[...]
57+
name: <machine_set_name>
58+
[...]
59+
spec:
60+
authoritativeAPI: MachineAPI <1>
61+
[...]
62+
template:
63+
[...]
64+
spec:
65+
authoritativeAPI: ClusterAPI <2>
66+
status:
67+
authoritativeAPI: MachineAPI <3>
68+
[...]
69+
----
70+
<1> The unconverted value for the Machine API compute machine set.
71+
Do not change the value in this part of the specification.
72+
<2> Specify `ClusterAPI` to configure the compute machine set to deploy Cluster API compute machines.
73+
<3> The current value for the Machine API compute machine set.
74+
Do not change the value in this part of the specification.
75+
76+
.Verification
77+
78+
. List the machines that are managed by the updated compute machine set by running the following command:
79+
+
80+
[source,terminal]
81+
----
82+
$ oc get machines.machine.openshift.io \
83+
-n openshift-machine-api \
84+
-l machine.openshift.io/cluster-api-machineset=<machine_set_name>
85+
----
86+
87+
. 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:
88+
+
89+
[source,terminal]
90+
----
91+
$ oc describe machines.machine.openshift.io <machine_name> \
92+
-n openshift-machine-api
93+
----
94+
+
95+
For a Cluster API compute machine, the value of the field is `ClusterAPI`.

‎modules/mapi-capi-migration-overview.adoc

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * machine_management/cluster_api_machine_management/cluster-api-disabling.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="mapi-capi-migration-overview_{context}"]
7+
= Migrating Cluster API resources to Machine API resources
8+
9+
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.
10+
11+
[NOTE]
12+
====
13+
The two-way synchronization controller only operates on clusters with the `MachineAPIMigration` feature gate in the `TechPreviewNoUpgrade` feature set enabled.
14+
====
15+
16+
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.
17+
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.
18+
19+
[NOTE]
20+
====
21+
You can only migrate some resources on supported infrastructure types.
22+
====
23+
24+
.Supported resource conversions
25+
[cols="6",options="header"]
26+
|===
27+
|Infrastructure
28+
|Compute machine
29+
|Compute machine set
30+
|Machine health check
31+
|Control plane machine set
32+
|Cluster autoscaler
33+
34+
|{aws-short}
35+
|Technology Preview
36+
|Technology Preview
37+
|Not Available
38+
|Not Available
39+
|Not Available
40+
41+
|All other infrastructure types
42+
|Not Available
43+
|Not Available
44+
|Not Available
45+
|Not Available
46+
|Not Available
47+
|===

0 commit comments

Comments
 (0)