Procedure

1. From the OpenShift Container Platform web console, navigate to the Administration → Namespaces page.
2. Click Create Namespace.
3. In the Name field, type openshift-cnv.
4. Click Create.

Procedure

1. Navigate to the Operators → Installed Operators page.
2. Click KubeVirt HyperConverged Cluster Operator.

3. Click the KubeVirt HyperConverged Cluster Operator Deployment tab and click Create HyperConverged.

   1. After you click Create HyperConverged, a YAML file is displayed. Remove the single quotation marks around the word 'false'. This is a workaround for the issue reported in BZ#1767167.

      When it is initially displayed, the YAML file resembles the following example:

      apiVersion: hco.kubevirt.io/v1alpha1
      kind: HyperConverged
      metadata:
        name: kubevirt-hyperconverged
        namespace: openshift-cnv
      spec:
        BareMetalPlatform: 'false' 1

      1

      Ensure that this line reads BareMetalPlatform: false before proceeding to the next step.

4. Click Create to launch container-native virtualization.
5. Navigate to the Workloads → Pods page and monitor the container-native virtualization Pods until they are all Running. After all the Pods display the Running state, you can access container-native virtualization.

Procedure

1. Run the following command:

   $ oc get csv

2. Review the output, checking the PHASE field. For example:

   VERSION  REPLACES                                        PHASE
   2.1.1    kubevirt-hyperconverged-operator.v2.1.0         Installing
   2.1.0                                                    Replacing

3. Optional: Monitor the aggregated status of all container-native virtualization component conditions by running the following command:

   $ oc get hco -n openshift-cnv hyperconverged-cluster \
   -o=jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.message}{"\n"}{end}'

   A successful upgrade results in the following output:

   ReconcileComplete  True  Reconcile completed successfully
   Available          True  Reconcile completed successfully
   Progressing        False Reconcile completed successfully
   Degraded           False Reconcile completed successfully
   Upgradeable        True  Reconcile completed successfully

Procedure

1. From the OpenShift Container Platform web console, select openshift-cnv from the Projects list.
2. Navigate to the Operators → Installed Operators page.
3. Click KubeVirt HyperConverged Cluster Operator.
4. Click the KubeVirt HyperConverged Cluster Operator Deployment tab.
5. Click the Options menu in the row containing the hyperconverged-cluster custom resource. In the expanded menu, click Delete HyperConverged.
6. Click Delete in the confirmation window.
7. Navigate to the Workloads → Pods page to verify that only the Operator Pods are running.

8. Open a terminal window and clean up the remaining KubeVirt resources by running the following command:

   $ oc delete apiservices v1alpha3.subresources.kubevirt.io -n openshift-cnv

   Note

   Because some KubeVirt resources are currently improperly retained, you must manually remove them. These resources will be removed automatically after (BZ1712429) is resolved.

Procedure

1. Navigate to the Catalog → OperatorHub page.
2. Locate the KubeVirt HyperConverged Cluster Operator and then select it.
3. Click Uninstall.

Procedure

1. Navigate to Administration → Namespaces.
2. Locate the namespace that you want to delete in the list of namespaces.
3. On the far right side of the namespace listing, select Delete Namespace from the Options menu .
4. When the Delete Namespace pane opens, enter the name of the namespace that you want to delete in the field.
5. Click Delete.

Procedure

1. Click Workloads → Virtual Machines from the side menu.
2. Click Create Virtual Machine and select Create with Wizard.
3. Fill in all required Basic Settings. Selecting a Template automatically fills in these fields.

4. Click Next to progress to the Networking screen. A nic0 NIC is attached by default.

   1. (Optional) Click Create NIC to create additional NICs.
   2. (Optional) You can remove any or all NICs by clicking the ⋮ button and selecting Remove NIC. A virtual machine does not need a NIC attached to be created. NICs can be created after the virtual machine has been created.

5. Click Next to progress to the Storage screen.

   1. (Optional) Click Create Disk to create additional disks. These disks can be removed by clicking the ⋮ button and selecting Remove Disk.
   2. (Optional) Click on a disk to modify available fields. Click the ✓ button to save the update.
   3. (Optional) Click Attach Disk to choose an available disk from the Select Storage drop-down list.
6. Click Create Virtual Machine >. The Results screen displays the JSON configuration file for the virtual machine.

Procedure

1. Click Workloads → Virtual Machines from the side menu.
2. Click Create Virtual Machine and select Create from YAML.

3. Write or paste your virtual machine configuration in the editable window.

   1. Alternatively, use the example virtual machine provided by default in the YAML screen.
4. (Optional) Click Download to download the YAML configuration file in its present state.
5. Click Create to create the virtual machine.

1. Attach the virtual machine disk to the virtual machine by referencing the relevant PVC claimName as a volume.

2. To create a virtual machine with the OpenShift Container Platform client, run this command:

   $ oc create -f <vm.yaml>

3. Since virtual machines are created in a Stopped state, run a virtual machine instance by starting it.

Procedure

1. Ensure you are in the correct namespace. The ConfigMap can only be referenced by DataVolumes if it is in the same namespace.

   $ oc get ns

2. Create the ConfigMap:

   $ oc create configmap <configmap-name> --from-file=</path/to/file/ca.pem>

Procedure

1. Identify an HTTP file server that hosts the virtual disk image that you want to import. You need the complete URL in the correct format:

   • http://www.example.com/path/to/data

