Managing control plane machines with control plane machine sets

Control plane machine sets automate several essential aspects of control plane management.

Replacing a control plane machine

To replace a control plane machine in a cluster that has a control plane machine set, you delete the machine manually. The control plane machine set replaces the deleted machine with one using the specification in the control plane machine set custom resource (CR).

Prerequisites

  • If your cluster runs on OpenStack and you need to evacuate a compute server, such as for an upgrade, you must disable the OpenStack compute node that the machine runs on by running the following command:

    1. $ openstack compute service set <target_node_host_name> nova-compute --disable

    For more information, see Preparing to migrate in the OpenStack documentation.

Procedure

  1. List the control plane machines in your cluster by running the following command:

    1. $ oc get machines \
    2.   -l machine.openshift.io/cluster-api-machine-role==master \
    3.   -n openshift-machine-api

  2. Delete a control plane machine by running the following command:

    1. $ oc delete machine \
    2.   -n openshift-machine-api \
    3.   <control_plane_machine_name> (1)
    1Specify the name of the control plane machine to delete.

    If you delete multiple control plane machines, the control plane machine set replaces them according to the configured update strategy:

    • For clusters that use the default RollingUpdate update strategy, the Operator replaces one machine at a time until each machine is replaced.

    • For clusters that are configured to use the OnDelete update strategy, the Operator creates all of the required replacement machines simultaneously.

    Both strategies maintain etcd health during control plane machine replacement.

Updating the control plane configuration

You can make changes to the configuration of the machines in the control plane by updating the specification in the control plane machine set custom resource (CR).

The Control Plane Machine Set Operator monitors the control plane machines and compares their configuration with the specification in the control plane machine set CR. When there is a discrepancy between the specification in the CR and the configuration of a control plane machine, the Operator marks that control plane machine for replacement.

For more information about the parameters in the CR, see “Control plane machine set configuration”.

Prerequisites

  • Your cluster has an activated and functioning Control Plane Machine Set Operator.

Procedure

  1. Edit your control plane machine set CR by running the following command:

    1. $ oc edit controlplanemachineset.machine.openshift.io cluster \
    2.   -n openshift-machine-api

  2. Change the values of any fields that you want to update in your cluster configuration.

  3. Save your changes.

Next steps

  • For clusters that use the default RollingUpdate update strategy, the control plane machine set propagates changes to your control plane configuration automatically.

  • For clusters that are configured to use the OnDelete update strategy, you must replace your control plane machines manually.

Automatic updates to the control plane configuration

The RollingUpdate update strategy automatically propagates changes to your control plane configuration. This update strategy is the default configuration for the control plane machine set.

For clusters that use the RollingUpdate update strategy, the Operator creates a replacement control plane machine with the configuration that is specified in the CR. When the replacement control plane machine is ready, the Operator deletes the control plane machine that is marked for replacement. The replacement machine then joins the control plane.

If multiple control plane machines are marked for replacement, the Operator protects etcd health during replacement by repeating this replacement process one machine at a time until it has replaced each machine.

Manual updates to the control plane configuration

You can use the OnDelete update strategy to propagate changes to your control plane configuration by replacing machines manually. Manually replacing machines allows you to test changes to your configuration on a single machine before applying the changes more broadly.

For clusters that are configured to use the OnDelete update strategy, the Operator creates a replacement control plane machine when you delete an existing machine. When the replacement control plane machine is ready, the etcd Operator allows the existing machine to be deleted. The replacement machine then joins the control plane.

If multiple control plane machines are deleted, the Operator creates all of the required replacement machines simultaneously. The Operator maintains etcd health by preventing more than one machine being removed from the control plane at once.

Enabling Amazon Web Services features for control plane machines

You can enable Amazon Web Services (AWS) features on control plane machines by changing the configuration of your 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.

Restricting the API server to private

After you deploy a cluster to Amazon Web Services (AWS), you can reconfigure the API server to use only the private zone.

Prerequisites

  • Install the OpenShift CLI (oc).

  • Have access to the web console as a user with admin privileges.

Procedure

  1. In the web portal or console for your cloud provider, take the following actions:

    1. Locate and delete the appropriate load balancer component:

      • For AWS, delete the external load balancer. The API DNS entry in the private zone already points to the internal load balancer, which uses an identical configuration, so you do not need to modify the internal load balancer.

    2. Delete the api.$clustername.$yourdomain DNS entry in the public zone.

  2. Remove the external load balancers by deleting the following lines in the control plane machine set custom resource:

    1. providerSpec:
    2.   value:
    3.     loadBalancers:
    4.     - name: lk4pj-ext (1)
    5.       type: network (1)
    6.     - name: lk4pj-int
    7.       type: network
    1Delete this line.

