Chapter 2. Managing compute machines with the Machine API

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

4. If you need compute machine sets in other availability zones, repeat this process to create more compute machine sets.

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/v1beta1
   kind: MachineSet
   # ...
   spec:
     template:
       spec:
         providerSpec:
           value:
             instanceType: <supported_instance_type> 1
             networkInterfaceType: EFA 2
             placement:
               availabilityZone: <zone> 3
               region: <region> 4
             placementGroupName: <placement_group> 5
             placementGroupPartition: <placement_group_partition_number> 6
   # ...

   1

   Specify an instance type that supports EFAs.

   2

   Specify the EFA network interface type.

   3

   Specify the zone, for example, us-east-1a.

   4

   Specify the region, for example, us-east-1.

   5

   Specify the name of the existing AWS placement group to deploy machines in.

   6

   Optional: Specify the partition number of the existing AWS placement group to deploy machines in.

Procedure

1. 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 nodes

   Example output

   NAME                                        STATUS   ROLES                  AGE     VERSION
   ip-10-0-52-50.us-east-2.compute.internal    Ready    worker                 3d17h   v1.30.3
   ip-10-0-58-24.us-east-2.compute.internal    Ready    control-plane,master   3d17h   v1.30.3
   ip-10-0-68-148.us-east-2.compute.internal   Ready    worker                 3d17h   v1.30.3
   ip-10-0-68-68.us-east-2.compute.internal    Ready    control-plane,master   3d17h   v1.30.3
   ip-10-0-72-170.us-east-2.compute.internal   Ready    control-plane,master   3d17h   v1.30.3
   ip-10-0-74-50.us-east-2.compute.internal    Ready    worker                 3d17h   v1.30.3

2. View the machines and machine sets that exist in the openshift-machine-api namespace 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-api

   Example output

   NAME                                        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

3. View the machines that exist in the openshift-machine-api namespace 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 worker

   Example output

   preserve-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

4. Make a copy of one of the existing compute MachineSet definitions 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>

5. Edit the JSON file and make the following changes to the new MachineSet definition:

   • Replace worker with gpu. This will be the name of the new machine set.

   • Change the instance type of the new MachineSet definition to g4dn, which includes an NVIDIA Tesla T4 GPU. To learn more about AWS g4dn instance 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 as preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a.json.

6. Update the following fields in preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a.json:

   • .metadata.name to a name containing gpu.
   • .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.instanceType to g4dn.xlarge.

7. To verify your changes, perform a diff of 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 output

   10c10
   
   < "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",

8. 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.json

   Example output

   machineset.machine.openshift.io/preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a created

Verification

1. View the machine set you created by running the following command:

   $ oc -n openshift-machine-api get machinesets | grep gpu

   The MachineSet replica count is set to 1 so a new Machine object is created automatically.

   Example output

   preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a   1         1         1       1           4m21s

2. View the Machine object that the machine set created by running the following command:

   $ oc -n openshift-machine-api get machines | grep gpu

   Example output

   preserve-dsoc12r4-ktjfc-worker-gpu-us-east-2a    running    g4dn.xlarge   us-east-2   us-east-2a  4m36s

Procedure

1. Install the Node Feature Discovery Operator from OperatorHub in the OpenShift Container Platform console.
2. After installing the NFD Operator into OperatorHub, select Node Feature Discovery from the installed Operators list and select Create instance. This installs the nfd-master and nfd-worker pods, one nfd-worker pod for each compute node, in the openshift-nfd namespace.

3. Verify that the Operator is installed and running by running the following command:

   $ oc get pods -n openshift-nfd

   Example output

   NAME                                       READY    STATUS     RESTARTS   AGE
   
   nfd-controller-manager-8646fcbb65-x5qgk    2/2      Running 7  (8h ago)   1d

4. Browse to the installed Oerator in the console and select Create Node Feature Discovery.
5. Select Create to build a NFD custom resource. This creates NFD pods in the openshift-nfd namespace that poll the OpenShift Container Platform nodes for hardware resources and catalogue them.

Verification

1. After a successful build, verify that a NFD pod is running on each nodes by running the following command:

   $ oc get pods -n openshift-nfd

   Example output

   NAME                                       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)   12d

   The NFD Operator uses vendor PCI IDs to identify hardware in a node. NVIDIA uses the PCI ID 10de.

2. 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 output

   Roles: worker
   
   feature.node.kubernetes.io/pci-1013.present=true
   
   feature.node.kubernetes.io/pci-10de.present=true
   
   feature.node.kubernetes.io/pci-1d0f.present=true

   10de appears in the node feature list for the GPU-enabled node. This mean the NFD Operator correctly identified the node from the GPU-enabled MachineSet.

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

Procedure