2. If your data source requires authentication credentials, edit the endpoint-secret.yaml file, and apply the updated configuration to the cluster:

   apiVersion: v1
   kind: Secret
   metadata:
     name: <endpoint-secret>
     labels:
       app: containerized-data-importer
   type: Opaque
   data:
     accessKeyId: "" 1
     secretKey:   "" 2

   1

   Optional: your key or user name, base64 encoded

   2

   Optional: your secret or password, base64 encoded

   $ oc apply -f endpoint-secret.yaml

3. Edit the virtual machine configuration file, specifying the data source for the image you want to import. In this example, a Fedora image is imported:

   apiVersion: kubevirt.io/v1alpha3
   kind: VirtualMachine
   metadata:
     creationTimestamp: null
     labels:
       kubevirt.io/vm: vm-fedora-datavolume
     name: vm-fedora-datavolume
   spec:
     dataVolumeTemplates:
     - metadata:
         creationTimestamp: null
         name: fedora-dv
       spec:
         pvc:
           accessModes:
           - ReadWriteOnce
           resources:
             requests:
               storage: 2Gi
           storageClassName: local
         source:
           http:
             url: https://download.fedoraproject.org/pub/fedora/linux/releases/28/Cloud/x86_64/images/Fedora-Cloud-Base-28-1.1.x86_64.qcow2 1
             secretRef: "" 2
             certConfigMap: "" 3
       status: {}
     running: false
     template:
       metadata:
         creationTimestamp: null
         labels:
           kubevirt.io/vm: vm-fedora-datavolume
       spec:
         domain:
           devices:
             disks:
             - disk:
                 bus: virtio
               name: datavolumedisk1
           machine:
             type: ""
           resources:
             requests:
               memory: 64M
         terminationGracePeriodSeconds: 0
         volumes:
         - dataVolume:
             name: fedora-dv
           name: datavolumedisk1
   status: {}

   1

   The HTTP source of the image you want to import.

   2

   The secretRef parameter is optional.

   3

   The certConfigMap is only required if the endpoint requires authentication. The referenced ConfigMap must be in the same namespace as the DataVolume.

4. Create the virtual machine:

   $ oc create -f vm-<name>-datavolume.yaml

   Note

   The oc create command creates the DataVolume and the virtual machine. The CDI controller creates an underlying PVC with the correct annotation, and the import process begins. When the import completes, the DataVolume status changes to Succeeded, and the virtual machine is allowed to start.

   DataVolume provisioning happens in the background, so there is no need to monitor it. You can start the virtual machine, and it will not run until the import is complete.

Optional verification steps

1. Run oc get pods and look for the importer Pod. This Pod downloads the image from the specified URL and stores it on the provisioned PV.

2. Monitor the DataVolume status until it shows Succeeded.

   $ oc describe dv <data-label> 1

   1

   The data label for the DataVolume specified in the virtual machine configuration file.

3. To verify that provisioning is complete and that the VMI has started, try accessing its serial console:

   $ virtctl console <vm-fedora-datavolume>

Procedure

1. Click Workloads → Virtual Machine from the side menu.
2. Select a virtual machine.
3. Click the YAML tab to display the editable configuration.
4. Optional: You can click Download to download the YAML file locally in its current state.
5. Edit the file and click Save.

Procedure

1. Run the following command to update the virtual machine configuration.

   $ oc edit <object_type> <object_ID>

2. Open the object configuration.
3. Edit the YAML.

4. If you edit a running virtual machine, you need to do one of the following:

   • Restart the virtual machine

   • Run the following command for the new configuration to take effect.

     $ oc apply <object_type> <object_ID>

Procedure

1. From the Virtual Machines tab, select your virtual machine.
2. Select the Disks tab.
3. Click Add Disks to open the Add Disk window.
4. In the Add Disk window, specify Source, Name, Size, Interface, and Storage Class.
5. Edit the disk configuration by using the drop-down lists and check boxes.
6. Click OK.

Procedure

1. From the Virtual Machines tab, select the virtual machine.
2. Select the Network Interfaces tab.
3. Click Create Network Interface.
4. In the Create Network Interface list row, specify the Name, Model, Network, Type, and MAC Address of the network interface.
5. Click the green check-mark to the right of the row to add the network interface.
6. Restart the virtual machine to enable access.
7. Edit the drop-down lists and check boxes to configure the network interface.
8. Click Save Changes.
9. Click OK.

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machines from the side menu.

2. Click the ⋮ button of the virtual machine to delete and select Delete Virtual Machine.

   • Alternatively, click the virtual machine name to open the Virtual Machine Details screen and click Actions → Delete Virtual Machine.
3. In the confirmation pop-up window, click Delete to permanently delete the virtual machine.

1. Run the following command to delete the virtual machine:

   $ oc delete vm <fedora-vm>

2. Run the following command to delete the DataVolume:

   $ oc delete dv <datavolume-name>

Procedure

1. Edit an Ansible Playbook YAML file so that it includes the kubevirt_vm task:

     kubevirt_vm:
       namespace:
       name:
       cpu_cores:
       memory:
       disks:
         - name:
           volume:
             containerDisk:
               image:
           disk:
             bus:

   Note

   This snippet only includes the kubevirt_vm portion of the playbook.

2. Edit the values to reflect the virtual machine you want to create, including the namespace, the number of cpu_cores, the memory, and the disks. For example:

     kubevirt_vm:
       namespace: default
       name: vm1
       cpu_cores: 1
       memory: 64Mi
       disks:
         - name: containerdisk
           volume:
             containerDisk:
               image: kubevirt/cirros-container-disk-demo:latest
           disk:
             bus: virtio