Changing the Amazon Web Services instance type by using a control plane machine set

You can change the Amazon Web Services (AWS) instance type that your control plane machines use by updating the specification in the control plane machine set custom resource (CR).

Prerequisites

  • Your AWS cluster uses a control plane machine set.

Procedure

  1. Edit the following line under the providerSpec field:

    1. providerSpec:
    2.   value:
    3.     ...
    4.     instanceType: <compatible_aws_instance_type> (1)
    1Specify a larger AWS instance type with the same base as the previous selection. For example, you can change m6i.xlarge to m6i.2xlarge or m6i.4xlarge.

  2. Save your changes.

Assigning machines to placement groups for Elastic Fabric Adapter instances by using machine sets

You can configure a machine set to deploy machines on Elastic Fabric Adapter (EFA) instances within an existing AWS placement group.

EFA instances do not require placement groups, and you can use placement groups for purposes other than configuring an EFA. This example uses both to demonstrate a configuration that can improve network performance for machines within the specified placement group.

Prerequisites

  • You created a placement group in the AWS console.

    Ensure that the rules and limitations for the type of placement group that you create are compatible with your intended use case. The control plane machine set spreads the control plane machines across multiple failure domains when possible. To use placement groups for the control plane, you must use a placement group type that can span multiple Availability Zones.

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:

    1. apiVersion: machine.openshift.io/v1
    2. kind: ControlPlaneMachineSet
    3. # ...
    4. spec:
    5.   template:
    6.     spec:
    7.       providerSpec:
    8.         value:
    9.           instanceType: <supported_instance_type> (1)
    10.           networkInterfaceType: EFA (2)
    11.           placement:
    12.             availabilityZone: <zone> (3)
    13.             region: <region> (4)
    14.           placementGroupName: <placement_group> (5)
    15. # ...
    1Specify an instance type that supports EFAs.
    2Specify the EFA network interface type.
    3Specify the zone, for example, us-east-1a.
    4Specify the region, for example, us-east-1.
    5Specify the name of the existing AWS placement group to deploy machines in.

Verification

  • In the AWS console, find a machine that the machine set created and verify the following in the machine properties:

    • The placement group field has the value that you specified for the placementGroupName parameter in the machine set.

    • The interface type field indicates that it uses an EFA.

Machine set options for the Amazon EC2 Instance Metadata Service

You can use machine sets to create machines that use a specific version of the Amazon EC2 Instance Metadata Service (IMDS). Machine sets can create machines that allow the use of both IMDSv1 and IMDSv2 or machines that require the use of IMDSv2.

Using IMDSv2 is only supported on AWS clusters that were created with OKD version 4.7 or later.

To change the IMDS configuration for existing machines, edit the machine set YAML file that manages those machines.

Before configuring a machine set to create machines that require IMDSv2, ensure that any workloads that interact with the AWS metadata service support IMDSv2.

Configuring IMDS by using machine sets

You can specify whether to require the use of IMDSv2 by adding or editing the value of metadataServiceOptions.authentication in the machine set YAML file for your machines.

Prerequisites

  • To use IMDSv2, your AWS cluster must have been created with OKD version 4.7 or later.

Procedure

  • Add or edit the following lines under the providerSpec field:

    1. providerSpec:
    2.   value:
    3.     metadataServiceOptions:
    4.       authentication: Required (1)
    1To require IMDSv2, set the parameter value to Required. To allow the use of both IMDSv1 and IMDSv2, set the parameter value to Optional. If no value is specified, both IMDSv1 and IMDSv2 are allowed.

Machine sets that deploy machines as Dedicated Instances

You can create a machine set running on AWS that deploys machines as Dedicated Instances. Dedicated Instances run in a virtual private cloud (VPC) on hardware that is dedicated to a single customer. These Amazon EC2 instances are physically isolated at the host hardware level. The isolation of Dedicated Instances occurs even if the instances belong to different AWS accounts that are linked to a single payer account. However, other instances that are not dedicated can share hardware with Dedicated Instances if they belong to the same AWS account.

Instances with either public or dedicated tenancy are supported by the Machine API. Instances with public tenancy run on shared hardware. Public tenancy is the default tenancy. Instances with dedicated tenancy run on single-tenant hardware.

Creating Dedicated Instances by using machine sets

You can run a machine that is backed by a Dedicated Instance by using Machine API integration. Set the tenancy field in your machine set YAML file to launch a Dedicated Instance on AWS.

