Before installing a OKD cluster on your Red Hat Virtualization (RHV) environment, you create a custom virtual machine template and configure your environment so the installation program uses the template.

Creating a custom virtual machine template for RHV is a workaround for a known issue (BZ#1818577). If you do not create a custom virtual machine, the OKD cluster you install will fail.

Prerequisites

Downloading a specific FCOS image to the RHV Manager machine

Download a specific Fedora CoreOS (FCOS) image to the Red Hat Virtualization (RHV) Manager machine.

Do not substitute the FCOS image specified by these instructions with another image.
Procedure
  1. Open a terminal session with the RHV Manager machine. For example, if you run the Manager as a self-hosted engine:

    1. Go to the RHV Administration Portal and go to the ComputeVirtual Machines page.

    2. Select the HostedEngine virtual machine and click Console.

  2. On the Manager’s command line, create a working directory and change to it.

    $ mkdir rhcos
    $ cd rhcos
  3. In a browser, go to https://github.com/openshift/installer/blob/release-4.4/data/data/rhcos.json.

  4. In rhcos.json, find baseURI and copy its value.

  5. On the Manager, start a wget command and paste the value of baseURI but do not press Enter. For example:

    $ wget https://releases-art-rhcos.svc.ci.openshift.org/art/storage/releases/rhcos-4.4/44.81.202003062006-0/x86_64/
  6. In rhcos.json document, find openstack and copy the value of path.

  7. On the Manager, paste the value of path. For example:

    $ wget https://releases-art-rhcos.svc.ci.openshift.org/art/storage/releases/rhcos-4.4/44.81.202003062006-0/x86_64/rhcos-44.81.202003062006-0-openstack.x86_64.qcow2.gz
  8. Press Enter and wait for wget to finish downloading the FCOS image.

  9. Unzip the FCOS image. For example:

    $ gunzip rhcos*

Using an Ansible playbook to upload an FCOS image to a data storage domain

Use an Ansible playbook to upload an Fedora CoreOS (FCOS) image to a data storage domain.

Procedure
  1. Create an Ansible playbook file upload_rhcos_disk.yaml on the Red Hat Virtualization (RHV) Manager. For example:

    $ vi upload_rhcos_disk.yaml
  2. Go to this file on the Red Hat Customer Portal.

  3. Paste its contents into your playbook.

  4. In your playbook, update the parameter values that have callouts.

    - hosts: localhost
      gather_facts: no
      tasks:
        - name: Authenticate with engine
          ovirt_auth:
            url: https://<virtlab.example.com>/ovirt-engine/api (1)
            username: <username@profile> (2)
            password: <password> (3)
            insecure: yes
    
        - name: Upload FCOS image
          ovirt_disk:
            auth: "{{ ovirt_auth }}"
            name: <rhcos_44-81_img-diskname> (4)
            size: 120GiB (5)
            interface: virtio_scsi
            storage_domain: <SSD_RAID_10> (6)
            bootable: yes
            timeout: 3600 (7)
            upload_image_path: </custom/rhcos-44.81.202003110027-0-openstack.x86_64.qcow2> (8)
            wait: yes
    1 For <virtlab.example.com>, specify the fully-qualified domain name (FQDN) of your RHV Manager.
    2 For <username@profile>, specify the admin user name and profile.
    3 For <password>, specify the admin password.
    4 For <rhcos_44-81_img-diskname>, specify a disk name.
    5 Specify 120GiB or more for production environments. For resource-constrained or non-production environments, specify 32GiB or more.
    6 For <SSD_RAID_10>, specify a data storage domain name.
    7 Specify a timeout period, in seconds, that gives your RHV environment enough time to upload a 2.4 GB image to storage. The default value, 3600 seconds, gives one hour.
    8 For </custom/rhcos-44.81.202003110027-0-openstack.x86_64.qcow2>, specify the image path and file name.
  5. On the Manager, run the Ansible playbook. For example:

    $ ansible-playbook rhcos_image.yaml -vvv
  6. In the Administration Portal, go to the StorageDisks page and find the disk name you specified in the playbook. For example, rhcos_44-81_img-diskname.

  7. When the status of the disk is OK, the playbook has finished uploading the FCOS image to the storage domain.

Determining the resources available to customize your virtual machine template

Otherwise, if you plan to install a cluster on RHV with customizations, consider the following information.

You can customize the virtual machine template the installation program uses to create the control and compute machines in your OKD cluster. You can customize the template so these machines have more than the default virtual CPU, memory, and storage resources. Your customizations apply equally to both control and compute machines; they cannot be customized differently.

Over-allocating resources can cause the installation or operation of your cluster to fail. To avoid over-allocating resources, you must determine how much of each resource is available for each virtual machine: Inspect the resources in your Red Hat Virtualization (RHV) cluster and divide them by the number of virtual machines. The resulting quotients are the maximum values you can allocate for each resource.

Procedure
  1. Inspect the available resources in your RHV cluster.

    1. Go to Verifying the requirements for the RHV environment

    2. Record the values of the storage Free Space, Logical CPU Cores, and Max free Memory for scheduling new VMs.

  2. Record the number of virtual machines in your OKD cluster.

    • By default, your cluster contains seven machines.

    • You can also customize the number of machines, as described in Installation configuration parameters for RHV. To account for the bootstrap machine, add one machine to the number in the configuration file.

  3. Divide each resource by the number of virtual machines.

  4. Record these values for use later on.

Attaching the virtual disk with the FCOS image to a virtual machine

Attach the virtual disk with the Fedora CoreOS (FCOS) image to a virtual machine.

Procedure
  1. Go to the ComputeVirtual Machines page and click New.

  2. In the New Virtual MachineGeneral window that opens, use Cluster to select the RHV cluster where you plan to create the OKD cluster.

  3. Leave Template unchanged, with Blank selected.

  4. Set Operating System to Red Hat Enterprise Linux CoreOS.

  5. Leave Optimized for unchanged, with Desktop selected.

  6. For Name, specify the name of the virtual machine. For example, vmname.

  7. For Instance Images, click Attach.

  8. In the Attach Virtual Disks window that opens, find the disk you specified in the playbook. For example, rhcos_44-81_img-diskname.

  9. Click the radio button for this disk.

  10. Select the OS checkbox for this disk. This makes the disk bootable.

  11. Click OK to save and close the Attach Virtual Disks window.

Configuring and creating of the virtual machine

Continue configuring the virtual machine and then create it.

Procedure
  1. In the New Virtual MachineGeneral window, for each NIC under Instantiate VM network interfaces by picking a vNIC profile, select a vNIC profile.

  2. Go to the New Virtual MachineSystem window.

  3. Set Memory Size to 16384 MB or more. This default value is equivalent to 16 GiB. You can adjust this value according to the workload you expect on the compute machines and the amount of memory resources that are available.

  4. Due to a known issue (bz#1821215), set Physical Memory Guaranteed to 8192 MB. This value is equivalent to 8 GiB.

  5. Set Total Virtual CPUs to 4 or more. You can adjust this value according to the workload you expect on the compute machines and the resources that are available.

  6. Expand Advanced Parameters.

  7. Adjust Cores per Virtual Socket to 4 or more so it matches the Total Virtual CPUs setting.

  8. Press OK to save and close the New Virtual Machine.

    The new virtual machine appears in the ComputeVirtual Machines window. Because the virtual machine is not starting, it appears quickly.

Creating a virtual machine template

Create the virtual machine template.

Procedure
  1. Select the new virtual machine.

  2. In the upper-right corner of the Administration Portal window, click the More actions menu, and select Make Template.

  3. In the New Template window, specify a value for the Name. For example, vm-tmpltname.

  4. Verify that Target and the other parameter values are correct and reflect your previous choices.

  5. Verify that Seal Template (Linux only) is not selected.

  6. Click OK.

  7. Go to the ComputeTemplates page and wait for the template to be created.

Exporting some environment variables

Using these environment variables to customize the install is a temporary workaround for a known issue (BZ#1818577). This content might be removed in a future release.
  1. Determine the values you specified for Memory and Total Virtual CPUs in the virtual machine settings.

  2. Run the following environment variables on the command line of your installation machine.

$ export OPENSHIFT_INSTALL_OS_IMAGE_OVERRIDE=<vm-tmpltname> (1)
$ export TF_VAR_ovirt_template_mem=<mem-value> (2)
$ export TF_VAR_ovirt_template_cpu=<cpu-value> (3)
$ export TF_VAR_ovirt_master_mem=<mem-value> (2)
$ export TF_VAR_ovirt_master_cpu=<cpu-value> (3)
1 For <vm-tmpltname>, specify the name of the template that you created.
2 For <mem-value>, specify the value of Memory in MB, in the virtual machine. For example, 16384.
3 For <cpu-value>, specify value of Total Virtual CPUs in the virtual machine. For example, 4.

For example:

$ export OPENSHIFT_INSTALL_OS_IMAGE_OVERRIDE=vm-tmpltname
$ export TF_VAR_ovirt_template_mem=16384
$ export TF_VAR_ovirt_template_cpu=4
$ export TF_VAR_ovirt_master_mem=16384
$ export TF_VAR_ovirt_master_cpu=4