3. If you want the virtual machine to boot immediately after creation, add state: running to the YAML file. For example:

     kubevirt_vm:
       namespace: default
       name: vm1
       state: running 1
       cpu_cores: 1

   1

   Changing this value to state: absent deletes the virtual machine, if it already exists.

4. Run the ansible-playbook command, using your playbook’s file name as the only argument:

   $ ansible-playbook create-vm.yaml

5. Review the output to determine if the play was successful:

   (...)
   TASK [Create my first VM] ************************************************************************
   changed: [localhost]
   
   PLAY RECAP ********************************************************************************************************
   localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

6. If you did not include state: running in your playbook file and you want to boot the VM now, edit the file so that it includes state: running and run the playbook again:

   $ ansible-playbook create-vm.yaml

Procedure

1. Edit the interfaces spec of your virtual machine configuration file:

   kind: VirtualMachine
   spec:
     domain:
       devices:
         interfaces:
           - name: red
             masquerade: {} 1
             ports:
               - port: 80 2
     networks:
     - name: red
       pod: {}

   1

   Connect using masquerade mode

   2

   Allow incoming traffic on port 80

2. Create the virtual machine:

   $ oc create -f <vm-name>.yaml

Procedure

1. Create a new file for the NetworkAttachmentDefinition in any local directory. The file must have the following contents, modified to match your configuration:

   apiVersion: "k8s.cni.cncf.io/v1"
   kind: NetworkAttachmentDefinition
   metadata:
     name: a-bridge-network
     annotations:
       k8s.v1.cni.cncf.io/resourceName: bridge.network.kubevirt.io/br0 1
   spec:
     config: '{
       "cniVersion": "0.3.1",
       "plugins": [
         {
           "type": "cnv-bridge", 2
           "bridge": "br0", 3
           "ipam": {}
         },
         {
           "type": "tuning" 4
         }
       ]
     }'

   1

   If you add this annotation to your NetworkAttachmentDefinition, your virtual machine instances will only run on nodes that have the br0 bridge connected.

   2

   The actual name of the Container Network Interface (CNI) plug-in that provides the network for this NetworkAttachmentDefinition. Do not change this field unless you want to use a different CNI.

   3

   You must substitute the actual name of the bridge, if it is not br0.

   4

   Required. This allows the MAC pool manager to assign a unique MAC address to the connection.

   $ oc create -f <resource_spec.yaml>

2. Edit the configuration file of a virtual machine or virtual machine instance that you want to connect to the bridge network:

   apiVersion: v1
   kind: VirtualMachine
   metadata:
     name: example-vm
     annotations:
       k8s.v1.cni.cncf.io/networks: a-bridge-network 1
   spec:
   ...

   1

   You must substitute the actual name value from the NetworkAttachmentDefinition.

   In this example, the NetworkAttachmentDefinition and Pod are in the same namespace.

   To specify a different namespace, use the following syntax:

   ...
     annotations:
       k8s.v1.cni.cncf.io/networks: <namespace>/a-bridge-network
   ...

3. Apply the configuration file to the resource:

   $ oc create -f <local/path/to/network-attachment-definition.yaml>

Procedure

1. In the correct project in the container-native virtualization console, click Workloads → Virtual Machines.
2. Select a virtual machine template.
3. Click Network Interfaces to display the NICs already attached to the virtual machine.
4. Click Create NIC to create a new slot in the list.
5. Fill in the NAME, NETWORK, MAC ADDRESS, and BINDING METHOD for the new NIC.
6. Click the ✓ button to save and attach the NIC to the virtual machine.

Procedure

1. Access the virtual machine command line through one of the consoles or by SSH.

2. Install the QEMU guest agent on the virtual machine:

   $ yum install -y qemu-guest-agent

3. Start the QEMU guest agent service:

   $ systemctl start qemu-guest-agent

4. Ensure the service is persistent:

   $ systemctl enable qemu-guest-agent

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machines.
2. Click the virtual machine name to open the Virtual Machine Overview screen.

Procedure

1. Configure a PXE network on the cluster:

   1. Create the NetworkAttachmentDefinition file for PXE network pxe-net-conf:

      apiVersion: "k8s.cni.cncf.io/v1"
      kind: NetworkAttachmentDefinition
      metadata:
        name: pxe-net-conf
      spec:
        config: '{
            "cniVersion": "0.3.1",
            "name": "pxe-net-conf",
            "plugins": [
              {
                "type": "cnv-bridge",
                "bridge": "br1",
                "ipam": {}
              },
              {
                "type": "cnv-tuning" 1
              }
            ]
          }'

      1

      The cnv-tuning plug-in provides support for custom MAC addresses.

      Note

      The virtual machine instance will be attached to the bridge br1 through an access port with the requested VLAN.

2. Create the NetworkAttachmentDefinition object by using the file you created in the previous step:

   $ oc create -f pxe-net-conf.yaml