Procedure

  • Specify a dedicated tenancy under the providerSpec field:

    1. providerSpec:
    2.   placement:
    3.     tenancy: dedicated

Enabling Microsoft Azure features for control plane machines

You can enable Microsoft Azure features on control plane machines by changing the configuration of your 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.

Restricting the API server to private

After you deploy a cluster to Microsoft Azure, you can reconfigure the API server to use only the private zone.

Prerequisites

  • Install the OpenShift CLI (oc).

  • Have access to the web console as a user with admin privileges.

Procedure

  1. In the web portal or console for your cloud provider, take the following actions:

    1. Locate and delete the appropriate load balancer component:

      • For Azure, delete the api-internal rule for the load balancer.

    2. Delete the api.$clustername.$yourdomain DNS entry in the public zone.

  2. Remove the external load balancers by deleting the following lines in the control plane machine set custom resource:

    1. providerSpec:
    2.   value:
    3.     loadBalancers:
    4.     - name: lk4pj-ext (1)
    5.       type: network (1)
    6.     - name: lk4pj-int
    7.       type: network
    1Delete this line.

Using the Azure Marketplace offering

You can create a machine set running on Azure that deploys machines that use the Azure Marketplace offering. To use this offering, you must first obtain the Azure Marketplace image. When obtaining your image, consider the following:

  • While the images are the same, the Azure Marketplace publisher is different depending on your region. If you are located in North America, specify redhat as the publisher. If you are located in EMEA, specify redhat-limited as the publisher.

  • The offer includes a rh-ocp-worker SKU and a rh-ocp-worker-gen1 SKU. The rh-ocp-worker SKU represents a Hyper-V generation version 2 VM image. The default instance types used in OKD are version 2 compatible. If you plan to use an instance type that is only version 1 compatible, use the image associated with the rh-ocp-worker-gen1 SKU. The rh-ocp-worker-gen1 SKU represents a Hyper-V version 1 VM image.

Installing images with the Azure marketplace is not supported on clusters with 64-bit ARM instances.

Prerequisites

  • You have installed the Azure CLI client (az).

  • Your Azure account is entitled for the offer and you have logged into this account with the Azure CLI client.

Procedure

  1. Display all of the available OKD images by running one of the following commands:

    • North America:

      1. $  az vm image list --all --offer rh-ocp-worker --publisher redhat -o table

      Example output

      1. Offer          Publisher       Sku                 Urn                                                             Version
      2. -------------  --------------  ------------------  --------------------------------------------------------------  -----------------
      3. rh-ocp-worker  RedHat          rh-ocp-worker       RedHat:rh-ocp-worker:rh-ocp-worker:413.92.2023101700            413.92.2023101700
      4. rh-ocp-worker  RedHat          rh-ocp-worker-gen1  RedHat:rh-ocp-worker:rh-ocp-worker-gen1:413.92.2023101700       413.92.2023101700

    • EMEA:

      1. $  az vm image list --all --offer rh-ocp-worker --publisher redhat-limited -o table

      Example output

      1. Offer          Publisher       Sku                 Urn                                                                     Version
      2. -------------  --------------  ------------------  --------------------------------------------------------------          -----------------
      3. rh-ocp-worker  redhat-limited  rh-ocp-worker       redhat-limited:rh-ocp-worker:rh-ocp-worker:413.92.2023101700            413.92.2023101700
      4. rh-ocp-worker  redhat-limited  rh-ocp-worker-gen1  redhat-limited:rh-ocp-worker:rh-ocp-worker-gen1:413.92.2023101700       413.92.2023101700

    Regardless of the version of OKD that you install, the correct version of the Azure Marketplace image to use is 4.13. If required, your VMs are automatically upgraded as part of the installation process.

  2. Inspect the image for your offer by running one of the following commands:

    • North America:

      1. $ az vm image show --urn redhat:rh-ocp-worker:rh-ocp-worker:<version>

    • EMEA:

      1. $ az vm image show --urn redhat-limited:rh-ocp-worker:rh-ocp-worker:<version>

  3. Review the terms of the offer by running one of the following commands:

    • North America:

      1. $ az vm image terms show --urn redhat:rh-ocp-worker:rh-ocp-worker:<version>

    • EMEA:

      1. $ az vm image terms show --urn redhat-limited:rh-ocp-worker:rh-ocp-worker:<version>

  4. Accept the terms of the offering by running one of the following commands:

    • North America:

      1. $ az vm image terms accept --urn redhat:rh-ocp-worker:rh-ocp-worker:<version>

    • EMEA:

      1. $ az vm image terms accept --urn redhat-limited:rh-ocp-worker:rh-ocp-worker:<version>

  5. Record the image details of your offer, specifically the values for publisher, offer, sku, and version.

  6. Add the following parameters to the providerSpec section of your machine set YAML file using the image details for your offer:

    Sample providerSpec image values for Azure Marketplace machines

    1. providerSpec:
    2.   value:
    3.     image:
    4.       offer: rh-ocp-worker
    5.       publisher: redhat
    6.       resourceID: ""
    7.       sku: rh-ocp-worker
    8.       type: MarketplaceWithPlan
    9.       version: 413.92.2023101700