1. Display all of the available OpenShift Container Platform images by running one of the following commands:

   • North America:

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

     Example output

     Offer          Publisher       Sku                 Urn                                                             Version
     -------------  --------------  ------------------  --------------------------------------------------------------  -----------------
     rh-ocp-worker  RedHat          rh-ocp-worker       RedHat:rh-ocp-worker:rh-ocp-worker:4.15.2024072409              4.15.2024072409
     rh-ocp-worker  RedHat          rh-ocp-worker-gen1  RedHat:rh-ocp-worker:rh-ocp-worker-gen1:4.15.2024072409         4.15.2024072409

   • EMEA:

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

     Example output

     Offer          Publisher       Sku                 Urn                                                                     Version
     -------------  --------------  ------------------  --------------------------------------------------------------          -----------------
     rh-ocp-worker  redhat-limited  rh-ocp-worker       redhat-limited:rh-ocp-worker:rh-ocp-worker:4.15.2024072409              4.15.2024072409
     rh-ocp-worker  redhat-limited  rh-ocp-worker-gen1  redhat-limited:rh-ocp-worker:rh-ocp-worker-gen1:4.15.2024072409         4.15.2024072409

   Note

   Use the latest image that is available for compute and control plane nodes. 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:

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

   • EMEA:

     $ 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:

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

   • EMEA:

     $ 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:

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

   • EMEA:

     $ 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

   providerSpec:
     value:
       image:
         offer: rh-ocp-worker
         publisher: redhat
         resourceID: ""
         sku: rh-ocp-worker
         type: MarketplaceWithPlan
         version: 413.92.2023101700

1. Using the secureBoot field.
2. Using the virtualizedTrustedPlatformModule field.

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

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   # ...
   spec:
     template:
       machines_v1beta1_machine_openshift_io:
         spec:
           providerSpec:
             value:
               securityProfile:
                 settings:
                   securityType: TrustedLaunch 1
                   trustedLaunch:
                     uefiSettings: 2
                       secureBoot: Enabled 3
                       virtualizedTrustedPlatformModule: Enabled 4
   # ...

   1

   Enables the use of trusted launch for Azure virtual machines. This value is required for all valid configurations.

   2

   Specifies which UEFI security features to use. This section is required for all valid configurations.

   3

   Enables UEFI Secure Boot.

   4

   Enables the use of a vTPM.

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

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   # ...
   spec:
     template:
       spec:
         providerSpec:
           value:
             osDisk:
               # ...
               managedDisk:
                 securityProfile: 1
                   securityEncryptionType: VMGuestStateOnly 2
               # ...
             securityProfile: 3
               settings:
                   securityType: ConfidentialVM 4
                   confidentialVM:
                     uefiSettings: 5
                       secureBoot: Disabled 6
                       virtualizedTrustedPlatformModule: Enabled 7
             vmSize: Standard_DC16ads_v5 8
   # ...

   1

   Specifies security profile settings for the managed disk when using a confidential VM.

   2

   Enables encryption of the Azure VM Guest State (VMGS) blob. This setting requires the use of vTPM.

   3

   Specifies security profile settings for the confidential VM.

   4

   Enables the use of confidential VMs. This value is required for all valid configurations.

   5

   Specifies which UEFI security features to use. This section is required for all valid configurations.

   6

   Disables UEFI Secure Boot.

   7

   Enables the use of a vTPM.

   8

   Specifies an instance type that supports confidential VMs.

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

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   # ...
   spec:
     template:
       spec:
         providerSpec:
           value:
             capacityReservationGroupID: <capacity_reservation_group> 1
   # ...

   1

   Specify the ID of the Capacity Reservation group that you want the machine set to deploy machines on.

Procedure

1. View the machines and machine sets that exist in the openshift-machine-api namespace by running the following command. Each compute machine set is associated with a different availability zone within the Azure region. The installer automatically load balances compute machines across availability zones.

   $ oc get machineset -n openshift-machine-api

   Example output

   NAME                              DESIRED   CURRENT   READY   AVAILABLE   AGE
   myclustername-worker-centralus1   1         1         1       1           6h9m
   myclustername-worker-centralus2   1         1         1       1           6h9m
   myclustername-worker-centralus3   1         1         1       1           6h9m

2. Make a copy of one of the existing compute MachineSet definitions and output the result to a YAML file by running the following command. This will be the basis for the GPU-enabled compute machine set definition.

   $ oc get machineset -n openshift-machine-api myclustername-worker-centralus1 -o yaml > machineset-azure.yaml