3. Edit the virtual machine instance configuration file to include the details of the interface and network.

   1. Specify the network and MAC address, if required by the PXE server. If the MAC address is not specified, a value is assigned automatically. However, note that at this time, MAC addresses assigned automatically are not persistent.

      Ensure that bootOrder is set to 1 so that the interface boots first. In this example, the interface is connected to a network called <pxe-net>:

      interfaces:
      - masquerade: {}
        name: default
      - bridge: {}
        name: pxe-net
        macAddress: de:00:00:00:00:de
        bootOrder: 1

      Note

      Boot order is global for interfaces and disks.

   2. Assign a boot device number to the disk to ensure proper booting after operating system provisioning.

      Set the disk bootOrder value to 2:

      devices:
        disks:
        - disk:
            bus: virtio
          name: containerdisk
          bootOrder: 2

   3. Specify that the network is connected to the previously created NetworkAttachmentDefinition. In this scenario, <pxe-net> is connected to the NetworkAttachmentDefinition called <pxe-net-conf>:

      networks:
      - name: default
        pod: {}
      - name: pxe-net
        multus:
          networkName: pxe-net-conf

4. Create the virtual machine instance:

   $ oc create -f vmi-pxe-boot.yaml
     virtualmachineinstance.kubevirt.io "vmi-pxe-boot" created

5. Wait for the virtual machine instance to run:

   $ oc get vmi vmi-pxe-boot -o yaml | grep -i phase
     phase: Running

6. View the virtual machine instance using VNC:

   $ virtctl vnc vmi-pxe-boot

7. Watch the boot screen to verify that the PXE boot is successful.

8. Log in to the virtual machine instance:

   $ virtctl console vmi-pxe-boot

9. Verify the interfaces and MAC address on the virtual machine and that the interface connected to the bridge has the specified MAC address. In this case, we used eth1 for the PXE boot, without an IP address. The other interface, eth0, got an IP address from OpenShift Container Platform.

   $ ip addr
   ...
   3. eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
      link/ether de:00:00:00:00:de brd ff:ff:ff:ff:ff:ff

Procedure

1. To explicitly tell the virtual machine instance that it has more memory available than was requested from the cluster, edit the virtual machine configuration file and set spec.domain.memory.guest to a higher value than spec.domain.resources.requests.memory. This process is called memory overcommitment.

   In this example, 1024M is requested from the cluster, but the virtual machine instance is told that it has 2048M available. As long as there is enough free memory available on the node, the virtual machine instance will consume up to 2048M.

   kind: VirtualMachine
   spec:
     template:
       domain:
       resources:
           requests:
             memory: 1024M
       memory:
           guest: 2048M

   Note

   The same eviction rules as those for Pods apply to the virtual machine instance if the node is under memory pressure.

2. Create the virtual machine:

   $ oc create -f <file name>.yaml

Procedure

1. To disable guest memory overhead accounting, edit the YAML configuration file and set the overcommitGuestOverhead value to true. This parameter is disabled by default.

   kind: VirtualMachine
   spec:
     template:
       domain:
       resources:
           overcommitGuestOverhead: true
           requests:
             memory: 1024M

   Note

   If overcommitGuestOverhead is enabled, it adds the guest overhead to memory limits, if present.

2. Create the virtual machine:

   $ oc create -f <file name>.yaml

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machine Templates.
2. Click Create Template and select Create with Wizard.
3. Fill in all required Basic Settings.

4. Click Next to progress to the Networking screen. A NIC that is named nic0 is attached by default.

   1. Optional: Click Create NIC to create additional NICs.
   2. Optional: You can remove any or all NICs by clicking the Options menu and selecting Remove NIC. Virtual machines created from a template do not need a NIC attached. NICs can be created after a virtual machine has been created.

5. Click Next to progress to the Storage screen.

   1. Optional: Click Create Disk to create additional disks.
   2. Optional: Click a disk to modify available fields. Click the ✓ button to save the changes.

   3. Optional: Click Attach Disk to choose an available disk from the Select Storage list.

      Note

      If either URL or Container are selected as the Provision Source in the Basic Settings screen, a rootdisk disk is created and attached to virtual machines as the Bootable Disk. You can modify the rootdisk but you cannot remove it.

      A Bootable Disk is not required for virtual machines provisioned from a PXE source if there are no disks attached to the virtual machine. If one or more disks are attached to the virtual machine, you must select one as the Bootable Disk.

6. Click Create Virtual Machine Template >. The Results screen displays the JSON configuration file for the virtual machine template.

   The template is listed in Workloads → Virtual Machine Templates.

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machine Templates.
2. Select a template.
3. Click the YAML tab to display the editable configuration.
4. Edit the file and click Save.

Procedure

1. From the Virtual Machine Templates tab, select your virtual machine template.
2. Select the Disks tab.
3. Click Add Disks to open the Add Disk window.
4. In the Add Disk window, specify Source, Name, Size, Interface, and Storage Class.
5. Edit the disk configuration by using the drop-down lists and check boxes.
6. Click OK.

Procedure

1. From the Virtual Machine Templates tab, select the virtual machine template.
2. Select the Network Interfaces tab.
3. Click Create Network Interface.
4. In the Create Network Interface list row, specify the Name, Model, Network, Type, and MAC Address of the network interface.
5. Click the green check-mark to the right of the row to add the network interface.
6. Restart the virtual machine to enable access.
7. Edit the drop-down lists and check boxes to configure the network interface.
8. Click Save Changes.
9. Click OK.

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machine Templates.

2. You can delete the virtual machine template from this pane, which makes it easier to perform actions on multiple templates in the one pane, or from the Virtual Machine Template Details pane where you can view comprehensive details of the selected template:

   • Click the Options menu of the template to delete and select Delete Template.
   • Click the template name to open the Virtual Machine Template Details pane and click Actions → Delete Template.
3. In the confirmation pop-up window, click Delete to permanently delete the template.

Procedure