Enabling Azure boot diagnostics

You can enable boot diagnostics on Azure machines that your machine set creates.

Prerequisites

  • Have an existing Microsoft Azure cluster.

Procedure

  • Add the diagnostics configuration that is applicable to your storage type to the providerSpec field in your machine set YAML file:

    • For an Azure Managed storage account:

      1. providerSpec:
      2.   diagnostics:
      3.     boot:
      4.       storageAccountType: AzureManaged (1)
      1Specifies an Azure Managed storage account.

    • For an Azure Unmanaged storage account:

      1. providerSpec:
      2.   diagnostics:
      3.     boot:
      4.       storageAccountType: CustomerManaged (1)
      5.       customerManaged:
      6.         storageAccountURI: https://<storage-account>.blob.core.windows.net (2)
      1Specifies an Azure Unmanaged storage account.
      2Replace <storage-account> with the name of your storage account.

      Only the Azure Blob Storage data service is supported.

Verification

  • On the Microsoft Azure portal, review the Boot diagnostics page for a machine deployed by the machine set, and verify that you can see the serial logs for the machine.

Machine sets that deploy machines with ultra disks as data disks

You can create a machine set running on Azure that deploys machines with ultra disks. Ultra disks are high-performance storage that are intended for use with the most demanding data workloads.

Additional resources

Creating machines with ultra disks by using machine sets

You can deploy machines with ultra disks on Azure by editing your machine set YAML file.

Prerequisites

  • Have an existing Microsoft Azure cluster.

Procedure

  1. Create a custom secret in the openshift-machine-api namespace using the master data secret by running the following command:

    1. $ oc -n openshift-machine-api \
    2. get secret <role>-user-data \ (1)
    3. --template='{{index .data.userData | base64decode}}' | jq > userData.txt (2)
    1Replace <role> with master.
    2Specify userData.txt as the name of the new custom secret.

  2. In a text editor, open the userData.txt file and locate the final } character in the file.

    1. On the immediately preceding line, add a ,.

    2. Create a new line after the , and add the following configuration details:

      1. "storage": {
      2.   "disks": [ (1)
      3.     {
      4.       "device": "/dev/disk/azure/scsi1/lun0", (2)
      5.       "partitions": [ (3)
      6.         {
      7.           "label": "lun0p1", (4)
      8.           "sizeMiB": 1024, (5)
      9.           "startMiB": 0
      10.         }
      11.       ]
      12.     }
      13.   ],
      14.   "filesystems": [ (6)
      15.     {
      16.       "device": "/dev/disk/by-partlabel/lun0p1",
      17.       "format": "xfs",
      18.       "path": "/var/lib/lun0p1"
      19.     }
      20.   ]
      21. },
      22. "systemd": {
      23.   "units": [ (7)
      24.     {
      25.       "contents": "[Unit]\nBefore=local-fs.target\n[Mount]\nWhere=/var/lib/lun0p1\nWhat=/dev/disk/by-partlabel/lun0p1\nOptions=defaults,pquota\n[Install]\nWantedBy=local-fs.target\n", (8)
      26.       "enabled": true,
      27.       "name": "var-lib-lun0p1.mount"
      28.     }
      29.   ]
      30. }
      1The configuration details for the disk that you want to attach to a node as an ultra disk.
      2Specify the lun value that is defined in the dataDisks stanza of the machine set you are using. For example, if the machine set contains lun: 0, specify lun0. You can initialize multiple data disks by specifying multiple “disks” entries in this configuration file. If you specify multiple “disks” entries, ensure that the lun value for each matches the value in the machine set.
      3The configuration details for a new partition on the disk.
      4Specify a label for the partition. You might find it helpful to use hierarchical names, such as lun0p1 for the first partition of lun0.
      5Specify the total size in MiB of the partition.
      6Specify the filesystem to use when formatting a partition. Use the partition label to specify the partition.
      7Specify a systemd unit to mount the partition at boot. Use the partition label to specify the partition. You can create multiple partitions by specifying multiple “partitions” entries in this configuration file. If you specify multiple “partitions” entries, you must specify a systemd unit for each.
      8For Where, specify the value of storage.filesystems.path. For What, specify the value of storage.filesystems.device.

  3. Extract the disabling template value to a file called disableTemplating.txt by running the following command:

    1. $ oc -n openshift-machine-api get secret <role>-user-data \ (1)
    2. --template='{{index .data.disableTemplating | base64decode}}' | jq > disableTemplating.txt
    1Replace <role> with master.

  4. Combine the userData.txt file and disableTemplating.txt file to create a data secret file by running the following command:

    1. $ oc -n openshift-machine-api create secret generic <role>-user-data-x5 \ (1)
    2. --from-file=userData=userData.txt \
    3. --from-file=disableTemplating=disableTemplating.txt
    1For <role>-user-data-x5, specify the name of the secret. Replace <role> with master.

  5. Edit your control plane machine set CR by running the following command:

    1. $ oc --namespace openshift-machine-api edit controlplanemachineset.machine.openshift.io cluster

  6. Add the following lines in the positions indicated:

    1. apiVersion: machine.openshift.io/v1beta1
    2. kind: ControlPlaneMachineSet
    3. spec:
    4.   template:
    5.     spec:
    6.       metadata:
    7.         labels:
    8.           disk: ultrassd (1)
    9.       providerSpec:
    10.         value:
    11.           ultraSSDCapability: Enabled (2)
    12.           dataDisks: (2)
    13.           - nameSuffix: ultrassd
    14.             lun: 0
    15.             diskSizeGB: 4
    16.             deletionPolicy: Delete
    17.             cachingType: None
    18.             managedDisk:
    19.               storageAccountType: UltraSSD_LRS
    20.           userDataSecret:
    21.             name: <role>-user-data-x5 (3)
    1Specify a label to use to select a node that is created by this machine set. This procedure uses disk.ultrassd for this value.
    2These lines enable the use of ultra disks. For dataDisks, include the entire stanza.
    3Specify the user data secret created earlier. Replace <role> with master.

  7. Save your changes.

    • For clusters that use the default RollingUpdate update strategy, the Operator automatically propagates the changes to your control plane configuration.

    • For clusters that are configured to use the OnDelete update strategy, you must replace your control plane machines manually.