3. View the content of the machineset:

   $ cat machineset-azure.yaml

   Example machineset-azure.yaml file

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   metadata:
     annotations:
       machine.openshift.io/GPU: "0"
       machine.openshift.io/memoryMb: "16384"
       machine.openshift.io/vCPU: "4"
     creationTimestamp: "2023-02-06T14:08:19Z"
     generation: 1
     labels:
       machine.openshift.io/cluster-api-cluster: myclustername
       machine.openshift.io/cluster-api-machine-role: worker
       machine.openshift.io/cluster-api-machine-type: worker
     name: myclustername-worker-centralus1
     namespace: openshift-machine-api
     resourceVersion: "23601"
     uid: acd56e0c-7612-473a-ae37-8704f34b80de
   spec:
     replicas: 1
     selector:
       matchLabels:
         machine.openshift.io/cluster-api-cluster: myclustername
         machine.openshift.io/cluster-api-machineset: myclustername-worker-centralus1
     template:
       metadata:
         labels:
           machine.openshift.io/cluster-api-cluster: myclustername
           machine.openshift.io/cluster-api-machine-role: worker
           machine.openshift.io/cluster-api-machine-type: worker
           machine.openshift.io/cluster-api-machineset: myclustername-worker-centralus1
       spec:
         lifecycleHooks: {}
         metadata: {}
         providerSpec:
           value:
             acceleratedNetworking: true
             apiVersion: machine.openshift.io/v1beta1
             credentialsSecret:
               name: azure-cloud-credentials
               namespace: openshift-machine-api
             diagnostics: {}
             image:
               offer: ""
               publisher: ""
               resourceID: /resourceGroups/myclustername-rg/providers/Microsoft.Compute/galleries/gallery_myclustername_n6n4r/images/myclustername-gen2/versions/latest
               sku: ""
               version: ""
             kind: AzureMachineProviderSpec
             location: centralus
             managedIdentity: myclustername-identity
             metadata:
               creationTimestamp: null
             networkResourceGroup: myclustername-rg
             osDisk:
               diskSettings: {}
               diskSizeGB: 128
               managedDisk:
                 storageAccountType: Premium_LRS
               osType: Linux
             publicIP: false
             publicLoadBalancer: myclustername
             resourceGroup: myclustername-rg
             spotVMOptions: {}
             subnet: myclustername-worker-subnet
             userDataSecret:
               name: worker-user-data
             vmSize: Standard_D4s_v3
             vnet: myclustername-vnet
             zone: "1"
   status:
     availableReplicas: 1
     fullyLabeledReplicas: 1
     observedGeneration: 1
     readyReplicas: 1
     replicas: 1

4. Make a copy of the machineset-azure.yaml file by running the following command:

   $ cp machineset-azure.yaml machineset-azure-gpu.yaml

5. Update the following fields in machineset-azure-gpu.yaml:

   • Change .metadata.name to a name containing gpu.
   • Change .spec.selector.matchLabels["machine.openshift.io/cluster-api-machineset"] to match the new .metadata.name.
   • Change .spec.template.metadata.labels["machine.openshift.io/cluster-api-machineset"] to match the new .metadata.name.

   • Change .spec.template.spec.providerSpec.value.vmSize to Standard_NC4as_T4_v3.

     Example machineset-azure-gpu.yaml file

     apiVersion: machine.openshift.io/v1beta1
     kind: MachineSet
     metadata:
       annotations:
         machine.openshift.io/GPU: "1"
         machine.openshift.io/memoryMb: "28672"
         machine.openshift.io/vCPU: "4"
       creationTimestamp: "2023-02-06T20:27:12Z"
       generation: 1
       labels:
         machine.openshift.io/cluster-api-cluster: myclustername
         machine.openshift.io/cluster-api-machine-role: worker
         machine.openshift.io/cluster-api-machine-type: worker
       name: myclustername-nc4ast4-gpu-worker-centralus1
       namespace: openshift-machine-api
       resourceVersion: "166285"
       uid: 4eedce7f-6a57-4abe-b529-031140f02ffa
     spec:
       replicas: 1
       selector:
         matchLabels:
           machine.openshift.io/cluster-api-cluster: myclustername
           machine.openshift.io/cluster-api-machineset: myclustername-nc4ast4-gpu-worker-centralus1
       template:
         metadata:
           labels:
             machine.openshift.io/cluster-api-cluster: myclustername
             machine.openshift.io/cluster-api-machine-role: worker
             machine.openshift.io/cluster-api-machine-type: worker
             machine.openshift.io/cluster-api-machineset: myclustername-nc4ast4-gpu-worker-centralus1
         spec:
           lifecycleHooks: {}
           metadata: {}
           providerSpec:
             value:
               acceleratedNetworking: true
               apiVersion: machine.openshift.io/v1beta1
               credentialsSecret:
                 name: azure-cloud-credentials
                 namespace: openshift-machine-api
               diagnostics: {}
               image:
                 offer: ""
                 publisher: ""
                 resourceID: /resourceGroups/myclustername-rg/providers/Microsoft.Compute/galleries/gallery_myclustername_n6n4r/images/myclustername-gen2/versions/latest
                 sku: ""
                 version: ""
               kind: AzureMachineProviderSpec
               location: centralus
               managedIdentity: myclustername-identity
               metadata:
                 creationTimestamp: null
               networkResourceGroup: myclustername-rg
               osDisk:
                 diskSettings: {}
                 diskSizeGB: 128
                 managedDisk:
                   storageAccountType: Premium_LRS
                 osType: Linux
               publicIP: false
               publicLoadBalancer: myclustername
               resourceGroup: myclustername-rg
               spotVMOptions: {}
               subnet: myclustername-worker-subnet
               userDataSecret:
                 name: worker-user-data
               vmSize: Standard_NC4as_T4_v3
               vnet: myclustername-vnet
               zone: "1"
     status:
       availableReplicas: 1
       fullyLabeledReplicas: 1
       observedGeneration: 1
       readyReplicas: 1
       replicas: 1

