From 1b2b8de11f2a355f53b43a38c5f4b60a09102988 Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Fri, 26 Jun 2026 14:21:21 +0100 Subject: [PATCH] OSDOCS-17045-2: CQA 1 for MACH-4 Cluster API for Compute Machines --- .../cluster-api-getting-started.adoc | 8 ++++- .../cluster-api-config-options-azure.adoc | 8 ++--- modules/capi-creating-machine-set.adoc | 23 ++++++++------- modules/capi-creating-machine-template.adoc | 24 ++++++++------- modules/capi-yaml-machine-set-azure.adoc | 22 ++++++++------ modules/capi-yaml-machine-template-azure.adoc | 26 ++++++++++------- ...g-capi-machines-via-mapi-machine-sets.adoc | 24 ++++++++------- ...achine-set-authoritative-api-machines.adoc | 3 +- modules/mapi-to-capi-migration-overview.adoc | 9 ++++-- modules/migrating-between-capi-mapi.adoc | 29 +++++-------------- 10 files changed, 92 insertions(+), 84 deletions(-) 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 a0e68bc6cef3..104661ec4600 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,6 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] 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. @@ -24,7 +25,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#mapi-to-capi-migration-overview_cluster-api-getting-started[Migrating Machine API resources to Cluster API resources]. +For more information, see "Migrating Machine API resources to Cluster API resources". [id="creating-primary-resources_{context}"] == Creating the Cluster API primary resources @@ -39,6 +40,8 @@ include::modules/capi-creating-machine-template.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources + +* 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] * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-template-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API machine template resource on {aws-full}] * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-template-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API machine template resource on {gcp-full}] * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-azure.adoc#capi-yaml-machine-template-azure_cluster-api-config-options-azure[Sample YAML for a Cluster API machine template resource on {azure-full}] @@ -51,6 +54,7 @@ include::modules/capi-creating-machine-set.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources + * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc#capi-yaml-machine-set-aws_cluster-api-config-options-aws[Sample YAML for a Cluster API compute machine set resource on {aws-full}] * xref:../../machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-gcp.adoc#capi-yaml-machine-set-gcp_cluster-api-config-options-gcp[Sample YAML for a Cluster API compute machine set resource on {gcp-full}] * 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}] @@ -69,6 +73,7 @@ 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 @@ -76,5 +81,6 @@ include::modules/deploying-capi-machines-via-mapi-machine-sets.adoc[leveloffset= [role="_additional-resources"] .Additional 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] diff --git a/machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-azure.adoc b/machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-azure.adoc index de7120be8683..bde00e346b09 100644 --- a/machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-azure.adoc +++ b/machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-azure.adoc @@ -6,21 +6,19 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] You can change the configuration of your {azure-first} Cluster API machines by updating values in the Cluster API custom resource manifests. :FeatureName: Managing machines with the Cluster API include::snippets/technology-preview.adoc[] -[id="cluster-api-sample-yaml-azure_{context}"] -== Sample YAML for configuring {azure-full} clusters - The following example YAML files show configurations for an {azure-short} cluster. //Sample YAML for CAPI Azure machine template resource -include::modules/capi-yaml-machine-template-azure.adoc[leveloffset=+2] +include::modules/capi-yaml-machine-template-azure.adoc[leveloffset=+1] //Sample YAML for a CAPI Azure compute machine set resource -include::modules/capi-yaml-machine-set-azure.adoc[leveloffset=+2] +include::modules/capi-yaml-machine-set-azure.adoc[leveloffset=+1] // [id="cluster-api-supported-features-azure_{context}"] // == Enabling {azure-full} features with the Cluster API diff --git a/modules/capi-creating-machine-set.adoc b/modules/capi-creating-machine-set.adoc index 67fee8270bd9..9e1c2a821cc2 100644 --- a/modules/capi-creating-machine-set.adoc +++ b/modules/capi-creating-machine-set.adoc @@ -6,6 +6,7 @@ [id="capi-creating-machine-set_{context}"] = Creating a Cluster API compute machine set +[role="_abstract"] You can create compute machine sets that use the Cluster API to dynamically manage the machine compute resources for specific workloads of your choice. .Prerequisites @@ -24,16 +25,15 @@ You can create compute machine sets that use the Cluster API to dynamically mana . Create a YAML file similar to the following. This procedure uses `.yaml` as an example file name. + --- [source,yaml] ---- apiVersion: cluster.x-k8s.io/v1beta1 kind: MachineSet metadata: - name: # <1> + name: namespace: openshift-cluster-api spec: - clusterName: # <2> + clusterName: replicas: 1 selector: matchLabels: @@ -42,12 +42,15 @@ spec: metadata: labels: test: example - spec: # <3> + spec: # ... ---- -<1> Specify a name for the compute machine set. ++ +where: + +`metadata.name`:: Specifies a name for the compute machine set. The cluster ID, machine role, and region form a typical pattern for this value in the following format: `--`. -<2> Specify the name of the cluster. +`spec.clusterName`:: Specifies the name of the cluster. Obtain the value of the cluster ID by running the following command: + [source,terminal] @@ -55,8 +58,8 @@ Obtain the value of the cluster ID by running the following command: $ oc get infrastructure cluster \ -o jsonpath='{.status.infrastructureName}' ---- -<3> Specify the details for your environment. These parameters are provider specific. For more information, see the sample Cluster API compute machine set YAML for your provider. --- ++ +`spec.template.spec`:: Specifies the details for your environment. These parameters are provider specific. For more information, see the sample Cluster API compute machine set YAML for your provider. . Create the compute machine set CR by running the following command: + @@ -84,7 +87,7 @@ When the new compute machine set is available, the `REPLICAS` and `AVAILABLE` va .Verification * To verify that the compute machine set is creating machines according to your required configuration, review the lists of machines and nodes in the cluster by running the following commands: - ++ ** View the list of Cluster API machines: + [source,terminal] @@ -98,7 +101,7 @@ $ oc get machine.cluster.x-k8s.io -n openshift-cluster-api NAME CLUSTER NODENAME PROVIDERID PHASE AGE VERSION - ..compute.internal Running 8m23s ---- - ++ ** View the list of nodes: + [source,terminal] diff --git a/modules/capi-creating-machine-template.adoc b/modules/capi-creating-machine-template.adoc index 783f150b0fc8..28ae254f7105 100644 --- a/modules/capi-creating-machine-template.adoc +++ b/modules/capi-creating-machine-template.adoc @@ -6,6 +6,7 @@ [id="capi-creating-machine-template_{context}"] = Creating a Cluster API machine template +[role="_abstract"] You can create a provider-specific machine template resource by creating a YAML manifest file and applying it with the {oc-first}. .Prerequisites @@ -20,21 +21,21 @@ You can create a provider-specific machine template resource by creating a YAML .Procedure -. Create a YAML file similar to the following. This procedure uses `.yaml` as an example file name. +. Create a YAML file similar to the following example. This procedure uses `.yaml` as an example file name. + --- [source,yaml] ---- apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 -kind: # <1> +kind: metadata: - name: # <2> + name: namespace: openshift-cluster-api spec: template: - spec: # <3> + spec: ---- -<1> Specify the machine template kind. This value must match the value for your platform. ++ +`kind`: Specifies the machine template kind. This value must match the value for your platform. The following values are valid: + |==== @@ -59,9 +60,10 @@ The following values are valid: |`Metal3MachineTemplate` |==== -<2> Specify a name for the machine template. -<3> Specify the details for your environment. These parameters are provider specific. For more information, see the sample Cluster API machine template YAML for your provider. --- ++ +`metadata.name`: Specifies a name for the machine template. ++ +`spec.template.spec`: Specifies the details for your environment. These parameters are provider specific. For more information, see the sample Cluster API machine template YAML for your provider. . Create the machine template CR by running the following command: + @@ -79,11 +81,11 @@ $ oc create -f .yaml $ oc get -n openshift-cluster-api ---- + -where `` is the value that corresponds to your platform. +``: Specifies the value that corresponds to your platform. + .Example output [source,text] ---- NAME AGE 77m ----- \ No newline at end of file +---- diff --git a/modules/capi-yaml-machine-set-azure.adoc b/modules/capi-yaml-machine-set-azure.adoc index 566ac534d919..d20eb31feedd 100644 --- a/modules/capi-yaml-machine-set-azure.adoc +++ b/modules/capi-yaml-machine-set-azure.adoc @@ -6,6 +6,7 @@ [id="capi-yaml-machine-set-azure_{context}"] = Sample YAML for a Cluster API compute machine set resource on {azure-full} +[role="_abstract"] The compute machine set resource defines additional properties of the machines that it creates. The compute machine set also references the cluster resource and machine template when creating machines. @@ -14,10 +15,10 @@ The compute machine set also references the cluster resource and machine templat apiVersion: cluster.x-k8s.io/v1beta1 kind: MachineSet metadata: - name: # <1> + name: namespace: openshift-cluster-api labels: - cluster.x-k8s.io/cluster-name: # <2> + cluster.x-k8s.io/cluster-name: spec: clusterName: replicas: 1 @@ -35,16 +36,19 @@ spec: node-role.kubernetes.io/: "" spec: bootstrap: - dataSecretName: worker-user-data + dataSecretName: worker-user-data clusterName: infrastructureRef: apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 - kind: AzureMachineTemplate # <3> - name: # <4> + kind: AzureMachineTemplate + name: ---- -<1> Specify a name for the compute machine set. + +where: + +`metadata.name`:: Specifies a name for the compute machine set. The cluster ID, machine role, and region form a typical pattern for this value in the following format: `--`. -<2> Specify the cluster ID as the name of the cluster. -<3> Specify the machine template kind. +`metadata.labels.cluster.x-k8s.io/cluster-name`:: Specifies the cluster ID as the name of the cluster. +`spec.template.spec.infrastructureRef.kind`:: Specifies the machine template kind. This value must match the value for your platform. -<4> Specify the machine template name. \ No newline at end of file +`spec.template.spec.infrastructureRef.name`:: Specifies the machine template name. diff --git a/modules/capi-yaml-machine-template-azure.adoc b/modules/capi-yaml-machine-template-azure.adoc index 9121bd4766b2..e57011aea5ed 100644 --- a/modules/capi-yaml-machine-template-azure.adoc +++ b/modules/capi-yaml-machine-template-azure.adoc @@ -6,23 +6,24 @@ [id="capi-yaml-machine-template-azure_{context}"] = Sample YAML for a Cluster API machine template resource on {azure-full} +[role="_abstract"] The machine template resource is provider-specific and defines the basic properties of the machines that a compute machine set creates. The compute machine set references this template when creating machines. -[source,yaml] +[source,yaml,subs="+quotes"] ---- apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 -kind: AzureMachineTemplate # <1> +kind: AzureMachineTemplate metadata: - name: # <2> + name: namespace: openshift-cluster-api spec: template: - spec: # <3> + spec: disableExtensionOperations: true identity: UserAssigned image: - id: /subscriptions//resourceGroups/-rg/providers/Microsoft.Compute/galleries/gallery_/images/-gen2/versions/latest # <4> + id: /subscriptions//resourceGroups/-rg/providers/Microsoft.Compute/galleries/gallery_/images/-gen2/versions/latest networkInterfaces: - acceleratedNetworking: true privateIPConfigs: 1 @@ -37,14 +38,17 @@ spec: - providerID: 'azure:///subscriptions//resourcegroups/-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/-identity' vmSize: Standard_D4s_v3 ---- -<1> Specify the machine template kind. + +where: + +`kind`:: Specifies the machine template kind. This value must match the value for your platform. -<2> Specify a name for the machine template. -<3> Specify the details for your environment. +`metadata.name`:: Specifies a name for the machine template. +`spec.template.spec`:: Specifies the details for your environment. The values here are examples. -<4> Specify an image that is compatible with your instance type. +`spec.template.spec.image.id`:: Specifies an image that is compatible with your instance type. The Hyper-V generation V2 images created by the installation program have a `-gen2` suffix, while V1 images have the same name without the suffix. -+ + [NOTE] ==== Default {product-title} cluster names contain hyphens (`-`), which are not compatible with {azure-short} gallery name requirements. @@ -54,4 +58,4 @@ Other instances of `` do not change. For example, a cluster name of `jdoe-test-2m2np` transforms to `jdoe_test_2m2np`. The full string for `gallery_` in this example is `gallery_jdoe_test_2m2np`, not `gallery_jdoe-test-2m2np`. The complete value of `spec.template.spec.image.id` for this example value is `/subscriptions//resourceGroups/jdoe-test-2m2np-rg/providers/Microsoft.Compute/galleries/gallery_jdoe_test_2m2np/images/jdoe-test-2m2np-gen2/versions/latest`. -==== \ 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 index 4131dc225a4c..edd19d5ee672 100644 --- a/modules/deploying-capi-machines-via-mapi-machine-sets.adoc +++ b/modules/deploying-capi-machines-via-mapi-machine-sets.adoc @@ -6,8 +6,9 @@ [id="deploying-capi-machines-via-mapi-machine-sets_{context}"] = Deploying Cluster API compute machines by using a Machine API compute machine set +[role="_abstract"] 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. +Use 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. @@ -44,7 +45,7 @@ $ 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. +``: Specifies 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: + @@ -57,23 +58,24 @@ metadata: name: [...] spec: - authoritativeAPI: MachineAPI <1> + authoritativeAPI: MachineAPI [...] template: [...] spec: - authoritativeAPI: ClusterAPI <2> + authoritativeAPI: ClusterAPI status: - authoritativeAPI: MachineAPI <3> + authoritativeAPI: MachineAPI [...] ---- -<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. ++ +where: ++ +`spec.authoritativeAPI`:: Specifies the unconverted value for the Machine API compute machine set. Do not change the value in this part of the specification. +`spec.template.spec.authoritativeAPI`:: Specifies what `ClusterAPI` to configure the compute machine set to deploy Cluster API compute machines. +`status.authoritativeAPI`:: Specifies the current value for the Machine API compute machine set. Do not change the value in this part of the specification. -.Verification +.Verification . List the machines that are managed by the updated compute machine set by running the following command: + diff --git a/modules/machine-set-authoritative-api-machines.adoc b/modules/machine-set-authoritative-api-machines.adoc index a2c68af27916..c27c5be034d8 100644 --- a/modules/machine-set-authoritative-api-machines.adoc +++ b/modules/machine-set-authoritative-api-machines.adoc @@ -8,7 +8,8 @@ [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. +[role="_abstract"] +The authoritative API of a compute machine is determined by 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"] diff --git a/modules/mapi-to-capi-migration-overview.adoc b/modules/mapi-to-capi-migration-overview.adoc index 75b669a1cd9e..73f681655429 100644 --- a/modules/mapi-to-capi-migration-overview.adoc +++ b/modules/mapi-to-capi-migration-overview.adoc @@ -4,9 +4,12 @@ :_mod-docs-content-type: CONCEPT [id="mapi-to-capi-migration-overview_{context}"] -= Migrating Machine API resources to Cluster API resources += Machine API resources migration 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: +[role="_abstract"] +On clusters that support migrating Machine API resources to Cluster API resources, a two-way synchronization controller creates the Cluster API resources in the `openshift-cluster-api` namespace. + +These Cluster API resources are listed as follows: * One or more machine templates that correspond to compute machine sets. * One or more compute machine sets that manage three compute machines. @@ -61,4 +64,4 @@ You can only migrate some resources on supported infrastructure types. |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 index c26b1830b3ff..254a9cd1d910 100644 --- a/modules/migrating-between-capi-mapi.adoc +++ b/modules/migrating-between-capi-mapi.adoc @@ -34,6 +34,7 @@ endif::[] [id="migrating-between-capi-mapi_{context}"] = Migrating a {from-api-name} resource to use the {to-api-name} +[role="_abstract"] 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} @@ -77,9 +78,8 @@ where `` is one of the following values: $ 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. @@ -87,7 +87,6 @@ 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: + @@ -106,22 +105,12 @@ status: [...] ---- + --- 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. --- +`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] ==== @@ -140,9 +129,8 @@ For more information, see "Unexpected behavior when changing resource configurat $ 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. @@ -150,13 +138,10 @@ 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]