Verification

  1. Validate that the machines are created by running the following command:

    1. $ oc get machines

    The machines should be in the Running state.

  2. For a machine that is running and has a node attached, validate the partition by running the following command:

    1. $ oc debug node/<node-name> -- chroot /host lsblk

    In this command, oc debug node/<node-name> starts a debugging shell on the node <node-name> and passes a command with --. The passed command chroot /host provides access to the underlying host OS binaries, and lsblk shows the block devices that are attached to the host OS machine.

Next steps

  • To use an ultra disk on the control plane, reconfigure your workload to use the control plane’s ultra disk mount point.

Troubleshooting resources for machine sets that enable ultra disks

Use the information in this section to understand and recover from issues you might encounter.

Incorrect ultra disk configuration

If an incorrect configuration of the ultraSSDCapability parameter is specified in the machine set, the machine provisioning fails.

For example, if the ultraSSDCapability parameter is set to Disabled, but an ultra disk is specified in the dataDisks parameter, the following error message appears:

  1. StorageAccountType UltraSSD_LRS can be used only when additionalCapabilities.ultraSSDEnabled is set.
  • To resolve this issue, verify that your machine set configuration is correct.
Unsupported disk parameters

If a region, availability zone, or instance size that is not compatible with ultra disks is specified in the machine set, the machine provisioning fails. Check the logs for the following error message:

  1. failed to create vm <machine_name>: failure sending request for machine <machine_name>: cannot create vm: compute.VirtualMachinesClient#CreateOrUpdate: Failure sending request: StatusCode=400 -- Original Error: Code="BadRequest" Message="Storage Account type 'UltraSSD_LRS' is not supported <more_information_about_why>."
  • To resolve this issue, verify that you are using this feature in a supported environment and that your machine set configuration is correct.
Unable to delete disks

If the deletion of ultra disks as data disks is not working as expected, the machines are deleted and the data disks are orphaned. You must delete the orphaned disks manually if desired.

Enabling customer-managed encryption keys for a machine set

You can supply an encryption key to Azure to encrypt data on managed disks at rest. You can enable server-side encryption with customer-managed keys by using the Machine API.