6. To verify your changes, perform a diff of the original compute definition and the new GPU-enabled node definition by running the following command:

   $ diff machineset-azure.yaml machineset-azure-gpu.yaml

   Example output

   14c14
   <   name: myclustername-worker-centralus1
   ---
   >   name: myclustername-nc4ast4-gpu-worker-centralus1
   23c23
   <       machine.openshift.io/cluster-api-machineset: myclustername-worker-centralus1
   ---
   >       machine.openshift.io/cluster-api-machineset: myclustername-nc4ast4-gpu-worker-centralus1
   30c30
   <         machine.openshift.io/cluster-api-machineset: myclustername-worker-centralus1
   ---
   >         machine.openshift.io/cluster-api-machineset: myclustername-nc4ast4-gpu-worker-centralus1
   67c67
   <           vmSize: Standard_D4s_v3
   ---
   >           vmSize: Standard_NC4as_T4_v3

7. Create the GPU-enabled compute machine set from the definition file by running the following command:

   $ oc create -f machineset-azure-gpu.yaml

   Example output

   machineset.machine.openshift.io/myclustername-nc4ast4-gpu-worker-centralus1 created

8. View the machines and machine sets that exist in the openshift-machine-api namespace by running the following command. Each compute machine set is associated with a different availability zone within the Azure region. The installer automatically load balances compute machines across availability zones.

   $ oc get machineset -n openshift-machine-api

   Example output

   NAME                                               DESIRED   CURRENT   READY   AVAILABLE   AGE
   clustername-n6n4r-nc4ast4-gpu-worker-centralus1    1         1         1       1           122m
   clustername-n6n4r-worker-centralus1                1         1         1       1           8h
   clustername-n6n4r-worker-centralus2                1         1         1       1           8h
   clustername-n6n4r-worker-centralus3                1         1         1       1           8h

9. View the machines that exist in the openshift-machine-api namespace by running the following command. You can only configure one compute machine per set, although you can scale a compute machine set to add a node in a particular region and zone.

   $ oc get machines -n openshift-machine-api

   Example output

   NAME                                                PHASE     TYPE                   REGION      ZONE   AGE
   myclustername-master-0                              Running   Standard_D8s_v3        centralus   2      6h40m
   myclustername-master-1                              Running   Standard_D8s_v3        centralus   1      6h40m
   myclustername-master-2                              Running   Standard_D8s_v3        centralus   3      6h40m
   myclustername-nc4ast4-gpu-worker-centralus1-w9bqn   Running      centralus   1      21m
   myclustername-worker-centralus1-rbh6b               Running   Standard_D4s_v3        centralus   1      6h38m
   myclustername-worker-centralus2-dbz7w               Running   Standard_D4s_v3        centralus   2      6h38m
   myclustername-worker-centralus3-p9b8c               Running   Standard_D4s_v3        centralus   3      6h38m

10. 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 Azure region and OpenShift Container Platform role.

    $ oc get nodes

    Example output

    NAME                                                STATUS   ROLES                  AGE     VERSION
    myclustername-master-0                              Ready    control-plane,master   6h39m   v1.30.3
    myclustername-master-1                              Ready    control-plane,master   6h41m   v1.30.3
    myclustername-master-2                              Ready    control-plane,master   6h39m   v1.30.3
    myclustername-nc4ast4-gpu-worker-centralus1-w9bqn   Ready    worker                 14m     v1.30.3
    myclustername-worker-centralus1-rbh6b               Ready    worker                 6h29m   v1.30.3
    myclustername-worker-centralus2-dbz7w               Ready    worker                 6h29m   v1.30.3
    myclustername-worker-centralus3-p9b8c               Ready    worker                 6h31m   v1.30.3

11. View the list of compute machine sets:

    $ oc get machineset -n openshift-machine-api

    Example output

    NAME                                   DESIRED   CURRENT   READY   AVAILABLE   AGE
    myclustername-worker-centralus1        1         1         1       1           8h
    myclustername-worker-centralus2        1         1         1       1           8h
    myclustername-worker-centralus3        1         1         1       1           8h

12. Create the GPU-enabled compute machine set from the definition file by running the following command:

    $ oc create -f machineset-azure-gpu.yaml

13. View the list of compute machine sets:

    oc get machineset -n openshift-machine-api

    Example output

    NAME                                          DESIRED   CURRENT   READY   AVAILABLE   AGE
    myclustername-nc4ast4-gpu-worker-centralus1   1         1         1       1           121m
    myclustername-worker-centralus1               1         1         1       1           8h
    myclustername-worker-centralus2               1         1         1       1           8h
    myclustername-worker-centralus3               1         1         1       1           8h

Verification

1. View the machine set you created by running the following command:

   $ oc get machineset -n openshift-machine-api | grep gpu

   The MachineSet replica count is set to 1 so a new Machine object is created automatically.

   Example output

   myclustername-nc4ast4-gpu-worker-centralus1   1         1         1       1           121m

