OSDOCS-17042 [CQA] Convert callouts to definition lists in MachineSet YAML by bscott-rh · Pull Request #105995 · openshift/openshift-docs

bscott-rh · 2026-02-04T19:44:01Z

Replace numbered callouts with definition list format in platform-specific machineset YAML sample files for improved readability and standardization.

Changes:

AWS, Azure, Azure Stack Hub, GCP, IBM Cloud, Nutanix, OSP, vSphere
Generic machineset-creating.adoc

Version(s):
4.16+

Issue:
https://issues.redhat.com/browse/OSDOCS-17042

Link to docs preview:
Cloud templates
Creating a compute machine set

This is 1 of 3 PRs split out from #103488 by Claude. The other two PRs are #105996 and #105997

ocpdocs-previewbot · 2026-02-04T19:51:46Z

🤖 Wed Feb 04 20:11:17 - Prow CI generated the docs preview:
https://105995--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

Replace numbered callouts with definition list format in platform-specific machineset YAML sample files for improved readability and standardization. Changes: - AWS, Azure, Azure Stack Hub, GCP, IBM Cloud, Nutanix, OSP, vSphere - Generic machineset-creating.adoc Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

openshift-ci · 2026-02-04T20:14:56Z

@bscott-rh: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

jeana-redhat

Tricky group of files to remediate. Overall this is solid, I did have one structural note about the approach with the AWS/Azure/GCP nonguaranteed instance types. Otherwise, mostly small stuff throughout especially around trying to thread the needle on presenting these consistently across one YAML file. I'm happy to chat about any of this, of course

jeana-redhat · 2026-02-26T15:03:33Z

 ====
-<3> The values in the `<providerSpec>` section of the compute machine set CR are platform-specific. For more information about `<providerSpec>` parameters in the CR, see the sample compute machine set CR configuration for your provider.
+
+The values in the `<providerSpec>` section of the compute machine set CR are platform-specific. For more information about `<providerSpec>` parameters in the CR, see the sample compute machine set CR configuration for your provider.


Please fix my egregious mistake 😛

Suggested change

The values in the `<providerSpec>` section of the compute machine set CR are platform-specific. For more information about `<providerSpec>` parameters in the CR, see the sample compute machine set CR configuration for your provider.

The values in the `spec.template.spec.providerSpec` section of the compute machine set CR are platform-specific. For more information about `providerSpec` parameters in the CR, see the sample compute machine set CR configuration for your provider.

I think you can get away with only using the path once, but it's not a replaceable value and idk why I did that

I think you might want this to indent one over to the left - if so, use an open block to accomplish that

jeana-redhat · 2026-02-26T15:06:07Z

+where:
+
+`<infrastructure_id>`:: Specifies the cluster infrastructure ID.
+`<infrastructure_id>_<role>`:: Specifies a default node label.


tiny typo

Suggested change

`<infrastructure_id>_<role>`:: Specifies a default node label.

`<infrastructure_id>-<role>`:: Specifies a default node label.

jeana-redhat · 2026-02-26T15:10:36Z

+where:
+
+`<secret_name>`:: Specifies the name of the secret in the `openshift-machine-api` namespace that contains the required vCenter credentials.
+`dataDisks`:: Specifies the collection of data disk definitions. For more information, see "Configuring data disks by using machine sets".


This one is an outlier. I don't see a good way to make it into a user-replaced value, and I think it would be unfortunate for readability to swap the rest over to YAML field paths. WDYT about moving the contents of this one to a note at the end of the list like I think I mentioned on another PR with a similar snag?

jeana-redhat · 2026-02-26T15:13:57Z

+Machine sets running on AWS support non-guaranteed Spot Instances. You can save on costs by using Spot Instances at a lower price compared to
+On-Demand Instances on AWS. You can configure Spot Instances by adding `spotMarketOptions` to the `MachineSet` YAML file.


This is conditioned for edge, but these lines came from the infra docs. It also applies to the standard machine set.

For a standard machine set, the non-guaranteed instance type docs are in the same assembly, but for the infra machine set docs, we do need to make sure there are still links to the content as they were in e.g.

Machine sets running on AWS support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machineset-non-guaranteed-instance_creating-machineset-aws[Spot Instances]. You can save on costs by using Spot Instances at a lower price compared to On-Demand Instances on AWS. xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-aws[Configure Spot Instances] by adding `spotMarketOptions` to the `MachineSet` YAML file.

So, I think probably:

move this into the infra version of the body

it doesn't need to be a note - it's just a config option that we chose to mention for infra machine sets

add docs titles so that users know what they are looking for

add those docs links in an AR section under the modules

Machine sets running on AWS support non-guaranteed Spot Instances. You can save on costs by using Spot Instances at a lower price compared to On-Demand Instances on AWS. For more information, see "Machine sets that deploy machines as Spot Instances". ... .Additional resources * xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machineset-non-guaranteed-instance_creating-machineset-aws[Machine sets that deploy machines as Spot Instances]

It might make more sense to do this in #105997

jeana-redhat · 2026-02-26T18:32:06Z

 ifndef::infra,edge[]