1. Examine the virtual machine disk you want to clone to identify the name and namespace of the associated PVC.

2. Create a YAML file for a DataVolume object that specifies the name of the new DataVolume, the name and namespace of the source PVC, and the size of the new DataVolume.

   For example:

   apiVersion: cdi.kubevirt.io/v1alpha1
   kind: DataVolume
   metadata:
     name: <cloner-datavolume> 1
   spec:
     source:
       pvc:
         namespace: "<source-namespace>" 2
         name: "<my-favorite-vm-disk>" 3
     pvc:
       accessModes:
         - ReadWriteOnce
       resources:
         requests:
           storage: <2Gi> 4

   1

   The name of the new DataVolume.

   2

   The namespace where the source PVC exists.

   3

   The name of the source PVC.

   4

   The size of the new DataVolume. You must allocate enough space, or the cloning operation fails. The size must be the same as or larger than the source PVC.

3. Start cloning the PVC by creating the DataVolume:

   $ oc create -f <cloner-datavolume>.yaml

   Note

   DataVolumes prevent a virtual machine from starting before the PVC is prepared, so you can create a virtual machine that references the new DataVolume while the PVC clones.

Procedure

1. Examine the virtual machine you want to clone to identify the name and namespace of the associated PVC.

2. Create a YAML file for a VirtualMachine object. The following virtual machine example clones my-favorite-vm-disk, which is located in the source-namespace namespace. The 2Gi DataVolume called favorite-clone is created from my-favorite-vm-disk.

   For example:

   apiVersion: kubevirt.io/v1alpha3
   kind: VirtualMachine
   metadata:
     labels:
       kubevirt.io/vm: vm-dv-clone
     name: vm-dv-clone 1
   spec:
     running: false
     template:
       metadata:
         labels:
           kubevirt.io/vm: vm-dv-clone
       spec:
         domain:
           devices:
             disks:
             - disk:
                 bus: virtio
               name: root-disk
           resources:
             requests:
               memory: 64M
         volumes:
         - dataVolume:
             name: favorite-clone
           name: root-disk
     dataVolumeTemplates:
     - metadata:
         name: favorite-clone
       spec:
         pvc:
           accessModes:
           - ReadWriteOnce
           resources:
             requests:
               storage: 2Gi
         source:
           pvc:
             namespace: "source-namespace"
             name: "my-favorite-vm-disk"

   1

   The virtual machine to create.

3. Create the virtual machine with the PVC-cloned DataVolume:

   $ oc create -f <vm-clone-datavolumetemplate>.yaml

Procedure

1. Identify the following items:

   • File location of the VM disk image you want to upload
   • Name and size required for the resulting PVC

2. Run the virtctl image-upload command to upload your VM image. You must specify the PVC name, PVC size, and file location. For example:

   $ virtctl image-upload --pvc-name=<upload-fedora-pvc> --pvc-size=<2Gi> --image-path=</images/fedora.qcow2>

   Caution

   To allow insecure server connections when using HTTPS, use the --insecure parameter. Be aware that when you use the --insecure flag, the authenticity of the upload endpoint is not verified.

3. To verify that the PVC was created, view all PVC objects:

   $ oc get pvc

Procedure

1. Log in as root to the node on which to create the local PV. This procedure uses node01 for its examples.

2. Create a file and populate it with null characters so that it can be used as a block device. The following example creates a file loop10 with a size of 2Gb (20 100Mb blocks):

   $ dd if=/dev/zero of=<loop10> bs=100M count=20

3. Mount the loop10 file as a loop device.

   $ losetup </dev/loop10>d3 <loop10> 1 2

   1

   File path where the loop device is mounted.

   2

   The file created in the previous step to be mounted as the loop device.

4. Create a PersistentVolume configuration that references the mounted loop device.

   kind: PersistentVolume
   apiVersion: v1
   metadata:
     name: <local-block-pv10>
     annotations:
   spec:
     local:
       path: </dev/loop10> 1
     capacity:
       storage: <2Gi>
     volumeMode: Block 2
     storageClassName: local 3
     accessModes:
       - ReadWriteOnce
     persistentVolumeReclaimPolicy: Delete
     nodeAffinity:
       required:
         nodeSelectorTerms:
         - matchExpressions:
           - key: kubernetes.io/hostname
             operator: In
             values:
             - <node01> 4

   1

   The path of the loop device on the node.

   2

   Specifies it is a block PV.

   3

   Optional: Set a StorageClass for the PV. If you omit it, the cluster default is used.

   4

   The node on which the block device was mounted.

5. Create the block PV.

   # oc create -f <local-block-pv10.yaml>1

   1

   The filename of the PersistentVolume created in the previous step.

Procedure

1. Create a DataVolume configuration that specifies spec: source: upload{}:

   apiVersion: cdi.kubevirt.io/v1alpha1
   kind: DataVolume
   metadata:
     name: <upload-datavolume> 1
   spec:
     source:
         upload: {}
     pvc:
       accessModes:
         - ReadWriteOnce
       resources:
         requests:
           storage: <2Gi> 2

   1

   The name of the DataVolume

   2

   The size of the DataVolume

2. Create the DataVolume:

   $ oc create -f <upload-datavolume>.yaml

Procedure

1. Identify the following items:

   • File location of the VM disk image that you want to upload
   • Name of the DataVolume