2. View the Machine object that the machine set created by running the following command:

   $ oc -n openshift-machine-api get machines | grep gpu

   Example output

   myclustername-nc4ast4-gpu-worker-centralus1-w9bqn   Running   Standard_NC4as_T4_v3   centralus   1      21m

Procedure

1. Install the Node Feature Discovery Operator from OperatorHub in the OpenShift Container Platform console.
2. After installing the NFD Operator into OperatorHub, select Node Feature Discovery from the installed Operators list and select Create instance. This installs the nfd-master and nfd-worker pods, one nfd-worker pod for each compute node, in the openshift-nfd namespace.

3. Verify that the Operator is installed and running by running the following command:

   $ oc get pods -n openshift-nfd

   Example output

   NAME                                       READY    STATUS     RESTARTS   AGE
   
   nfd-controller-manager-8646fcbb65-x5qgk    2/2      Running 7  (8h ago)   1d

4. Browse to the installed Oerator in the console and select Create Node Feature Discovery.
5. Select Create to build a NFD custom resource. This creates NFD pods in the openshift-nfd namespace that poll the OpenShift Container Platform nodes for hardware resources and catalogue them.

Verification

1. After a successful build, verify that a NFD pod is running on each nodes by running the following command:

   $ oc get pods -n openshift-nfd

   Example output

   NAME                                       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)   12d

   The NFD Operator uses vendor PCI IDs to identify hardware in a node. NVIDIA uses the PCI ID 10de.

2. 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 output

   Roles: worker
   
   feature.node.kubernetes.io/pci-1013.present=true
   
   feature.node.kubernetes.io/pci-10de.present=true
   
   feature.node.kubernetes.io/pci-1d0f.present=true

   10de appears in the node feature list for the GPU-enabled node. This mean the NFD Operator correctly identified the node from the GPU-enabled MachineSet.

Procedure

1. 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 <availabilitySet>, <clusterID>, and <role> parameter values.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

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:

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   ...
   spec:
     template:
       spec:
         providerSpec:
           value:
             disks:
               type: <pd-disk-type> 1

   1

   Specify the persistent disk type. Valid values are pd-ssd, pd-standard, and pd-balanced. The default value is pd-standard.

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:

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   ...
   spec:
     template:
       spec:
         providerSpec:
           value:
             confidentialCompute: Enabled 1
             onHostMaintenance: Terminate 2
             machineType: n2d-standard-8 3
   ...

   1

   Specify whether Confidential VM is enabled. Valid values are Disabled or Enabled.

   2

   Specify 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.

   3

   Specify a machine type that supports Confidential VM. Confidential VM supports the N2D and C2D series of machine types.

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:

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   # ...
   spec:
     template:
       spec:
         providerSpec:
           value:
             shieldedInstanceConfig: 1
               integrityMonitoring: Enabled 2
               secureBoot: Disabled 3
               virtualizedTrustedPlatformModule: Enabled 4
   # ...

   1

   In this section, specify any Shielded VM options that you want.

   2

   Specify whether integrity monitoring is enabled. Valid values are Disabled or Enabled.

   Note

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

   3

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

   4

   Specify whether vTPM is enabled. Valid values are Disabled or Enabled.

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:

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

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

   apiVersion: machine.openshift.io/v1beta1
   kind: MachineSet
   ...
   spec:
     template:
       spec:
         providerSpec:
           value:
             disks:
             - type:
               encryptionKey:
                 kmsKey:
                   name: machine-encryption-key 1
                   keyRing: openshift-encrpytion-ring 2
                   location: global 3
                   projectID: openshift-gcp-project 4
                 kmsKeyServiceAccount: openshift-service-account@openshift-gcp-project.iam.gserviceaccount.com 5

   1

   The name of the customer-managed encryption key that is used for the disk encryption.

   2

   The name of the KMS key ring that the KMS key belongs to.

   3

   The GCP location in which the KMS key ring exists.

   4

   Optional: 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.

   5

   Optional: 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.

1. For more information about machine types, including specifications, compatibility, regional availability, and limitations, see the GCP Compute Engine documentation about N1 machine series, A2 machine series, and GPU regions and zones availability.

Procedure

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

2. Specify a GPU configuration under the providerSpec field in your compute machine set YAML file. See the following examples of valid configurations:

   Example configuration for the A2 machine series

     providerSpec:
       value:
         machineType: a2-highgpu-1g 1
         onHostMaintenance: Terminate 2
         restartPolicy: Always 3

   1

   Specify the machine type. Ensure that the machine type is included in the A2 machine series.

   2

   When using GPU support, you must set onHostMaintenance to Terminate.

   3

   Specify the restart policy for machines deployed by the compute machine set. Allowed values are Always or Never.

   Example configuration for the N1 machine series

   providerSpec:
     value:
       gpus:
       - count: 1 1
         type: nvidia-tesla-p100 2
       machineType: n1-standard-1 3
       onHostMaintenance: Terminate 4
       restartPolicy: Always 5

   1

   Specify the number of GPUs to attach to the machine.

   2

   Specify the type of GPUs to attach to the machine. Ensure that the machine type and GPU type are compatible.

   3

   Specify the machine type. Ensure that the machine type and GPU type are compatible.

   4

   When using GPU support, you must set onHostMaintenance to Terminate.

   5

   Specify the restart policy for machines deployed by the compute machine set. Allowed values are Always or Never.

