This is a cache of https://docs.okd.io/4.19/machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-vsphere.html. It is a snapshot of the page at 2025-07-05T20:52:48.373+0000.
Control plane configuration options for VMware vSphere - Managing control plane machines | Machine management | OKD 4.19
  1. Documentation
×

Control plane configuration options for VMware vSphere

You can change the configuration of your VMware vSphere control plane machines by updating values in the control plane machine set. When you save an update to the control plane machine set, the Control Plane Machine Set Operator updates the control plane machines according to your configured update strategy.

Sample YAML for configuring VMware vSphere clusters

The following example YAML snippets show provider specification and failure domain configurations for a vSphere cluster.

Sample VMware vSphere provider specification

When you create a control plane machine set for an existing cluster, the provider specification must match the providerSpec configuration in the control plane machine custom resource (CR) that the installation program creates.

Sample vSphere providerSpec values
apiVersion: machine.openshift.io/v1
kind: ControlPlaneMachineSet
metadata:
  name: cluster
  namespace: openshift-machine-api
spec:
# ...
  template:
# ...
      spec:
        providerSpec:
          value:
            apiVersion: machine.openshift.io/v1beta1
            credentialsSecret:
              name: vsphere-cloud-credentials (1)
            dataDisks: (2)
            - name: "<disk_name>"
              provisioningMode: "<mode>"
              sizeGiB: 20
            diskGiB: 120 (3)
            kind: VSphereMachineProviderSpec (4)
            memoryMiB: 16384 (5)
            metadata:
              creationTimestamp: null
            network: (6)
              devices:
              - networkName: <vm_network_name>
            numCPUs: 4 (7)
            numCoresPerSocket: 4 (8)
            snapshot: ""
            template: <vm_template_name> (9)
            userDataSecret:
              name: master-user-data (10)
            workspace: (11)
              datacenter: <vcenter_data_center_name> (12)
              datastore: <vcenter_datastore_name> (13)
              folder: <path_to_vcenter_vm_folder> (14)
              resourcePool: <vsphere_resource_pool> (15)
              server: <vcenter_server_ip> (16)
1 Specifies the secret name for the cluster. Do not change this value.
2 Specifies one or more data disk definitions. For more information, see "Configuring data disks by using machine sets".
3 Specifies the VM disk size for the control plane machines.
4 Specifies the cloud provider platform type. Do not change this value.
5 Specifies the memory allocated for the control plane machines.
6 Specifies the network on which the control plane is deployed.

If the cluster is configured to use a failure domain, this parameter is configured in the failure domain. If you specify this value in the provider specification when using failure domains, the Control Plane Machine Set Operator ignores it.
7 Specifies the number of CPUs allocated for the control plane machines.
8 Specifies the number of cores for each control plane CPU.
9 Specifies the vSphere VM template to use, such as user-5ddjd-rhcos.

If the cluster is configured to use a failure domain, this parameter is configured in the failure domain. If you specify this value in the provider specification when using failure domains, the Control Plane Machine Set Operator ignores it.
10 Specifies the control plane user data secret. Do not change this value.
11 Specifies the workspace details for the control plane.

If the cluster is configured to use a failure domain, these parameters are configured in the failure domain. If you specify these values in the provider specification when using failure domains, the Control Plane Machine Set Operator ignores them.
12 Specifies the vCenter datacenter for the control plane.
13 Specifies the vCenter datastore for the control plane.
14 Specifies the path to the vSphere VM folder in vCenter, such as /dc1/vm/user-inst-5ddjd.
15 Specifies the vSphere resource pool for your VMs.
16 Specifies the vCenter server IP or fully qualified domain name.

Sample VMware vSphere failure domain configuration

On VMware vSphere infrastructure, the cluster-wide infrastructure Custom Resource Definition (CRD), infrastructures.config.openshift.io, defines failure domains for your cluster. The providerSpec in the ControlPlaneMachineSet custom resource (CR) specifies names for failure domains that the control plane machine set uses to ensure control plane nodes are deployed to the appropriate failure domain. A failure domain is an infrastructure resource made up of a control plane machine set, a vCenter data center, vCenter datastore, and a network.

By using a failure domain resource, you can use a control plane machine set to deploy control plane machines on separate clusters or data centers. A control plane machine set also balances control plane machines across defined failure domains to provide fault tolerance capabilities to your infrastructure.

If you modify the ProviderSpec configuration in the ControlPlaneMachineSet CR, the control plane machine set updates all control plane machines deployed on the primary infrastructure and each failure domain infrastructure.
Sample VMware vSphere failure domain values
apiVersion: machine.openshift.io/v1
kind: ControlPlaneMachineSet
metadata:
  name: cluster
  namespace: openshift-machine-api