2. Run the virtctl image-upload command to upload your disk image. You must specify the DV name and file location. For example:

   $ virtctl image-upload --dv-name=<upload-datavolume> --image-path=</images/fedora.qcow2> 1 2

   1

   The name of the DataVolume that you are creating.

   2

   The filepath of the virtual machine disk image you are uploading.

   Caution

   To allow insecure server connections when using HTTPS, use the --insecure parameter. Be aware that when you use the --insecure flag, the authenticity of the upload endpoint is not verified.

3. To verify that the DV was created, view all DV objects:

   $ oc get dvs

Procedure

1. Edit the DataVolume configuration file:

   apiVersion: cdi.kubevirt.io/v1alpha1
   kind: DataVolume
   metadata:
     name: blank-image-datavolume
   spec:
     source:
         blank: {}
     pvc:
       # Optional: Set the storage class or omit to accept the default
       # storageClassName: "hostpath"
       accessModes:
         - ReadWriteOnce
       resources:
         requests:
           storage: 500Mi

2. Create the blank disk image by running the following command:

   $ oc create -f <blank-image-datavolume>.yaml

Procedure

1. Log in as root to the node on which to create the local PV. This procedure uses node01 for its examples.

2. Create a file and populate it with null characters so that it can be used as a block device. The following example creates a file loop10 with a size of 2Gb (20 100Mb blocks):

   $ dd if=/dev/zero of=<loop10> bs=100M count=20

3. Mount the loop10 file as a loop device.

   $ losetup </dev/loop10>d3 <loop10> 1 2

   1

   File path where the loop device is mounted.

   2

   The file created in the previous step to be mounted as the loop device.

4. Create a PersistentVolume configuration that references the mounted loop device.

   kind: PersistentVolume
   apiVersion: v1
   metadata:
     name: <local-block-pv10>
     annotations:
   spec:
     local:
       path: </dev/loop10> 1
     capacity:
       storage: <2Gi>
     volumeMode: Block 2
     storageClassName: local 3
     accessModes:
       - ReadWriteOnce
     persistentVolumeReclaimPolicy: Delete
     nodeAffinity:
       required:
         nodeSelectorTerms:
         - matchExpressions:
           - key: kubernetes.io/hostname
             operator: In
             values:
             - <node01> 4

   1

   The path of the loop device on the node.

   2

   Specifies it is a block PV.

   3

   Optional: Set a StorageClass for the PV. If you omit it, the cluster default is used.

   4

   The node on which the block device was mounted.

5. Create the block PV.

   # oc create -f <local-block-pv10.yaml>1

   1

   The filename of the PersistentVolume created in the previous step.

Procedure

1. If your data source requires authentication credentials, edit the endpoint-secret.yaml file, and apply the updated configuration to the cluster.

   1. Edit the endpoint-secret.yaml file with your preferred text editor:

      apiVersion: v1
      kind: Secret
      metadata:
        name: <endpoint-secret>
        labels:
          app: containerized-data-importer
      type: Opaque
      data:
        accessKeyId: "" 1
        secretKey:   "" 2

      1

      Optional: your key or user name, base64 encoded

      2

      Optional: your secret or password, base64 encoded

   2. Update the secret:

      $ oc apply -f endpoint-secret.yaml

2. Create a DataVolume configuration that specifies the data source for the image you want to import and volumeMode: Block so that an available block PV is used.

   apiVersion: cdi.kubevirt.io/v1alpha1
   kind: DataVolume
   metadata:
     name: <import-pv-datavolume> 1
   spec:
     storageClassName: local 2
     source:
         http:
            url: <http://download.fedoraproject.org/pub/fedora/linux/releases/28/Cloud/x86_64/images/Fedora-Cloud-Base-28-1.1.x86_64.qcow2> 3
            secretRef: <endpoint-secret> 4
     pvc:
       volumeMode: Block 5
       accessModes:
         - ReadWriteOnce
       resources:
         requests:
           storage: <2Gi>

   1

   The name of the DataVolume.

   2

   Optional: Set the storage class or omit it to accept the cluster default.

   3

   The HTTP source of the image to import.

   4

   Only required if the data source requires authentication.

   5

   Required for importing to a block PV.

3. Create the DataVolume to import the virtual machine image.

   $ oc create -f <import-pv-datavolume.yaml>1

   1

   The filename DataVolume created in the previous step.

Procedure

1. Log in as root to the node on which to create the local PV. This procedure uses node01 for its examples.

2. Create a file and populate it with null characters so that it can be used as a block device. The following example creates a file loop10 with a size of 2Gb (20 100Mb blocks):

   $ dd if=/dev/zero of=<loop10> bs=100M count=20

3. Mount the loop10 file as a loop device.

   $ losetup </dev/loop10>d3 <loop10> 1 2

   1

   File path where the loop device is mounted.

   2

   The file created in the previous step to be mounted as the loop device.

4. Create a PersistentVolume configuration that references the mounted loop device.

   kind: PersistentVolume
   apiVersion: v1
   metadata:
     name: <local-block-pv10>
     annotations:
   spec:
     local:
       path: </dev/loop10> 1
     capacity:
       storage: <2Gi>
     volumeMode: Block 2
     storageClassName: local 3
     accessModes:
       - ReadWriteOnce
     persistentVolumeReclaimPolicy: Delete
     nodeAffinity:
       required:
         nodeSelectorTerms:
         - matchExpressions:
           - key: kubernetes.io/hostname
             operator: In
             values:
             - <node01> 4

   1

   The path of the loop device on the node.

   2

   Specifies it is a block PV.

   3

   Optional: Set a StorageClass for the PV. If you omit it, the cluster default is used.

   4

   The node on which the block device was mounted.