Procedure

1. Make a copy of an existing MachineSet.
2. In the new copy, change the machine set name in metadata.name and in both instances of machine.openshift.io/cluster-api-machineset.

3. Change the instance type to add the following two lines to the newly copied MachineSet:

   machineType: a2-highgpu-1g
   onHostMaintenance: Terminate

   Example a2-highgpu-1g.json file

   {
       "apiVersion": "machine.openshift.io/v1beta1",
       "kind": "MachineSet",
       "metadata": {
           "annotations": {
               "machine.openshift.io/GPU": "0",
               "machine.openshift.io/memoryMb": "16384",
               "machine.openshift.io/vCPU": "4"
           },
           "creationTimestamp": "2023-01-13T17:11:02Z",
           "generation": 1,
           "labels": {
               "machine.openshift.io/cluster-api-cluster": "myclustername-2pt9p"
           },
           "name": "myclustername-2pt9p-worker-gpu-a",
           "namespace": "openshift-machine-api",
           "resourceVersion": "20185",
           "uid": "2daf4712-733e-4399-b4b4-d43cb1ed32bd"
       },
       "spec": {
           "replicas": 1,
           "selector": {
               "matchLabels": {
                   "machine.openshift.io/cluster-api-cluster": "myclustername-2pt9p",
                   "machine.openshift.io/cluster-api-machineset": "myclustername-2pt9p-worker-gpu-a"
               }
           },
           "template": {
               "metadata": {
                   "labels": {
                       "machine.openshift.io/cluster-api-cluster": "myclustername-2pt9p",
                       "machine.openshift.io/cluster-api-machine-role": "worker",
                       "machine.openshift.io/cluster-api-machine-type": "worker",
                       "machine.openshift.io/cluster-api-machineset": "myclustername-2pt9p-worker-gpu-a"
                   }
               },
               "spec": {
                   "lifecycleHooks": {},
                   "metadata": {},
                   "providerSpec": {
                       "value": {
                           "apiVersion": "machine.openshift.io/v1beta1",
                           "canIPForward": false,
                           "credentialsSecret": {
                               "name": "gcp-cloud-credentials"
                           },
                           "deletionProtection": false,
                           "disks": [
                               {
                                   "autoDelete": true,
                                   "boot": true,
                                   "image": "projects/rhcos-cloud/global/images/rhcos-412-86-202212081411-0-gcp-x86-64",
                                   "labels": null,
                                   "sizeGb": 128,
                                   "type": "pd-ssd"
                               }
                           ],
                           "kind": "GCPMachineProviderSpec",
                           "machineType": "a2-highgpu-1g",
                           "onHostMaintenance": "Terminate",
                           "metadata": {
                               "creationTimestamp": null
                           },
                           "networkInterfaces": [
                               {
                                   "network": "myclustername-2pt9p-network",
                                   "subnetwork": "myclustername-2pt9p-worker-subnet"
                               }
                           ],
                           "preemptible": true,
                           "projectID": "myteam",
                           "region": "us-central1",
                           "serviceAccounts": [
                               {
                                   "email": "myclustername-2pt9p-w@myteam.iam.gserviceaccount.com",
                                   "scopes": [
                                       "https://www.googleapis.com/auth/cloud-platform"
                                   ]
                               }
                           ],
                           "tags": [
                               "myclustername-2pt9p-worker"
                           ],
                           "userDataSecret": {
                               "name": "worker-user-data"
                           },
                           "zone": "us-central1-a"
                       }
                   }
               }
           }
       },
       "status": {
           "availableReplicas": 1,
           "fullyLabeledReplicas": 1,
           "observedGeneration": 1,
           "readyReplicas": 1,
           "replicas": 1
       }
   }

4. 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 GCP region and OpenShift Container Platform role.

   $ oc get nodes

   Example output

   NAME                                                             STATUS     ROLES                  AGE     VERSION
   myclustername-2pt9p-master-0.c.openshift-qe.internal             Ready      control-plane,master   8h      v1.30.3
   myclustername-2pt9p-master-1.c.openshift-qe.internal             Ready      control-plane,master   8h      v1.30.3
   myclustername-2pt9p-master-2.c.openshift-qe.internal             Ready      control-plane,master   8h      v1.30.3
   myclustername-2pt9p-worker-a-mxtnz.c.openshift-qe.internal       Ready      worker                 8h      v1.30.3
   myclustername-2pt9p-worker-b-9pzzn.c.openshift-qe.internal       Ready      worker                 8h      v1.30.3
   myclustername-2pt9p-worker-c-6pbg6.c.openshift-qe.internal       Ready      worker                 8h      v1.30.3
   myclustername-2pt9p-worker-gpu-a-wxcr6.c.openshift-qe.internal   Ready      worker                 4h35m   v1.30.3

