Chapter 1. Using Container-native Virtualization

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.

Procedure

1. Click Workloads Virtual Machines from the side menu.
2. Select a Virtual Machine.
3. Click Edit to make editable fields available.
4. You can change the Flavor but only to Custom, which provides additional fields for CPU and Memory.
5. Click Save.

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.

   1. (Optional) You can click Download to download the YAML file locally in its current state.
4. Edit the file and click Save.

Procedure

1. Click Workloads Virtual Machines from the side menu.
2. Select a Virtual Machine.
3. Click Events to view all events for the virtual machine.

Procedure

1. Click Workloads Virtual Machines from the side menu.

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

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

Procedure

1. Click Workloads Virtual Machine from the side menu.

2. Click the ⋮ button of the virtual machine and select Start Virtual Machine.

   1. Alternatively, click the virtual machine name to open the Virtual Machine Details screen and click Actions and select Start Virtual Machine.
3. In the confirmation pop-up window, click Start to start the virtual machine.

Procedure

1. Click Workloads Virtual Machine from the side menu.

2. Click the ⋮ button of the virtual machine and select Stop Virtual Machine.

   1. Alternatively, click the virtual machine name to open the Virtual Machine Details screen and click Actions and select Stop Virtual Machine.
3. In the confirmation pop-up window, click Stop to stop the virtual machine.

Procedure

1. Click Workloads Virtual Machine from the side menu.

2. Click the ⋮ button of the virtual machine and select Restart Virtual Machine.

   1. Alternatively, click the virtual machine name to open the Virtual Machine Details screen and click Actions and select Restart Virtual Machine.
3. In the confirmation pop-up window, click Restart to restart the virtual machine.

Procedure

1. Click Workloads Virtual Machines from the side menu.
2. Select a virtual machine.
3. Click Consoles. The VNC console opens by default.

Procedure

1. Click Workloads Virtual Machines from the side menu.
2. Select a virtual machine.
3. Click Consoles. The VNC console opens by default.
4. Click the VNC Console drop-down list and select Serial Console.

Procedure

1. Click Workloads Virtual Machines from the side menu.
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, and MAC ADDRESS details for the new NIC.
6. Click the ✓ button to save and attach the NIC to the virtual machine.

Procedure

1. Click Workloads Virtual Machines from the side menu.
2. Select a virtual machine.
3. Click Network Interfaces to display the NICs already attached to the virtual machine.
4. Click the ⋮ button of the NIC you wish to delete and select Delete.
5. In the confirmation pop-up window, click Delete to detach and delete the NIC.

Procedure

1. Click Workloads Virtual Machines from the side menu.
2. Select a virtual machine.
3. Click Disks to display the disks already attached to the virtual machine.
4. Click Create Disk to create a new slot in the list.
5. Fill in the NAME, SIZE, and optional STORAGE CLASS details for the new disk.
6. Click the ✓ button to save and attach the disk to the virtual machine.

Procedure

1. Click Workloads Virtual Machines from the side menu.
2. Select a virtual machine.
3. Click Disks to display the disks already attached to the virtual machine.
4. Click the ⋮ button of the disk you wish to delete and select Delete.
5. Click Confirm to detach and delete the disk.

Procedure

1. Click Workloads Virtual Machine Templates from the side menu.
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. An 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. 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. 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 Template >. The Results screen displays the JSON configuration file for the virtual machine template.

Procedure

1. Click Workloads Virtual Machine Template from the side menu.
2. Select a template.

3. Click the YAML tab to display the editable configuration.

   1. (Optional) You can click Download to download the YAML file locally in its current state.
4. Edit the file and click Save.

Procedure

1. Click Workloads Virtual Machine Templates from the side menu.

2. Click the ⋮ button of the template to delete and select Delete Template.

   1. Alternatively, click the template name to open the Virtual Machine Template Details screen and click Actions Delete Template.
3. In the confirmation pop-up window, click Delete to permanently delete the template.