An Azure Key Vault, a disk encryption set, and an encryption key are required to use a customer-managed key. The disk encryption set must be in a resource group where the Cloud Credential Operator (CCO) has granted permissions. If not, an additional reader role is required to be granted on the disk encryption set.

Prerequisites

Procedure

  • Configure the disk encryption set under the providerSpec field in your machine set YAML file. For example:

    1. providerSpec:
    2.   value:
    3.     osDisk:
    4.       diskSizeGB: 128
    5.       managedDisk:
    6.         diskEncryptionSet:
    7.           id: /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Compute/diskEncryptionSets/<disk_encryption_set_name>
    8.         storageAccountType: Premium_LRS

Additional resources

Configuring trusted launch for Azure virtual machines by using machine sets

Using trusted launch for Azure virtual machines 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.

OKD 4 supports trusted launch for Azure virtual machines (VMs). By editing the machine set YAML file, you can configure the trusted launch options that a machine set uses for machines that it deploys. For example, you can configure these machines to use UEFI security features such as Secure Boot or a dedicated virtual Trusted Platform Module (vTPM) instance.

Some feature combinations result in an invalid configuration.

Table 1. UEFI feature combination compatibility
Secure Boot[1]vTPM[2]Valid configuration

Enabled

Enabled

Yes

Enabled

Disabled

Yes

Enabled

Omitted

Yes

Disabled

Enabled

Yes

Omitted

Enabled

Yes

Disabled

Disabled

No

Omitted

Disabled

No

Omitted

Omitted

No

  1. Using the secureBoot field.

  2. Using the virtualizedTrustedPlatformModule field.

For more information about related features and functionality, see the Microsoft Azure documentation about Trusted launch for Azure virtual machines.

Procedure

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

  2. Edit the following section under the providerSpec field to provide a valid configuration:

    Sample valid configuration with UEFI Secure Boot and vTPM enabled

    1. apiVersion: machine.openshift.io/v1
    2. kind: ControlPlaneMachineSet
    3. # ...
    4. spec:
    5.   template:
    6.     spec:
    7.       providerSpec:
    8.         value:
    9.           securityProfile:
    10.             settings:
    11.               securityType: TrustedLaunch (1)
    12.               trustedLaunch:
    13.                 uefiSettings: (2)
    14.                   secureBoot: Enabled (3)
    15.                   virtualizedTrustedPlatformModule: Enabled (4)
    16. # ...
    1Enables the use of trusted launch for Azure virtual machines. This value is required for all valid configurations.
    2Specifies which UEFI security features to use. This section is required for all valid configurations.
    3Enables UEFI Secure Boot.
    4Enables the use of a vTPM.

Verification

  • On the Azure portal, review the details for a machine deployed by the machine set and verify that the trusted launch options match the values that you configured.

Configuring Azure confidential virtual machines by using machine sets

Using Azure confidential virtual machines 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.

OKD 4 supports Azure confidential virtual machines (VMs).

Confidential VMs are currently not supported on 64-bit ARM architectures.

By editing the machine set YAML file, you can configure the confidential VM options that a machine set uses for machines that it deploys. For example, you can configure these machines to use UEFI security features such as Secure Boot or a dedicated virtual Trusted Platform Module (vTPM) instance.

Not all instance types support confidential VMs. Do not change the instance type for a control plane machine set that is configured to use confidential VMs to a type that is incompatible. Using an incompatible instance type can cause your cluster to become unstable.

For more information about related features and functionality, see the Microsoft Azure documentation about Confidential virtual machines.

Procedure

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

  2. Edit the following section under the providerSpec field:

    Sample configuration

    1. apiVersion: machine.openshift.io/v1
    2. kind: ControlPlaneMachineSet
    3. # ...
    4. spec:
    5.   template:
    6.     spec:
    7.       providerSpec:
    8.         value:
    9.           osDisk:
    10.             # ...
    11.             managedDisk:
    12.               securityProfile: (1)
    13.                 securityEncryptionType: VMGuestStateOnly (2)
    14.             # ...
    15.           securityProfile: (3)
    16.             settings:
    17.                 securityType: ConfidentialVM (4)
    18.                 confidentialVM:
    19.                   uefiSettings: (5)
    20.                     secureBoot: Disabled (6)
    21.                     virtualizedTrustedPlatformModule: Enabled (7)
    22.           vmSize: Standard_DC16ads_v5 (8)
    23. # ...
    1Specifies security profile settings for the managed disk when using a confidential VM.
    2Enables encryption of the Azure VM Guest State (VMGS) blob. This setting requires the use of vTPM.
    3Specifies security profile settings for the confidential VM.
    4Enables the use of confidential VMs. This value is required for all valid configurations.
    5Specifies which UEFI security features to use. This section is required for all valid configurations.
    6Disables UEFI Secure Boot.
    7Enables the use of a vTPM.
    8Specifies an instance type that supports confidential VMs.