5. View the machines and machine sets that exist in the openshift-machine-api namespace by running the following command. Each compute machine set is associated with a different availability zone within the GCP region. The installer automatically load balances compute machines across availability zones.

   $ oc get machinesets -n openshift-machine-api

   Example output

   NAME                               DESIRED   CURRENT   READY   AVAILABLE   AGE
   myclustername-2pt9p-worker-a       1         1         1       1           8h
   myclustername-2pt9p-worker-b       1         1         1       1           8h
   myclustername-2pt9p-worker-c       1         1                             8h
   myclustername-2pt9p-worker-f       0         0                             8h

6. View the machines that exist in the openshift-machine-api namespace by running the following command. You can only configure one compute machine per set, although you can scale a compute machine set to add a node in a particular region and zone.

   $ oc get machines -n openshift-machine-api | grep worker

   Example output

   myclustername-2pt9p-worker-a-mxtnz       Running   n2-standard-4   us-central1   us-central1-a   8h
   myclustername-2pt9p-worker-b-9pzzn       Running   n2-standard-4   us-central1   us-central1-b   8h
   myclustername-2pt9p-worker-c-6pbg6       Running   n2-standard-4   us-central1   us-central1-c   8h

7. Make a copy of one of the existing compute MachineSet definitions 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 myclustername-2pt9p-worker-a -n openshift-machine-api -o json  > <output_file.json>

8. Edit the JSON file to make the following changes to the new MachineSet definition:

   • Rename the machine set name by inserting the substring gpu in metadata.name and in both instances of machine.openshift.io/cluster-api-machineset.

   • Change the machineType of the new MachineSet definition to a2-highgpu-1g, which includes an NVIDIA A100 GPU.

     jq .spec.template.spec.providerSpec.value.machineType ocp_4.17_machineset-a2-highgpu-1g.json
     
     "a2-highgpu-1g"

     The <output_file.json> file is saved as ocp_4.17_machineset-a2-highgpu-1g.json.