spec:
# ...
  template:
# ...
    machines_v1beta1_machine_openshift_io:
      failureDomains: (1)
        platform: VSphere
        vsphere: (2)
        - name: <failure_domain_name_1>
        - name: <failure_domain_name_2>
# ...
1 Specifies the vCenter location for OKD cluster nodes.
2 Specifies failure domains by name for the control plane machine set.

Each name field value in this section must match the corresponding value in the failureDomains.name field of the cluster-wide infrastructure CRD. You can find the value of the failureDomains.name field by running the following command:

$ oc get infrastructure cluster -o=jsonpath={.spec.platformSpec.vsphere.failureDomains[0].name}

The name field is the only supported failure domain field that you can specify in the ControlPlaneMachineSet CR.

For an example of a cluster-wide infrastructure CRD that defines resources for each failure domain, see "Specifying multiple regions and zones for your cluster on vSphere."

Additional resources

Enabling VMware vSphere features for control plane machines

You can enable features by updating values in the control plane machine set.

Adding tags to machines by using machine sets

OKD adds a cluster-specific tag to each virtual machine (VM) that it creates. The installation program uses these tags to select the VMs to delete when uninstalling a cluster.

In addition to the cluster-specific tags assigned to VMs, you can configure a machine set to add up to 10 additional vSphere tags to the VMs it provisions.

Prerequisites

  • You have access to an OKD cluster installed on vSphere using an account with cluster-admin permissions.

  • You have access to the VMware vCenter console associated with your cluster.

  • You have created a tag in the vCenter console.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Use the vCenter console to find the tag ID for any tag that you want to add to your machines:

    1. Log in to the vCenter console.

    2. From the Home menu, click Tags & Custom Attributes.

    3. Select a tag that you want to add to your machines.

    4. Use the browser URL for the tag that you select to identify the tag ID.

      Example tag URL
      https://vcenter.example.com/ui/app/tags/tag/urn:vmomi:InventoryServiceTag:208e713c-cae3-4b7f-918e-4051ca7d1f97:GLOBAL/permissions
      Example tag ID
      urn:vmomi:InventoryServiceTag:208e713c-cae3-4b7f-918e-4051ca7d1f97:GLOBAL

  2. In a text editor, open the YAML file for an existing machine set or create a new one.

  3. Edit the following lines under the providerSpec field:

    apiVersion: machine.openshift.io/v1
kind: ControlPlaneMachineSet
# ...
spec:
  template:
    spec:
      providerSpec:
        value:
          tagIDs: (1)
          - <tag_id_value> (2)
# ...
    1 Specify a list of up to 10 tags to add to the machines that this machine set provisions.
    2 Specify the value of the tag that you want to add to your machines. For example, urn:vmomi:InventoryServiceTag:208e713c-cae3-4b7f-918e-4051ca7d1f97:GLOBAL.

Configuring data disks by using machine sets

OKD clusters on VMware vSphere support adding up to 29 disks to the virtual machine (VM) controller.

Configuring vSphere data disks is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

By configuring data disks, you can attach disks to VMs and use them to store data for etcd, container images, and other uses. Separating data can help avoid filling the primary disk so that important activities such as upgrades have the resources that they require.

Adding data disks attaches them to the VM and mounts them to the location that FCOS designates.
Prerequisites

  • You have administrator access to OpenShift CLI (oc) for an OKD cluster on vSphere.

Procedure

  1. In a text editor, open the YAML file for an existing machine set or create a new one.

  2. Edit the following lines under the providerSpec field:

    apiVersion: machine.openshift.io/v1
kind: ControlPlaneMachineSet
# ...
spec:
  template:
    machines_v1beta1_machine_openshift_io:
      spec:
        providerSpec:
          value:
            dataDisks: (1)
            - name: "<disk_name>" (2)
              provisioningMode: "<mode>" (3)
              sizeGiB: 20 (4)
            - name: "<disk_name>"
              provisioningMode: "<mode>"
              sizeGiB: 20
# ...
    1 Specify a collection of 1-29 data disk definitions. This sample configuration shows the formatting to include two data disk definitions.
    2 Specify the name of the data disk. The name must meet the following requirements:

    • Start and end with an alphanumeric character

    • Consist only of alphanumeric characters, hyphens (-), and underscores (_)

    • Have a maximum length of 80 characters
    3 Specify the data disk provisioning method. This value defaults to the vSphere default storage policy if not set. Valid values are Thin, Thick, and EagerlyZeroed.
    4 Specify the size of the data disk in GiB. The maximum size is 16384 GiB.