Procedure

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

   $ yum install -y qemu-guest-agent

2. Start the QEMU guest agent service:

   $ systemctl start qemu-guest-agent

3. View the IP address information for a VMI:

   $ oc describe vmi <vmi_name>
   
   ...
   Interfaces:
      Interface Name:  eth0
      Ip Address:      10.244.0.37/24
      Ip Addresses:
        10.244.0.37/24
        fe80::858:aff:fef4:25/64
      Mac:             0a:58:0a:f4:00:25
      Name:            default
      Interface Name:  v2
      Ip Address:      1.1.1.7/24
      Ip Addresses:
        1.1.1.7/24
        fe80::f4d9:70ff:fe13:9089/64
      Mac:             f6:d9:70:13:90:89
      Interface Name:  v1
      Ip Address:      1.1.1.1/24
      Ip Addresses:
        1.1.1.1/24
        1.1.1.2/24
        1.1.1.4/24
        2001:de7:0:f101::1/64
        2001:db8:0:f101::1/64
        fe80::1420:84ff:fe10:17aa/64
      Mac:             16:20:84:10:17:aa

   Note

   You can also view the IP address information by running ip addr on the virtual machine, or by running oc get vmi -o yaml.

Procedure

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

   kind: VM
   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

Procedure

1. Identify the following items:

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

2. Remove the existing passthrough route:

   $ oc delete route -n cdi cdi-uploadproxy-route

3. Create a secured route using re-encryption termination:

   $ oc get secret -n cdi cdi-upload-proxy-ca-key -o=jsonpath="{.data['tls\.crt']}" | base64 -d > ca.pem
   
   $ oc create route reencrypt cdi-uploadproxy-route -n cdi --service=cdi-uploadproxy --dest-ca-cert=ca.pem

4. Use the virtctl image-upload command to upload your VM image, making sure to include your chosen parameters. For example:

   $ virtctl image-upload --uploadproxy-url=https://$(oc get route cdi-uploadproxy-route -n cdi -o=jsonpath='{.status.ingress[0].host}') --pvc-name=upload-fedora-pvc --pvc-size=10Gi --image-path=/images/fedora28.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.

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

   $ oc get pvc

Procedure

1. Identify an HTTP or S3 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
   • s3://bucketName/fileName

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

   apiVersion: v1
   kind: Secret
   metadata:
     name: <endpoint-secret>
     labels:
       app: containerized-data-importer
   type: Opaque
   data:
     accessKeyId: ""  # <optional: your key or user name, base64 encoded>
     secretKey:    "" # <optional: your secret or password, base64 encoded>

   $ oc apply -f endpoint-secret.yaml

3. Edit the VM configuration file, optionally including the secretRef parameter. In our example, we used a Fedora image:

   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
             secretRef: "" # Optional
       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: {}

4. Create the virtual machine:

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

   The virtual machine and a DataVolume will now be created. The CDI controller creates an underlying PVC with the correct annotation and begins the import process. When the import completes, the DataVolume status changes to Succeeded and the virtual machine will be allowed to start.

   DataVolume provisioning happens in the background, so there is no need to monitor it. You can start the VM 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 VirtualMachine 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. Identify an HTTP or S3 file server hosting the virtual disk image that you want to import. You need the complete URL, in either format:

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

   • s3://bucketName/fileName

     Use this URL as the cdi.kubevirt.io/storage.import.endpoint annotation value in your PVC configuration file.

     For example: cdi.kubevirt.io/storage.import.endpoint: https://download.fedoraproject.org/pub/fedora/linux/releases/28/Cloud/x86_64/images/Fedora-Cloud-Base-28-1.1.x86_64.qcow2