9. Update the following fields in ocp_4.17_machineset-a2-highgpu-1g.json:

   • Change .metadata.name to a name containing gpu.
   • Change .spec.selector.matchLabels["machine.openshift.io/cluster-api-machineset"] to match the new .metadata.name.
   • Change .spec.template.metadata.labels["machine.openshift.io/cluster-api-machineset"] to match the new .metadata.name.
   • Change .spec.template.spec.providerSpec.value.MachineType to a2-highgpu-1g.

   • Add the following line under machineType: `"onHostMaintenance": "Terminate". For example:

     "machineType": "a2-highgpu-1g",
     "onHostMaintenance": "Terminate",

10. To verify your changes, perform a diff of the original compute definition and the new GPU-enabled node definition by running the following command:

    $ oc get machineset/myclustername-2pt9p-worker-a -n openshift-machine-api -o json | diff ocp_4.17_machineset-a2-highgpu-1g.json -

    Example output

    15c15
    <         "name": "myclustername-2pt9p-worker-gpu-a",
    ---
    >         "name": "myclustername-2pt9p-worker-a",
    25c25
    <                 "machine.openshift.io/cluster-api-machineset": "myclustername-2pt9p-worker-gpu-a"
    ---
    >                 "machine.openshift.io/cluster-api-machineset": "myclustername-2pt9p-worker-a"
    34c34
    <                     "machine.openshift.io/cluster-api-machineset": "myclustername-2pt9p-worker-gpu-a"
    ---
    >                     "machine.openshift.io/cluster-api-machineset": "myclustername-2pt9p-worker-a"
    59,60c59
    <                         "machineType": "a2-highgpu-1g",
    <                         "onHostMaintenance": "Terminate",
    ---
    >                         "machineType": "n2-standard-4",

11. Create the GPU-enabled compute machine set from the definition file by running the following command:

    $ oc create -f ocp_4.17_machineset-a2-highgpu-1g.json

    Example output

    machineset.machine.openshift.io/myclustername-2pt9p-worker-gpu-a created

Verification

1. View the machine set you created by running the following command:

   $ oc -n openshift-machine-api get machinesets | grep gpu

   The MachineSet replica count is set to 1 so a new Machine object is created automatically.

   Example output

   myclustername-2pt9p-worker-gpu-a   1         1         1       1           5h24m

2. View the Machine object that the machine set created by running the following command:

   $ oc -n openshift-machine-api get machines | grep gpu

   Example output

   myclustername-2pt9p-worker-gpu-a-wxcr6   Running   a2-highgpu-1g   us-central1   us-central1-a   5h25m

Procedure

1. Install the Node Feature Discovery Operator from OperatorHub in the OpenShift Container Platform console.
2. After installing the NFD Operator into OperatorHub, select Node Feature Discovery from the installed Operators list and select Create instance. This installs the nfd-master and nfd-worker pods, one nfd-worker pod for each compute node, in the openshift-nfd namespace.

3. Verify that the Operator is installed and running by running the following command:

   $ oc get pods -n openshift-nfd

   Example output

   NAME                                       READY    STATUS     RESTARTS   AGE
   
   nfd-controller-manager-8646fcbb65-x5qgk    2/2      Running 7  (8h ago)   1d

4. Browse to the installed Oerator in the console and select Create Node Feature Discovery.
5. Select Create to build a NFD custom resource. This creates NFD pods in the openshift-nfd namespace that poll the OpenShift Container Platform nodes for hardware resources and catalogue them.

Verification

1. After a successful build, verify that a NFD pod is running on each nodes by running the following command:

   $ oc get pods -n openshift-nfd

   Example output

   NAME                                       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)   12d

   The NFD Operator uses vendor PCI IDs to identify hardware in a node. NVIDIA uses the PCI ID 10de.

2. 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 output

   Roles: worker
   
   feature.node.kubernetes.io/pci-1013.present=true
   
   feature.node.kubernetes.io/pci-10de.present=true
   
   feature.node.kubernetes.io/pci-1d0f.present=true

   10de appears in the node feature list for the GPU-enabled node. This mean the NFD Operator correctly identified the node from the GPU-enabled MachineSet.

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

1. Modify the cluster infrastructure custom resource (CR).
2. Modify the cluster control plane machine set CR.
3. Modify or replace the compute machine set CRs.

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

Procedure

1. To determine whether the required credentials exist, run the following command:

   $ oc get secret \
     -n openshift-machine-api vsphere-cloud-credentials \
     -o go-template='{{range $k,$v := .data}}{{printf "%s: " $k}}{{if not $v}}{{$v}}{{else}}{{$v | base64decode}}{{end}}{{"\n"}}{{end}}'

   Sample output

   <vcenter-server>.password=<openshift-user-password>
   <vcenter-server>.username=<openshift-user>

   where <vcenter-server> is the IP address or fully qualified domain name (FQDN) of the vCenter server and <openshift-user> and <openshift-user-password> are the OpenShift Container Platform administrator credentials to use.

2. If the secret does not exist, create it by running the following command:

   $ oc create secret generic vsphere-cloud-credentials \
     -n openshift-machine-api \
     --from-literal=<vcenter-server>.username=<openshift-user> --from-literal=<vcenter-server>.password=<openshift-user-password>

Procedure

1. To determine whether the required secret exists, run the following command:

   $ oc get secret \
     -n openshift-machine-api worker-user-data \
     -o go-template='{{range $k,$v := .data}}{{printf "%s: " $k}}{{if not $v}}{{$v}}{{else}}{{$v | base64decode}}{{end}}{{"\n"}}{{end}}'

   Sample output

   disableTemplating: false
   userData: 1
     {
       "ignition": {
         ...
         },
       ...
     }

   1

   The full output is omitted here, but should have this format.

2. If the secret does not exist, create it by running the following command:

   $ oc create secret generic worker-user-data \
     -n openshift-machine-api \
     --from-file=<installation_directory>/worker.ign

   where <installation_directory> is the directory that was used to store your installation assets during cluster installation.

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

   3. If you are creating a compute machine set for a cluster that has user-provisioned infrastructure, note the following important values:

      Example vSphere providerSpec values

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      ...
      template:
        ...
        spec:
          providerSpec:
            value:
              apiVersion: machine.openshift.io/v1beta1
              credentialsSecret:
                name: vsphere-cloud-credentials 1
              diskGiB: 120
              kind: VSphereMachineProviderSpec
              memoryMiB: 16384
              network:
                devices:
                  - networkName: "<vm_network_name>"
              numCPUs: 4
              numCoresPerSocket: 4
              snapshot: ""
              template: <vm_template_name> 2
              userDataSecret:
                name: worker-user-data 3
              workspace:
                datacenter: <vcenter_data_center_name>
                datastore: <vcenter_datastore_name>
                folder: <vcenter_vm_folder_path>
                resourcepool: <vsphere_resource_pool>
                server: <vcenter_server_address> 4

      1

      The name of the secret in the openshift-machine-api namespace that contains the required vCenter credentials.

      2

      The name of the RHCOS VM template for your cluster that was created during installation.

      3

      The name of the secret in the openshift-machine-api namespace that contains the required Ignition configuration credentials.

      4

      The IP address or fully qualified domain name (FQDN) of the vCenter server.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml

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/v1beta1
   kind: MachineSet
   # ...
   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.

Procedure

1. 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.

2. 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.

   1. To list the compute machine sets in your cluster, run the following command:

      $ oc get machinesets -n openshift-machine-api

      Example output

      NAME                                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

   2. 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 yaml

      Example output

      apiVersion: machine.openshift.io/v1beta1
      kind: MachineSet
      metadata:
        labels:
          machine.openshift.io/cluster-api-cluster: <infrastructure_id> 1
        name: <infrastructure_id>-<role> 2
        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: 3
              ...

      1

      The cluster infrastructure ID.

      2

      A default node label.

      Note

      For clusters that have user-provisioned infrastructure, a compute machine set can only create worker and infra type machines.

      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.

3. Create a MachineSet CR by running the following command:

   $ oc create -f <file_name>.yaml