OSDOCS-17045-2: CQA 1 for MACH-4 Cluster API for Compute Machines

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,12 +73,14 @@ 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
 include::modules/deploying-capi-machines-via-mapi-machine-sets.adoc[leveloffset=+2]
 
 [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]

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

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 `<machine_set_resource_file>.yaml` as an example file name.
 +
---
 [source,yaml]
 ----
 apiVersion: cluster.x-k8s.io/v1beta1
 kind: MachineSet
 metadata:
-  name: <machine_set_name> # <1>
+  name: <machine_set_name>
   namespace: openshift-cluster-api
 spec:
-  clusterName: <cluster_name> # <2>
+  clusterName: <cluster_name>
   replicas: 1
   selector:
     matchLabels:
@@ -42,21 +42,24 @@ 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: `<cluster_name>-<role>-<region>`.
-<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]
 ----
 $  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
 <machine_set_name>-<string_id>   <cluster_name>   <ip_address>.<region>.compute.internal   <provider_id>   Running   8m23s
 ----
-
++
 ** View the list of nodes:
 +
 [source,terminal]

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 `<machine_template_resource_file>.yaml` as an example file name.
+. Create a YAML file similar to the following example. This procedure uses `<machine_template_resource_file>.yaml` as an example file name.
 +
---
 [source,yaml]
 ----
 apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
-kind: <machine_template_kind> # <1>
+kind: <machine_template_kind>
 metadata:
-  name: <template_name> # <2>
+  name: <template_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 <machine_template_resource_file>.yaml
 $ oc get <machine_template_kind> -n openshift-cluster-api
 ----
 +
-where `<machine_template_kind>` is the value that corresponds to your platform.
+`<machine_template_kind>`: Specifies the value that corresponds to your platform.
 +
 .Example output
 [source,text]
 ----
 NAME              AGE
 <template_name>   77m
-----
+----

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: <machine_set_name> # <1>
+  name: <machine_set_name>
   namespace: openshift-cluster-api
   labels:
-    cluster.x-k8s.io/cluster-name: <cluster_name> # <2>
+    cluster.x-k8s.io/cluster-name: <cluster_name>
 spec:
   clusterName: <cluster_name>
   replicas: 1
@@ -35,16 +36,19 @@ spec:
         node-role.kubernetes.io/<role>: ""
     spec:
       bootstrap:
-         dataSecretName: worker-user-data
+        dataSecretName: worker-user-data
       clusterName: <cluster_name>
       infrastructureRef:
         apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
-        kind: AzureMachineTemplate # <3>
-        name: <template_name> # <4>
+        kind: AzureMachineTemplate
+        name: <template_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: `<cluster_name>-<role>-<region>`.
-<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.
+`spec.template.spec.infrastructureRef.name`:: Specifies the machine template name.

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: <template_name> # <2>
+  name: <template_name>
   namespace: openshift-cluster-api
 spec:
   template:
-    spec: # <3>
+    spec:
       disableExtensionOperations: true
       identity: UserAssigned
       image:
-        id: /subscriptions/<subscription_id>/resourceGroups/<cluster_name>-rg/providers/Microsoft.Compute/galleries/gallery_<compliant_cluster_name>/images/<cluster_name>-gen2/versions/latest # <4> 
+        id: /subscriptions/<subscription_id>/resourceGroups/<cluster_name>-rg/providers/Microsoft.Compute/galleries/gallery_<compliant_cluster_name>/images/<cluster_name>-gen2/versions/latest
       networkInterfaces:
         - acceleratedNetworking: true
           privateIPConfigs: 1
@@ -37,14 +38,17 @@ spec:
         - providerID: 'azure:///subscriptions/<subscription_id>/resourcegroups/<cluster_name>-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<cluster_name>-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 `<cluster_name>` do not change.
 For example, a cluster name of `jdoe-test-2m2np` transforms to `jdoe_test_2m2np`.
 The full string for `gallery_<compliant_cluster_name>` 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/<subscription_id>/resourceGroups/jdoe-test-2m2np-rg/providers/Microsoft.Compute/galleries/gallery_jdoe_test_2m2np/images/jdoe-test-2m2np-gen2/versions/latest`.
-====
+====

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 <machine_set_name> \
   -n openshift-machine-api
 ----
 +
-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.
+`<machine_set_name>`: 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: <machine_set_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:
 +

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"]