Creating a compute machine set on AWS
You can create a different compute machine set to serve a specific purpose in your OpenShift Container Platform cluster on Amazon Web Services (AWS). For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines.
Important
You can use the advanced machine management and scaling capabilities only in clusters where the Machine API is operational. Clusters with user-provisioned infrastructure require additional validation and configuration to use the Machine API.
Clusters with the infrastructure platform type none cannot use the Machine API. This limitation applies even if the compute machines that are attached to the cluster are installed on a platform that supports the feature. This parameter cannot be changed after installation.
To view the platform type for your cluster, run the following command:
$ oc get infrastructure cluster -o jsonpath='{.status.platform}'
Sample YAML for a compute machine set custom resource on AWS
The sample YAML defines a compute machine set that runs in the us-east-1a Amazon Web Services (AWS) Local Zone and creates nodes that are labeled with
node-role.kubernetes.io/<role>: "".
In this sample, <infrastructure_id> is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and
<role>
is the node label to add.
apiVersion: machine.openshift.io/v1beta1
kind: MachineSet
metadata:
labels:
machine.openshift.io/cluster-api-cluster: <infrastructure_id>
name: <infrastructure_id>-<role>-<zone>
namespace: openshift-machine-api
spec:
replicas: 1
selector:
matchLabels:
machine.openshift.io/cluster-api-cluster: <infrastructure_id>
machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role>-<zone>
template:
metadata:
labels:
machine.openshift.io/cluster-api-cluster: <infrastructure_id>
machine.openshift.io/cluster-api-machine-role: <role>
machine.openshift.io/cluster-api-machine-type: <role>
machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role>-<zone>
spec:
metadata:
labels:
node-role.kubernetes.io/<role>: ""
providerSpec:
value:
ami:
id: ami-046fe691f52a953f9
apiVersion: machine.openshift.io/v1beta1
blockDevices:
- ebs:
iops: 0
volumeSize: 120
volumeType: gp2
credentialsSecret:
name: aws-cloud-credentials
deviceIndex: 0
iamInstanceProfile:
id: <infrastructure_id>-worker-profile
instanceType: m6i.large
kind: AWSMachineProviderConfig
placement:
availabilityZone: <zone>
region: <region>
securityGroups:
- filters:
- name: tag:Name
values:
- <infrastructure_id>-node
- filters:
- name: tag:Name
values:
- <infrastructure_id>-lb
subnet:
filters:
- name: tag:Name
values:
- <infrastructure_id>-private-<zone>
tags:
- name: kubernetes.io/cluster/<infrastructure_id>
value: owned
- name: <custom_tag_name>
value: <custom_tag_value>
userDataSecret:
name: worker-user-data
- Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI installed, you can obtain the infrastructure ID by running the following command:
$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster - Specify the infrastructure ID, role node label, and zone.
- Specify the role node label to add.
- Specify a valid Red Hat Enterprise Linux CoreOS (RHCOS) Amazon
Machine Image (AMI) for your AWS zone for your OpenShift Container Platform nodes. If you want to use an AWS Marketplace image, you must complete the OpenShift Container Platform subscription from the AWS Marketplace to obtain an AMI ID for your region.
$ oc -n openshift-machine-api \ -o jsonpath='{.spec.template.spec.providerSpec.value.ami.id}{"\n"}' \ get machineset/<infrastructure_id>-<role>-<zone> - Specify the zone name, for example,
us-east-1a. - Specify the region, for example,
us-east-1. - Specify the infrastructure ID and zone.
- Optional: Specify custom tag data for your cluster. For example, you might add an admin contact email address by specifying a
name:valuepair ofEmail:admin-email@example.com.Note
Custom tags can also be specified during installation in the
install-config.ymlfile. If theinstall-config.ymlfile and the machine set include a tag with the samenamedata, the value for the tag from the machine set takes priority over the value for the tag in theinstall-config.ymlfile.
Creating a compute machine set
In addition to the compute machine sets created by the installation program, you can create your own to dynamically manage the machine compute resources for specific workloads of your choice.
-
Deploy an OpenShift Container Platform cluster.
-
Install the OpenShift CLI (
oc). -
Log in to
ocas a user withcluster-adminpermission.
-
Create a new YAML file that contains the compute machine set custom resource (CR) sample and is named
<file_name>.yaml.Ensure that you set the
<clusterID>and<role>parameter values. -
Optional: If you are not sure which value to set for a specific field, you can check an existing compute machine set from your cluster.
-
To list the compute machine sets in your cluster, run the following command:
$ oc get machinesets -n openshift-machine-apiExample outputNAME DESIRED CURRENT READY AVAILABLE AGE agl030519-vplxk-worker-us-east-1a 1 1 1 1 55m agl030519-vplxk-worker-us-east-1b 1 1 1 1 55m agl030519-vplxk-worker-us-east-1c 1 1 1 1 55m agl030519-vplxk-worker-us-east-1d 0 0 55m agl030519-vplxk-worker-us-east-1e 0 0 55m agl030519-vplxk-worker-us-east-1f 0 0 55m -
To view values of a specific compute machine set custom resource (CR), run the following command:
$ oc get machineset <machineset_name> \ -n openshift-machine-api -o yamlExample outputapiVersion: machine.openshift.io/v1beta1 kind: MachineSet metadata: labels: machine.openshift.io/cluster-api-cluster: <infrastructure_id> name: <infrastructure_id>-<role> namespace: openshift-machine-api spec: replicas: 1 selector: matchLabels: machine.openshift.io/cluster-api-cluster: <infrastructure_id> machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role> template: metadata: labels: machine.openshift.io/cluster-api-cluster: <infrastructure_id> machine.openshift.io/cluster-api-machine-role: <role> machine.openshift.io/cluster-api-machine-type: <role> machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role> spec: providerSpec: ...- The cluster infrastructure ID.
- A default node label.
Note
For clusters that have user-provisioned infrastructure, a compute machine set can only create
workerandinfratype machines. - 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.
-
-
Create a
MachineSetCR by running the following command:$ oc create -f <file_name>.yaml -
If you need compute machine sets in other availability zones, repeat this process to create more compute machine sets.
-
View the list of compute machine sets by running the following command:
$ oc get machineset -n openshift-machine-apiExample outputNAME DESIRED CURRENT READY AVAILABLE AGE agl030519-vplxk-infra-us-east-1a 1 1 1 1 11m agl030519-vplxk-worker-us-east-1a 1 1 1 1 55m agl030519-vplxk-worker-us-east-1b 1 1 1 1 55m agl030519-vplxk-worker-us-east-1c 1 1 1 1 55m agl030519-vplxk-worker-us-east-1d 0 0 55m agl030519-vplxk-worker-us-east-1e 0 0 55m agl030519-vplxk-worker-us-east-1f 0 0 55mWhen the new compute machine set is available, the
DESIREDandCURRENTvalues match. If the compute machine set is not available, wait a few minutes and run the command again.
Labeling GPU machine sets for the cluster autoscaler
You can use a machine set label to indicate which machines the cluster autoscaler can use to deploy GPU-enabled nodes.
-
Your cluster uses a cluster autoscaler.
-
On the machine set that you want to create machines for the cluster autoscaler to use to deploy GPU-enabled nodes, add a
cluster-api/acceleratorlabel:apiVersion: machine.openshift.io/v1beta1 kind: MachineSet metadata: name: machine-set-name spec: template: spec: metadata: labels: cluster-api/accelerator: <accelerator_name>where:
- <accelerator_name>
-
Specifies a label of your choice that consists of alphanumeric characters,
-,_, or.and starts and ends with an alphanumeric character. For example, you might usenvidia-t4to represent Nvidia T4 GPUs, ornvidia-a10gfor A10G GPUs.Note
You must specify the value of this label for the
spec.resourceLimits.gpus.typeparameter in yourClusterAutoscalerCR. For more information, see "Cluster autoscaler resource definition".
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.
-
You created a placement group in the AWS console.
Note
Ensure that the rules and limitations for the type of placement group that you create are compatible with your intended use case.
-
In a text editor, open the YAML file for an existing machine set or create a new one.
-
Edit the following lines under the
providerSpecfield:apiVersion: machine.openshift.io/v1beta1 kind: MachineSet # ... spec: template: spec: providerSpec: value: instanceType: <supported_instance_type> networkInterfaceType: EFA placement: availabilityZone: <zone> region: <region> placementGroupName: <placement_group> placementGroupPartition: <placement_group_partition_number> # ...- Specify an instance type that supports EFAs.
- Specify the
EFAnetwork interface type. - Specify the zone, for example,
us-east-1a. - Specify the region, for example,
us-east-1. - Specify the name of the existing AWS placement group to deploy machines in.
- Optional: Specify the partition number of the existing AWS placement group to deploy machines in.
-
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
placementGroupNameparameter in the machine set. -
The partition number field has the value that you specified for the
placementGroupPartitionparameter 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.
Note
To use IMDSv2 on AWS clusters that were created with OpenShift Container Platform version 4.6 or earlier, you must update your boot image. For more information, see "Boot image management".
To deploy new compute machines with your preferred IMDS configuration, create a compute machine set YAML file with the appropriate values. You can also edit an existing machine set to create new machines with your preferred IMDS configuration when the machine set is scaled up.
Important
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.
-
To use IMDSv2, your AWS cluster must have been created with OpenShift Container Platform version 4.7 or later.
-
Add or edit the following lines under the
providerSpecfield:providerSpec: value: metadataServiceOptions: authentication: Required- To require IMDSv2, set the parameter value to
Required. To allow the use of both IMDSv1 and IMDSv2, set the parameter value toOptional. If no value is specified, both IMDSv1 and IMDSv2 are allowed.
- To require IMDSv2, set the parameter value to
Configuring storage throughput for gp3 drives
You can improve performance for high traffic services by increasing the throughput of gp3 storage volumes in an AWS cluster. You can configure the storage throughput by editing your compute or control plane machine set.
-
You use gp3 storage volume(s).
-
Add or edit the following lines under the
providerSpecfield in your compute or control plane machine set:providerSpec: value: blockDevices: - ebs: throughputMib: <throughput_value>where:
<throughput_value>-
Specifies a value in MiB per second between 125 and 2,000. You can only edit this value on gp3 volumes. The default value is
125.
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.
-
Specify a dedicated tenancy under the
providerSpecfield:providerSpec: placement: tenancy: dedicated
Machine sets that deploy machines as Spot Instances
You can save on costs by creating a compute machine set running on AWS that deploys machines as non-guaranteed Spot Instances. Spot Instances use unused AWS EC2 capacity and are less expensive than On-Demand Instances. You can use Spot Instances for workloads that can tolerate interruptions, such as batch or stateless, horizontally scalable workloads.
AWS EC2 can terminate a Spot Instance at any time. AWS gives a two-minute warning to the user when an interruption occurs. OpenShift Container Platform begins to remove the workloads from the affected instances when AWS issues the termination warning.
Interruptions can occur when using Spot Instances for the following reasons:
-
The instance price exceeds your maximum price
-
The demand for Spot Instances increases
-
The supply of Spot Instances decreases
When AWS terminates an instance, a termination handler running on the Spot Instance node deletes the machine resource. To satisfy the compute machine set replicas quantity, the compute machine set creates a machine that requests a Spot Instance.
Creating Spot Instances by using compute machine sets
You can save on costs by creating a compute machine set that deploys machines as non-guaranteed instances.
To launch a Spot Instance on AWS, you add spotMarketOptions to your compute machine set YAML file.
-
Add the following line under the
providerSpecfield:providerSpec: value: spotMarketOptions: {}You can optionally set the
spotMarketOptions.maxPricefield to limit the cost of the Spot Instance. For example you can setmaxPrice: '2.50'.If the
maxPriceis set, this value is used as the hourly maximum spot price. If it is not set, the maximum price defaults to charge up to the On-Demand Instance price.Note
It is strongly recommended to use the default On-Demand price as the
maxPricevalue and to not set the maximum price for Spot Instances.
Configuring Capacity Reservations by using machine sets
OpenShift Container Platform version 4.19 and later supports Capacity Reservations on Amazon Web Services clusters, including On-Demand Capacity Reservations and Capacity Blocks for ML.
You can configure a machine set to deploy machines on any available resources that match the parameters of a capacity request that you define. These parameters specify the instance type, region, and number of instances that you want to reserve. If your Capacity Reservation can accommodate the capacity request, the deployment succeeds.
For more information, including limitations and suggested use cases for this AWS offering, see On-Demand Capacity Reservations and Capacity Blocks for ML in the AWS documentation.
-
You have access to the cluster with
cluster-adminprivileges. -
You installed the OpenShift CLI (
oc). -
You purchased an On-Demand Capacity Reservation or Capacity Block for ML. For more information, see On-Demand Capacity Reservations and Capacity Blocks for ML in the AWS documentation.
-
In a text editor, open the YAML file for an existing machine set or create a new one.
-
Edit the following section under the
providerSpecfield:Sample configurationapiVersion: machine.openshift.io/v1beta1 kind: MachineSet # ... spec: template: spec: providerSpec: value: capacityReservationId: <capacity_reservation> marketType: <market_type> # ...- Specify the ID of the Capacity Block for ML or On-Demand Capacity Reservation that you want the machine set to deploy machines on.
- Specify the market type to use.
The following values are valid:
CapacityBlock-
Use this market type with Capacity Blocks for ML.
OnDemand-
Use this market type with On-Demand Capacity Reservations.
Spot-
Use this market type with Spot Instances. This option is not compatible with Capacity Reservations.
-
To verify machine deployment, list the machines that the machine set created by running the following command:
$ oc get machines.machine.openshift.io \ -n openshift-machine-api \ -l machine.openshift.io/cluster-api-machineset=<machine_set_name>where
<machine_set_name>is the name of the compute machine set.In the output, verify that the characteristics of the listed machines match the parameters of your Capacity Reservation.
Adding a GPU node to an existing OpenShift Container Platform cluster
You can copy and modify a default compute machine set configuration to create a GPU-enabled machine set and machines for the AWS EC2 cloud provider.
For more information about the supported instance types, see the following NVIDIA documentation:
-
View the existing nodes, machines, and machine sets by running the following command. Note that each node is an instance of a machine definition with a specific AWS region and OpenShift Container Platform role.
$ oc get nodesExample outputNAME STATUS ROLES AGE VERSION ip-10-0-52-50.us-east-2.compute.internal Ready worker 3d17h v1.34.2 ip-10-0-58-24.us-east-2.compute.internal Ready control-plane,master 3d17h v1.34.2 ip-10-0-68-148.us-east-2.compute.internal Ready worker 3d17h v1.34.2 ip-10-0-68-68.us-east-2.compute.internal Ready control-plane,master 3d17h v1.34.2 ip-10-0-72-170.us-east-2.compute.internal Ready control-plane,master 3d17h v1.34.2 ip-10-0-74-50.us-east-2.compute.internal Ready worker 3d17h v1.34.2 -
View the machines and machine sets that exist in the
openshift-machine-apinamespace by running the following command. Each compute machine set is associated with a different availability zone within the AWS region. The installer automatically load balances compute machines across availability zones.$ oc get machinesets -n openshift-machine-apiExample outputNAME DESIRED CURRENT READY AVAILABLE AGE preserve-dsoc12r4-ktjfc-worker-us-east-2a 1 1 1 1 3d11h preserve-dsoc12r4-ktjfc-worker-us-east-2b 2 2 2 2 3d11h -
View the machines that exist in the
openshift-machine-apinamespace by running the following command. At this time, there is only one compute machine per machine set, though a compute machine set could be scaled to add a node in a particular region and zone.$ oc get machines -n openshift-machine-api | grep workerExample outputpreserve-dsoc12r4-ktjfc-worker-us-east-2a-dts8r Running m5.xlarge us-east-2 us-east-2a 3d11h preserve-dsoc12r4-ktjfc-worker-us-east-2b-dkv7w Running m5.xlarge us-east-2 us-east-2b 3d11h preserve-dsoc12r4-ktjfc-worker-us-east-2b-k58cw Running m5.xlarge us-east-2 us-east-2b 3d11h -
Make a copy of one of the existing compute
MachineSetdefinitions and output the result to a JSON file by running the following command. This will be the basis for the GPU-enabled compute machine set definition.$ oc get machineset preserve-dsoc12r4-ktjfc-worker-us-east-2a -n openshift-machine-api -o json > <output_file.json> -
Edit the JSON file and make the following changes to the new
MachineSetdefinition:-
Replace
workerwithgpu. This will be the name of the new machine set. -
Change the instance type of the new
MachineSetdefinition tog4dn, which includes an NVIDIA Tesla T4 GPU. To learn more about AWSg4dninstance types, see Accelerated Computing.$ jq .spec.template.spec.providerSpec.value.instanceType preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a.json "g4dn.xlarge"The
<output_file.json>file is saved aspreserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a.json.
-
-
Update the following fields in
preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a.json:-
.metadata.nameto a name containinggpu. -
.spec.selector.matchLabels["machine.openshift.io/cluster-api-machineset"]to match the new.metadata.name. -
.spec.template.metadata.labels["machine.openshift.io/cluster-api-machineset"]to match the new.metadata.name. -
.spec.template.spec.providerSpec.value.instanceTypetog4dn.xlarge.
-
-
To verify your changes, perform a
diffof the original compute definition and the new GPU-enabled node definition by running the following command:$ oc -n openshift-machine-api get preserve-dsoc12r4-ktjfc-worker-us-east-2a -o json | diff preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a.json -Example output10c10 < "name": "preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a", --- > "name": "preserve-dsoc12r4-ktjfc-worker-us-east-2a", 21c21 < "machine.openshift.io/cluster-api-machineset": "preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a" --- > "machine.openshift.io/cluster-api-machineset": "preserve-dsoc12r4-ktjfc-worker-us-east-2a" 31c31 < "machine.openshift.io/cluster-api-machineset": "preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a" --- > "machine.openshift.io/cluster-api-machineset": "preserve-dsoc12r4-ktjfc-worker-us-east-2a" 60c60 < "instanceType": "g4dn.xlarge", --- > "instanceType": "m5.xlarge", -
Create the GPU-enabled compute machine set from the definition by running the following command:
$ oc create -f preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a.jsonExample outputmachineset.machine.openshift.io/preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a created
-
View the machine set you created by running the following command:
$ oc -n openshift-machine-api get machinesets | grep gpuThe MachineSet replica count is set to
1so a newMachineobject is created automatically.Example outputpreserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a 1 1 1 1 4m21s -
View the
Machineobject that the machine set created by running the following command:$ oc -n openshift-machine-api get machines | grep gpuExample outputpreserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a running g4dn.xlarge us-east-2 us-east-2a 4m36s
Note that there is no need to specify a namespace for the node. The node definition is cluster scoped.
Deploying the Node Feature Discovery Operator
After the GPU-enabled node is created, you need to discover the GPU-enabled node so it can be scheduled. To do this, install the Node Feature Discovery (NFD) Operator. The NFD Operator identifies hardware device features in nodes. It solves the general problem of identifying and cataloging hardware resources in the infrastructure nodes so they can be made available to OpenShift Container Platform.
-
Install the Node Feature Discovery Operator from the software catalog in the OpenShift Container Platform console.
-
After installing the NFD Operator, select Node Feature Discovery from the installed Operators list and select Create instance. This installs the
nfd-masterandnfd-workerpods, onenfd-workerpod for each compute node, in theopenshift-nfdnamespace. -
Verify that the Operator is installed and running by running the following command:
$ oc get pods -n openshift-nfdExample outputNAME READY STATUS RESTARTS AGE nfd-controller-manager-8646fcbb65-x5qgk 2/2 Running 7 (8h ago) 1d -
Browse to the installed Oerator in the console and select Create Node Feature Discovery.
-
Select Create to build a NFD custom resource. This creates NFD pods in the
openshift-nfdnamespace that poll the OpenShift Container Platform nodes for hardware resources and catalogue them.
-
After a successful build, verify that a NFD pod is running on each nodes by running the following command:
$ oc get pods -n openshift-nfdExample outputNAME READY STATUS RESTARTS AGE nfd-controller-manager-8646fcbb65-x5qgk 2/2 Running 7 (8h ago) 12d nfd-master-769656c4cb-w9vrv 1/1 Running 0 12d nfd-worker-qjxb2 1/1 Running 3 (3d14h ago) 12d nfd-worker-xtz9b 1/1 Running 5 (3d14h ago) 12dThe NFD Operator uses vendor PCI IDs to identify hardware in a node. NVIDIA uses the PCI ID
10de. -
View the NVIDIA GPU discovered by the NFD Operator by running the following command:
$ oc describe node ip-10-0-132-138.us-east-2.compute.internal | egrep 'Roles|pci'Example outputRoles: worker feature.node.kubernetes.io/pci-1013.present=true feature.node.kubernetes.io/pci-10de.present=true feature.node.kubernetes.io/pci-1d0f.present=true10deappears in the node feature list for the GPU-enabled node. This mean the NFD Operator correctly identified the node from the GPU-enabled MachineSet.