5. Create the block PV.

   # oc create -f <local-block-pv10.yaml>1

   1

   The filename of the PersistentVolume created in the previous step.

Procedure

1. Examine the virtual machine disk you want to clone to identify the name and namespace of the associated PVC.

2. Create a YAML file for a DataVolume object that specifies the name of the new DataVolume, the name and namespace of the source PVC, volumeMode: Block so that an available block PV is used, and the size of the new DataVolume.

   For example:

   apiVersion: cdi.kubevirt.io/v1alpha1
   kind: DataVolume
   metadata:
     name: <cloner-datavolume> 1
   spec:
     source:
       pvc:
         namespace: "<source-namespace>" 2
         name: "<my-favorite-vm-disk>" 3
     pvc:
       accessModes:
         - ReadWriteOnce
       resources:
         requests:
           storage: <2Gi> 4
       volumeMode: Block 5

   1

   The name of the new DataVolume.

   2

   The namespace where the source PVC exists.

   3

   The name of the source PVC.

   4

   The size of the new DataVolume. You must allocate enough space, or the cloning operation fails. The size must be the same as or larger than the source PVC.

   5

   Specifies that the destination is a block PV

3. Start cloning the PVC by creating the DataVolume:

   $ oc create -f <cloner-datavolume>.yaml

   Note

   DataVolumes prevent a virtual machine from starting before the PVC is prepared, so you can create a virtual machine that references the new DataVolume while the PVC clones.

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machines.

2. You can initiate the migration from this screen, which makes it easier to perform actions on multiple virtual machines in the one screen, or from the Virtual Machine Details screen where you can view comprehensive details of the selected virtual machine:

   • Click the Options menu at the end of virtual machine and select Migrate Virtual Machine.
   • Click the virtual machine name to open the Virtual Machine Details screen and click Actions → Migrate Virtual Machine.
3. Click Migrate to migrate the virtual machine to another node.

Procedure

1. Create a VirtualMachineInstanceMigration configuration file for the virtual machine instance to migrate. For example, vmi-migrate.yaml:

   apiVersion: kubevirt.io/v1alpha3
   kind: VirtualMachineInstanceMigration
   metadata:
     name: migration-job
   spec:
     vmiName: vmi-fedora

2. Create the object in the cluster:

   $ oc create -f vmi-migrate.yaml

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machines.

2. You can cancel the migration from this screen, which makes it easier to perform actions on multiple virtual machines in the one screen, or from the Virtual Machine Details screen where you can view comprehensive details of the selected virtual machine:

   • Click the Options menu at the end of virtual machine and select Cancel Virtual Machine Migration.
   • Click the virtual machine name to open the Virtual Machine Details screen and click Actions → Cancel Virtual Machine Migration.
3. Click Cancel Migration to cancel the virtual machine live migration.

Procedure

1. Add the evictionStrategy: LiveMigrate option to the spec section in the virtual machine configuration file. This example uses oc edit to update the relevant snippet of the VirtualMachine configuration file:

   $ oc edit vm <custom-vm> -n <my-namespace>

   apiVersion: kubevirt.io/v1alpha3
   kind: VirtualMachine
   metadata:
     name: custom-vm
   spec:
     terminationGracePeriodSeconds: 30
     evictionStrategy: LiveMigrate
     domain:
       resources:
         requests:
   ...

2. Restart the virtual machine for the update to take effect:

   $ virtctl restart <custom-vm> -n <my-namespace>

Procedure

1. In the container-native virtualization console, click Compute → Nodes.

2. You can set the node to maintenance from this screen, which makes it easier to perform actions on multiple nodes in the one screen or from the Node Details screen where you can view comprehensive details of the selected node:

   • Click the Options menu at the end of the node and select Start Maintenance.
   • Click the node name to open the Node Details screen and click Actions → Start Maintenance.
3. Click Start Maintenance in the confirmation window.

Procedure

1. Create the node maintenance CR configuration. This example uses a CR that is called node02-maintenance.yaml:

   apiVersion: kubevirt.io/v1alpha1
   kind: NodeMaintenance
   metadata:
     name: node02-maintenance
   spec:
     nodeName: node02
     reason: "Replacing node02"

2. Create the NodeMaintenance object in the cluster:

   $ oc apply -f <node02-maintenance.yaml>

Procedure

1. In the container-native virtualization console, click Compute → Nodes.

2. You can resume the node from this screen, which makes it easier to perform actions on multiple nodes in the one screen, or from the Node Details screen where you can view comprehensive details of the selected node:

   • Click the Options menu at the end of the node and select Stop Maintenance.
   • Click the node name to open the Node Details screen and click Actions → Stop Maintenance.
3. Click Stop Maintenance in the confirmation window.

Procedure

1. Find the NodeMaintenance object:

   $ oc get nodemaintenance

2. Optional: Insepct the NodeMaintenance object to ensure it is associated with the correct node:

   $ oc describe nodemaintenance <node02-maintenance>

   Name:         node02-maintenance
   Namespace:
   Labels:
   Annotations:
   API Version:  kubevirt.io/v1alpha1
   Kind:         NodeMaintenance
   ...
   Spec:
     Node Name:  node02
     Reason:     Replacing node02

3. Delete the NodeMaintenance object:

   $ oc delete nodemaintenance <node02-maintenance>

Procedure

1. Download the rotate-certs.sh script from GitHub:

   $ curl -O https://raw.githubusercontent.com/kubevirt/hyperconverged-cluster-operator/master/tools/rotate-certs.sh