-<2> Specify the infrastructure ID, role node label, and zone.
-<3> Specify the role node label to add.
+`<infrastructure_id>-role-<zone>`:: Specifies the infrastructure ID, role node label, and zone.


Suggested change

`<infrastructure_id>-role-<zone>`:: Specifies the infrastructure ID, role node label, and zone.

`<infrastructure_id>-<role>-<zone>`:: Specifies the infrastructure ID, role node label, and zone.

jeana-redhat · 2026-02-26T19:12:10Z

+Machine sets running on {gcp-short} support non-guaranteed preemptible VM instances. You can save on costs by using preemptible VM instances at a lower price
+compared to normal instances on {gcp-short}. You can configure preemptible VM instances by adding `preemptible` to the `MachineSet` YAML file.


this guy has the same issue as AWS and Azure

jeana-redhat · 2026-02-26T19:14:12Z

+`gcpMetadata`:: Optional: Specifies custom metadata in the form of a `key:value` pair. For example use cases, see the {gcp-short} documentation for link:https://cloud.google.com/compute/docs/metadata/setting-custom-metadata[setting custom metadata].
+`<project_name>`:: Specifies the name of the {gcp-short} project that you use for your cluster.
+`serviceAccounts`:: Specifies a single service account. Multiple service accounts are not supported.


since there are fewer callouts here and there are two that would be hard to make variables, you might consider doing all of these as dot paths (you might have a better idea to get them consistent)

jeana-redhat · 2026-02-26T19:17:01Z

this one is a little harder to get consistent wrt callout replacement strategy. might want to come back to nutanix after the rest are done to see if any ideas have suggested themselves

jeana-redhat · 2026-02-26T19:17:43Z

 link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html/command_line_interface_reference/server#server_group_create[creating a server group]. For most deployments, `anti-affinity` or `soft-anti-affinity` policies are recommended.
-<5> Required for deployments to multiple networks. To specify multiple networks, add another entry in the networks array. Also, you must include the network that is used as the `primarySubnet` value.
-<6> Specify the {rh-openstack} subnet that you want the endpoints of nodes to be published on. Usually, this is the same subnet that is used as the value of `machinesSubnet` in the `install-config.yaml` file.
+`networks`:: Required for deployments to multiple networks. To specify multiple networks, add another entry in the networks array. Also, you must include the network that is used as the `primarySubnet` value.


Possibly this could be a note to avoid being the lone field?

jeana-redhat · 2026-02-26T19:18:37Z

similar things as some of the challenges earlier.

openshift-ci Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Feb 4, 2026

bscott-rh force-pushed the OSDOCS-17042-pr1-machineset-yaml branch from b0a5576 to 47f273c Compare February 4, 2026 20:01

bscott-rh changed the title ~~OSDOCS-17042 Convert callouts to definition lists in MachineSet YAML~~ OSDOCS-17042 [CQA] Convert callouts to definition lists in MachineSet YAML Feb 23, 2026

This was referenced Feb 23, 2026

OSDOCS-17042 [CQA] Simplify VPA and CRO resource movement documentation #105996

Open

OSDOCS-17042 [CQA] Update infrastructure machine set creation documentation #105997

Open

bscott-rh added branch/enterprise-4.16 branch/enterprise-4.17 branch/enterprise-4.18 branch/enterprise-4.19 branch/enterprise-4.20 branch/enterprise-4.21 branch/enterprise-4.22 labels Feb 23, 2026

bscott-rh added this to the Continuous Release milestone Feb 23, 2026

jeana-redhat reviewed Feb 26, 2026

View reviewed changes

	The values in the `<providerSpec>` section of the compute machine set CR are platform-specific. For more information about `<providerSpec>` parameters in the CR, see the sample compute machine set CR configuration for your provider.
	The values in the `spec.template.spec.providerSpec` section of the compute machine set CR are platform-specific. For more information about `providerSpec` parameters in the CR, see the sample compute machine set CR configuration for your provider.

	`<infrastructure_id>_<role>`:: Specifies a default node label.
	`<infrastructure_id>-<role>`:: Specifies a default node label.

		Machine sets running on AWS support non-guaranteed Spot Instances. You can save on costs by using Spot Instances at a lower price compared to
		On-Demand Instances on AWS. You can configure Spot Instances by adding `spotMarketOptions` to the `MachineSet` YAML file.

	`<infrastructure_id>-role-<zone>`:: Specifies the infrastructure ID, role node label, and zone.
	`<infrastructure_id>-<role>-<zone>`:: Specifies the infrastructure ID, role node label, and zone.

		Machine sets running on {gcp-short} support non-guaranteed preemptible VM instances. You can save on costs by using preemptible VM instances at a lower price
		compared to normal instances on {gcp-short}. You can configure preemptible VM instances by adding `preemptible` to the `MachineSet` YAML file.

Conversation

bscott-rh commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci Bot commented Feb 4, 2026

Uh oh!

jeana-redhat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bscott-rh commented Feb 4, 2026 •

edited

Loading

ocpdocs-previewbot commented Feb 4, 2026 •

edited

Loading