Verification

  • On the Azure portal, review the details for a machine deployed by the machine set and verify that the confidential VM options match the values that you configured.

Accelerated Networking for Microsoft Azure VMs

Accelerated Networking uses single root I/O virtualization (SR-IOV) to provide Microsoft Azure VMs with a more direct path to the switch. This enhances network performance. This feature can be enabled after installation.

Limitations

Consider the following limitations when deciding whether to use Accelerated Networking:

  • Accelerated Networking is only supported on clusters where the Machine API is operational.

  • Accelerated Networking requires an Azure VM size that includes at least four vCPUs. To satisfy this requirement, you can change the value of vmSize in your machine set. For information about Azure VM sizes, see Microsoft Azure documentation.

Enabling Accelerated Networking on an existing Microsoft Azure cluster

You can enable Accelerated Networking on Azure by adding acceleratedNetworking to your machine set YAML file.

Prerequisites

  • Have an existing Microsoft Azure cluster where the Machine API is operational.

Procedure

  • Add the following to the providerSpec field:

    1. providerSpec:
    2.   value:
    3.     acceleratedNetworking: true (1)
    4.     vmSize: <azure-vm-size> (2)
    1This line enables Accelerated Networking.
    2Specify an Azure VM size that includes at least four vCPUs. For information about VM sizes, see Microsoft Azure documentation.

Verification

  • On the Microsoft Azure portal, review the Networking settings page for a machine provisioned by the machine set, and verify that the Accelerated networking field is set to Enabled.

Enabling Google Cloud Platform features for control plane machines

You can enable Google Cloud Platform (GCP) features on control plane machines by changing the configuration of your 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.

Configuring persistent disk types by using machine sets

You can configure the type of persistent disk that a machine set deploys machines on by editing the machine set YAML file.

For more information about persistent disk types, compatibility, regional availability, and limitations, see the GCP Compute Engine documentation about persistent disks.

Procedure

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

  2. Edit the following line under the providerSpec field:

    1. apiVersion: machine.openshift.io/v1
    2. kind: ControlPlaneMachineSet
    3. ...
    4. spec:
    5.   template:
    6.     spec:
    7.       providerSpec:
    8.         value:
    9.           disks:
    10.             type: <pd-disk-type> (1)
    1Specify the disk persistent type. Valid values are pd-ssd, pd-standard, and pd-balanced. The default value is pd-standard.

Verification

  • Using the Google Cloud console, review the details for a machine deployed by the machine set and verify that the Type field matches the configured disk type.

Configuring Confidential VM by using machine sets

By editing the machine set YAML file, you can configure the Confidential VM options that a machine set uses for machines that it deploys.

For more information about Confidential VM features, functions, and compatibility, see the GCP Compute Engine documentation about Confidential VM.

Confidential VMs are currently not supported on 64-bit ARM architectures.

OKD 4 does not support some Confidential Compute features, such as Confidential VMs with AMD Secure Encrypted Virtualization Secure Nested Paging (SEV-SNP).

Procedure

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

  2. Edit the following section under the providerSpec field:

    1. apiVersion: machine.openshift.io/v1
    2. kind: ControlPlaneMachineSet
    3. ...
    4. spec:
    5.   template:
    6.     spec:
    7.       providerSpec:
    8.         value:
    9.           confidentialCompute: Enabled (1)
    10.           onHostMaintenance: Terminate (2)
    11.           machineType: n2d-standard-8 (3)
    12. ...
    1Specify whether Confidential VM is enabled. Valid values are Disabled or Enabled.
    2Specify the behavior of the VM during a host maintenance event, such as a hardware or software update. For a machine that uses Confidential VM, this value must be set to Terminate, which stops the VM. Confidential VM does not support live VM migration.
    3Specify a machine type that supports Confidential VM. Confidential VM supports the N2D and C2D series of machine types.

Verification

  • On the Google Cloud console, review the details for a machine deployed by the machine set and verify that the Confidential VM options match the values that you configured.

Configuring Shielded VM options by using machine sets

By editing the machine set YAML file, you can configure the Shielded VM options that a machine set uses for machines that it deploys.

For more information about Shielded VM features and functionality, see the GCP Compute Engine documentation about Shielded VM.