2. Ensure the script is executable:

   $ chmod +x rotate-certs.sh

3. Run the script:

   $ ./rotate-certs.sh -n openshift-cnv

Procedure

1. Add the container-native-virtualization/virtio-win container disk as a cdrom disk in the Windows virtual machine configuration file. The container disk will be downloaded from the registry if it is not already present in the cluster.

   spec:
     domain:
       devices:
         disks:
           - name: virtiocontainerdisk
             bootOrder: 2 1
             cdrom:
               bus: sata
   volumes:
     - containerDisk:
         image: container-native-virtualization/virtio-win
       name: virtiocontainerdisk

   1

   Container-native virtualization boots virtual machine disks in the order defined in the VirtualMachine configuration file. You can either define other disks for the virtual machine before the container-native-virtualization/virtio-win container disk or use the optional bootOrder parameter to ensure the virtual machine boots from the correct disk. If you specify the bootOrder for a disk, it must be specified for all disks in the configuration.

2. The disk is available once the virtual machine has started:

   • If you add the container disk to a running virtual machine, use oc apply -f <vm.yaml> in the CLI or reboot the virtual machine for the changes to take effect.
   • If the virtual machine is not running, use virtctl start <vm>.

Procedure

1. Start the virtual machine and connect to a graphical console.
2. Log in to a Windows user session.

3. Open Device Manager and expand Other devices to list any Unknown device.

   1. Open the Device Properties to identify the unknown device. Right-click the device and select Properties.
   2. Click the Details tab and select Hardware Ids in the Property list.
   3. Compare the Value for the Hardware Ids with the supported VirtIO drivers.
4. Right-click the device and select Update Driver Software.
5. Click Browse my computer for driver software and browse to the attached SATA CD drive, where the VirtIO drivers are located. The drivers are arranged hierarchically according to their driver type, operating system, and CPU architecture.
6. Click Next to install the driver.
7. Repeat this process for all the necessary VirtIO drivers.
8. After the driver installs, click Close to close the window.
9. Reboot the virtual machine to complete the driver installation.

Procedure

1. Edit the configuration file and remove the disk and the volume.

   $ oc edit vm <vm-name>

   spec:
     domain:
       devices:
         disks:
           - name: virtiocontainerdisk
             bootOrder: 2
             cdrom:
               bus: sata
   volumes:
     - containerDisk:
         image: container-native-virtualization/virtio-win
       name: virtiocontainerdisk

2. Reboot the virtual machine for the changes to take effect.

Procedure

1. Add the container-native-virtualization/virtio-win container disk as a cdrom disk in the Windows virtual machine configuration file. The container disk will be downloaded from the registry if it is not already present in the cluster.

   spec:
     domain:
       devices:
         disks:
           - name: virtiocontainerdisk
             bootOrder: 2 1
             cdrom:
               bus: sata
   volumes:
     - containerDisk:
         image: container-native-virtualization/virtio-win
       name: virtiocontainerdisk

   1

   Container-native virtualization boots virtual machine disks in the order defined in the VirtualMachine configuration file. You can either define other disks for the virtual machine before the container-native-virtualization/virtio-win container disk or use the optional bootOrder parameter to ensure the virtual machine boots from the correct disk. If you specify the bootOrder for a disk, it must be specified for all disks in the configuration.

2. The disk is available once the virtual machine has started:

   • If you add the container disk to a running virtual machine, use oc apply -f <vm.yaml> in the CLI or reboot the virtual machine for the changes to take effect.
   • If the virtual machine is not running, use virtctl start <vm>.

Procedure

1. Start the virtual machine and connect to a graphical console.
2. Begin the Windows installation process.
3. Select the Advanced installation.
4. The storage destination will not be recognized until the driver is loaded. Click Load driver.
5. The drivers are attached as a SATA CD drive. Click OK and browse the CD drive for the storage driver to load. The drivers are arranged hierarchically according to their driver type, operating system, and CPU architecture.
6. Repeat the previous two steps for all required drivers.
7. Complete the Windows installation.

Procedure

1. Edit the configuration file and remove the disk and the volume.

   $ oc edit vm <vm-name>

   spec:
     domain:
       devices:
         disks:
           - name: virtiocontainerdisk
             bootOrder: 2
             cdrom:
               bus: sata
   volumes:
     - containerDisk:
         image: container-native-virtualization/virtio-win
       name: virtiocontainerdisk

2. Reboot the virtual machine for the changes to take effect.

Procedure

1. In the container-native virtualization console, click Workloads → Virtual Machines.
2. Click the virtual machine to open the Virtual Machine Details panel.
3. In the Overview tab, click the virt-launcher-<name> Pod in the POD section.
4. Click Logs.

Procedure

1. Navigate to the directory where you want to store the must-gather data.

2. Run the oc adm must-gather command with one or more --image or --image-stream arguments. For example, the following command gathers both the default cluster data and information specific to container-native virtualization:

   $ oc adm must-gather \
    --image-stream=openshift/must-gather \ 1
    --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8 2

   1

   Default OpenShift Container Platform must-gather image

   2

   Container-native virtualization must-gather image

3. Create a compressed file from the must-gather directory that was just created in your working directory. For example, on a computer that uses a Linux operating system, run the following command:

   $ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ 1

   1

   Make sure to replace must-gather-local.5421342344627712289/ with the actual directory name.

4. Attach the compressed file to your support case on the Red Hat Customer Portal.