2. If the file server requires authentication credentials, edit the endpoint-secret.yaml file:

   apiVersion: v1
   kind: Secret
   metadata:
     name: endpoint-secret
     labels:
       app: containerized-data-importer
   type: Opaque
   data:
     accessKeyId: ""  # <optional: your key or user name, base64 encoded>
     secretKey:    "" # <optional: your secret or password, base64 encoded>

   1. Save the value of metadata.name to use with the cdi.kubevirt.io/storage.import.secret annotation in your PVC configuration file.

      For example: cdi.kubevirt.io/storage.import.secret: endpoint-secret

3. Apply endpoint-secret.yaml to the cluster:

   $ oc apply -f endpoint-secret.yaml

4. Edit the PVC configuration file, making sure to include the required annotations.

   For example:

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: "example-vmdisk-volume"
     labels:
      app: containerized-data-importer
     annotations:
       cdi.kubevirt.io/storage.import.endpoint: "https://download.fedoraproject.org/pub/fedora/linux/releases/28/Cloud/x86_64/images/Fedora-Cloud-Base-28-1.1.x86_64.qcow2" 1
       cdi.kubevirt.io/storage.import.secret: "endpoint-secret" 2
   spec:
     accessModes:
     - ReadWriteOnce
     resources:
       requests:
         storage: 5Gi

   1

   Endpoint annotation for the import image URL

   2

   Endpoint annotation for the authorization secret

5. Create the PVC using the oc CLI:

   $ oc create -f <pvc.yaml> 1

   1

   The PersistentVolumeClaim file name.

   After the disk image is successfully imported into the PV, the import pod expires, and you can bind the PVC to a virtual machine object within OpenShift Container Platform.

Procedure

1. Examine the DataVolume 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, <vm-dv-clone>, clones <my-favorite-vm-disk> (located in the <source-namespace> namespace) and creates the 2Gi <favorite-clone> DataVolume, referenced in the virtual machine as the <favorite-clone> volume.

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

Procedure

1. Examine the DataVolume 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 following parameters:

   metadata: name	The name of the new DataVolume.
   source: pvc: namespace	The namespace in which the source PVC exists.
   source: pvc: name	The name of the source PVC.
   storage	The size of the new DataVolume. Be sure to allocate enough space or the cloning operation fails. The size must be the same or larger as the source PVC. For example: apiVersion: cdi.kubevirt.io/v1alpha1 kind: DataVolume metadata: name: cloner-datavolume spec: source: pvc: namespace: "<source-namespace>" name: "<my-favorite-vm-disk>" pvc: accessModes: - ReadWriteOnce resources: requests: storage: 2Gi

3. Start the PVC clone by creating the DataVolume:

   $ oc create -f <datavolume>.yaml

Procedure

1. Create the DataVolume manifest 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. Deploy the DataVolume manifest to create the blank disk image:

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

Procedure

1. Create the PVC manifest file:

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: "blank-image-pvc"
     labels:
       app: containerized-data-importer
     annotations:
       cdi.kubevirt.io/storage.import.source: "none"
   spec:
     accessModes:
     - ReadWriteOnce
     resources:
       requests:
         storage: 4Gi
     # Optional: Set the storage class or omit to accept the default
     # storageClassName: local

2. Deploy the PVC manifest to create the blank disk image:

   $ oc create -f blank-image-pvc.yaml

Procedure

1. Connect to the serial console with virtctl:

   $ virtctl console <VMI>

Procedure

1. Connect to the graphical interface with the virtctl utility:

   $ virtctl vnc <VMI>

2. If the command failed, try using the -v flag to collect troubleshooting information:

   $ virtctl vnc <VMI> -v 4

Procedure

1. Run the following command to create the fedora-vm-ssh service:

   $ virtctl expose vm <fedora-vm> --port=20022 --target-port=22 --name=fedora-vm-ssh --type=NodePort

2. Check the service to find out which port the service acquired:

   $ oc get svc
   NAME            TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)           AGE
   fedora-vm-ssh   NodePort   127.0.0.1      <none>        20022:32551/TCP   6s

3. Log in to the virtual machine instance via SSH, using the ipAddress of the node and the port that you found in Step 2:

   $ ssh username@<node IP> -p 32551