Procedure

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

  2. Edit the following section under the providerSpec field:

    1. apiVersion: machine.openshift.io/v1
    2. kind: ControlPlaneMachineSet
    3. # ...
    4. spec:
    5.   template:
    6.     spec:
    7.       providerSpec:
    8.         value:
    9.           shieldedInstanceConfig: (1)
    10.             integrityMonitoring: Enabled (2)
    11.             secureBoot: Disabled (3)
    12.             virtualizedTrustedPlatformModule: Enabled (4)
    13. # ...
    1In this section, specify any Shielded VM options that you want.
    2Specify whether integrity monitoring is enabled. Valid values are Disabled or Enabled.

    When integrity monitoring is enabled, you must not disable virtual trusted platform module (vTPM).

    3Specify whether UEFI Secure Boot is enabled. Valid values are Disabled or Enabled.
    4Specify whether vTPM is enabled. Valid values are Disabled or Enabled.

Verification

  • Using the Google Cloud console, review the details for a machine deployed by the machine set and verify that the Shielded VM options match the values that you configured.

Additional resources

Enabling customer-managed encryption keys for a machine set

Google Cloud Platform (GCP) Compute Engine allows users to supply an encryption key to encrypt data on disks at rest. The key is used to encrypt the data encryption key, not to encrypt the customer’s data. By default, Compute Engine encrypts this data by using Compute Engine keys.

You can enable encryption with a customer-managed key in clusters that use the Machine API. You must first create a KMS key and assign the correct permissions to a service account. The KMS key name, key ring name, and location are required to allow a service account to use your key.

If you do not want to use a dedicated service account for the KMS encryption, the Compute Engine default service account is used instead. You must grant the default service account permission to access the keys if you do not use a dedicated service account. The Compute Engine default service account name follows the service-<project_number>@compute-system.iam.gserviceaccount.com pattern.

Procedure

  1. To allow a specific service account to use your KMS key and to grant the service account the correct IAM role, run the following command with your KMS key name, key ring name, and location:

    1. $ gcloud kms keys add-iam-policy-binding <key_name> \
    2.   --keyring <key_ring_name> \
    3.   --location <key_ring_location> \
    4.   --member "serviceAccount:service-<project_number>@compute-system.iam.gserviceaccount.com” \
    5.   --role roles/cloudkms.cryptoKeyEncrypterDecrypter

  2. Configure the encryption key under the providerSpec field in your machine set YAML file. For example:

    1. apiVersion: machine.openshift.io/v1
    2. kind: ControlPlaneMachineSet
    3. ...
    4. spec:
    5.   template:
    6.     spec:
    7.       providerSpec:
    8.         value:
    9.           disks:
    10.           - type:
    11.             encryptionKey:
    12.               kmsKey:
    13.                 name: machine-encryption-key (1)
    14.                 keyRing: openshift-encrpytion-ring (2)
    15.                 location: global (3)
    16.                 projectID: openshift-gcp-project (4)
    17.               kmsKeyServiceAccount: openshift-service-account@openshift-gcp-project.iam.gserviceaccount.com (5)
    1The name of the customer-managed encryption key that is used for the disk encryption.
    2The name of the KMS key ring that the KMS key belongs to.
    3The GCP location in which the KMS key ring exists.
    4Optional: The ID of the project in which the KMS key ring exists. If a project ID is not set, the machine set projectID in which the machine set was created is used.
    5Optional: The service account that is used for the encryption request for the given KMS key. If a service account is not set, the Compute Engine default service account is used.

    When a new machine is created by using the updated providerSpec object configuration, the disk encryption key is encrypted with the KMS key.

Updating the configuration for OpenStack control plane machines

You can configure OpenStack control plane machines by changing the configuration of your 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.

Changing the OpenStack compute flavor by using a control plane machine set

You can change the OpenStack compute service (Nova) flavor that your control plane machines use by updating the specification in the control plane machine set custom resource.

In OpenStack, flavors define the compute, memory, and storage capacity of computing instances. By increasing or decreasing the flavor size, you can scale your control plane vertically.

Prerequisites

  • Your OpenStack cluster uses a control plane machine set.

Procedure

  1. Edit the following line under the providerSpec field:

    1. providerSpec:
    2.   value:
    3. # ...
    4.     flavor: m1.xlarge (1)
    1Specify a OpenStack flavor type that has the same base as the existing selection. For example, you can change m6i.xlarge to m6i.2xlarge or m6i.4xlarge. You can choose larger or smaller flavors depending on your vertical scaling needs.

  2. Save your changes.

After you save your changes, machines are replaced with ones that use the flavor you chose.