Introduction

This tutorial outlines the steps to create virtual machines using the packaged utilities provided by the Oracle Linux Kernel-based Virtual Machine (KVM) image for Oracle Cloud Infrastructure. KVM provides a set of modules that enable you to use the Oracle Linux kernel as a hypervisor and is built into the Oracle Linux Unbreakable Enterprise Kernel (UEK) by default.

Oracle Linux KVM image is available for deployment from the Marketplace and the Oracle Images catalog in the Oracle Cloud Infrastructure Console. This Oracle packaged image simplifies the deployment of virtual machines by integrating with services such as block storage and virtual network interfaces through the use of scripted utilities, including OCI Utilities. These utilities include support for defining the virtual machine guest domain, allocating a specific block device or VNIC and launching and removing virtual machines on Oracle Cloud Infrastructure.

This tutorial guides you through the following tasks on the Console:

  • Creating and accessing an Oracle Linux KVM instance
  • Allocating block storage and a VNIC to an Oracle KVM instance
  • Creating a virtual machine on an Oracle Linux KVM instance
  • Removing a virtual machine from an Oracle Linux KVM instance

Included in this tutorial is a Using OCI-KVM Utility reference section that provides detail on the utility's commands and options.

Before You Begin

If you are new to Oracle Cloud Infrastructure, review the Getting Started section in the Oracle Cloud Infrastructure documentation. It is also helpful to have familiarity with managing virtual machine guests using libvirt, in particular virsh and virt-install.

For more information on using KVM with Oracle Linux, see:

What’s New in Release 2.0

Release 2.0 introduces the following updates:

  • The base operating system is updated to Oracle Linux 7 Update 9 and Unbreakable Enterprise Kernel Release 6 (UEKR6).
  • The oci-utils package is updated to v0.11.6-9.
  • The Oracle Cloud Marketplace now offers two versions of the Oracle Linux KVM image:

    • Oracle Linux KVM image (Autonomous Linux): This image is configured to run Oracle Autonomous Linux using the standard Oracle Linux repositories. Oracle Autonomous Linux provides autonomous capabilities such as automated Ksplice patching with zero downtime, and known exploit detection, to help keep the instance highly secure and reliable. The Autonomous Linux version of the image is listed in the Oracle Cloud Marketplace as Oracle Linux KVM image (Autonomous Linux).

      For more information about Oracle Autonomous Linux, see Getting Started: Deploying and Configuring Oracle Autonomous Linux on Oracle Cloud Infrastructure and Oracle Autonomous Linux for Oracle Cloud Infrastructure (Oracle Linux Learning Library).

    • Oracle Linux KVM image: The Oracle Linux version of the image is listed in the Oracle Cloud Marketplace as Oracle Linux KVM image.
      Important

      Future releases of the Oracle Linux KVM image for Oracle Cloud Infrastructure will be configured as Autonomous Linux using the standard Oracle Linux repositories.

For information about older releases, see About Previous Releases.

Deploying an Oracle Linux KVM Instance

In Oracle Cloud Infrastructure, you can use the Oracle Linux KVM image to launch a KVM instance. You can access the Oracle Linux KVM image from the Oracle Cloud Infrastructure Console by using the embedded Marketplace or the Oracle Images tab.

You can also access the Oracle Linux KVM image through the Oracle Cloud Marketplace, which is outside of Oracle Cloud Infrastructure. For more information, see Overview of Marketplace.

Creating a KVM Instance

To deploy an Oracle Linux KVM instance from the Console, complete the steps in either of the following sections:

  • Creating a KVM Instance from the Embedded Marketplace
  • Creating a KVM Instance from Oracle Images

You can create Oracle KVM instances on Oracle Cloud Infrastructure using any of the compute shapes; however, AMD processor-based virtual machines do not support nested virtualization. For more information, see Compute Shapes.

Be aware that on shapes with an active physical NIC 1, attaching a KVM guest to VLAN 0 is currently not supported; however, it is fully supported to attach KVM guests to the other VLANs on either physical NIC.

Creating a KVM Instance from the Embedded Marketplace

  1. Log in to the Console.
  2. Open the navigation menu. Under Solutions and Platform, go to Marketplace and select Applications.
  3. Type Oracle Linux KVM Image in the search box and press Enter.

    This image shows the Marketplace, all available applications, and how to search for Oracle Linux KVM image in All Applications.
    Click to view larger image kvm-image-marketplace.png

  4. Click the Oracle Linux KVM Image box.

    This image gives you an overview of the Oracle Linux KVM image.
    Click to view larger image kvm-image-launch.png

  5. To launch the instance:
    1. Select the Version of the image and the Compartment in which you want to deploy the image.
    2. Accept the Oracle Standard Terms and Restrictions.
    3. Click Launch Instance.

    The Create Compute Instance page automatically pre-populates with the KVM image source and instance configuration details.

    This image shows the pre-populated information for the instance.
    Click to view larger image kvm-image-create.png

  6. (Optional) To change the instance type or the instance shape:
    1. Click Change Shape.
    2. Choose an Instance type of Virtual Machine or Bare Metal Machine.
    3. Select a compute Shape Series and Shape Name on which to deploy the image.
    4. Click Select Shape.
  7. Under Configure networking, review the pre-populated fields and make any necessary changes.
  8. (Optional) Under Boot volume, change the default boot volume size or encrypt the volume.
  9. Under Add SSH keys either generate a key pair or upload your own public key. If you provide an existing public key, when you connect to the instance you are asked to provide the associated private key. For more information on SSH keys, see Managing Key Pairs on Linux Instances.
  10. Click Create to deploy your KVM instance.

Creating a KVM Instance from Oracle Images

  1. Log in to the Console.
  2. To provision an Oracle Linux KVM instance, do one of the following:
    • Open the navigation menu. Under Core Infrastructure go to Compute, select Instances and click on Create Instance.
    • From the Oracle Cloud Infrastructure home page under Quick Actions select Create a VM instance.
  3. From the Create Instance page, click Change Image.

    The Browse All Images page displays.

  4. From the Oracle Images tab, select Oracle Linux KVM Image.
  5. Confirm that you have reviewed and accept the Oracle Standard Terms and Restrictions and click on Select Image.

    This image shows the Browse All Images page with the Oracle Linux KVM image selected, the terms and restrictions checked, and Select Image enabled.
    Click to view larger image kvm-image-browse.png

  6. (Optional) To change the instance type or the instance shape:
    1. Click Change Shape.
    2. Choose an Instance type of Virtual Machine or Bare Metal Machine.
    3. Select a compute Shape Series and Shape Name on which to deploy the image.
    4. Click Select Shape.
  7. Under Configure networking, review the pre-populated fields and make any necessary changes.
  8. (Optional) Under Boot volume, change the default boot volume size or encrypt the volume.
  9. Under Add SSH keys either generate a key pair or upload your own public key. If you provide an existing public key, when you connect to the instance you are asked to provide the associated private key. For more information on SSH keys, see Managing Key Pairs on Linux Instances.
  10. Click Create to deploy your KVM instance.

For more information, see Creating an Instance.

Accessing the Oracle Linux KVM Instance

When you connect to the newly provisioned Oracle Linux KVM instance, you use the following:

  • SSH client
  • Default user (opc)
  • Public IP address of the instance
  • Path to the SSH-2 RSA private key file

For example, from an SSH client run the following command:

$ ssh –i PRIVATE_KEY_PATH opc@PUBLIC_IP_ADDRESS

When you’re logged in as opc, you can use the sudo command to run administrative tasks. For example, run the following command to show details for all storage devices attached to your instance:

$ sudo oci-iscsi-config --show

For more information, see:

Allocating Block Storage and a VNIC

Each guest requires a dedicated Oracle Cloud Infrastructure block storage device and Oracle Cloud Infrastructure VNIC to be configured on the Console. This means that before you create a virtual machine on your new KVM instance you allocate block storage and a VNIC for your KVM instance.

Creating and Attaching Block Storage

  1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and select Block Volumes.
  2. Select Create Block Volume.

    This image shows you how to create a block volume, also described in the following text.
    Click to view larger image kvm-image-create-block.png

  3. Enter a name for your new block volume and click Create Block Volume.
  4. Open the navigation menu. Under Core Infrastructure, go to Compute and select Instances.
  5. In the Instances list, select your KVM instance.
  6. From your Instance Details page, under Resources click Attached Block Volumes.
  7. In the Attached Block Volumes section, click Attach Block Volume.

    This image shows you how to attach a block volume, also described in the following text.
    Click to view larger image kvm-image-attach-block.png

  8. From the block volume list, select the block volume you created and click Attach.

    The block volume is created and attached and displays in Attached Block Volumes on the Instance Details page.

Alternatively, you can use the oci-iscsi-config command to create and attach a block volume. For example, log in to your KVM instance from a CLI and run the following command:

$ sudo oci-iscsi-config --create-volume SIZE --volume-name MY_VOLUME

For more information, see Creating a Volume and the oci-iscsi-config man page.

Creating and Attaching VNICs

Note

The Oracle KVM image allows you to create and attach multiple VNICs on a KVM host. By repeating the following steps, you can allocate multiple VNICs for your KVM host instance.

  1. Open the navigation menu. Under Core Infrastructure, go to Compute and select Instances.
  2. In the Instances list, select your KVM instance.
  3. From your Instance Details page, under Resources click Attached VNICs.
  4. In the Attached VNICs section, click Create VNIC.

    This image shows you how to configure your VNIC and optionally change default information.
    Click to view larger image kvm-image-create-vnic.png

  5. Enter a name for the VNIC and select a virtual cloud network from the list.
  6. Select a subnet and click Save Changes.

    The VNIC is created and attached and displays in Attached VNICs on the Instance Details page.

Alternatively, you can use the oci-network-config command to create and attach VNICs. For example, log in to your KVM instance from a CLI and run the following command:

$ sudo oci-network-config --create-vnic --vnic-name MY_VNIC

For more information, see Virtual Network Interface Cards and the oci-network-config man page.

Creating and Removing a Virtual Machine

Provided with the Oracle Linux KVM image for Oracle Cloud Infrastructure is the OCI-KVM utility that allows you to create and configure KVM guests on Oracle Cloud Infrastructure instances that use Oracle Cloud Infrastructure resources such as block volumes and VNICs. 

For more information on the OCI-KVM utility's commands and options, see Using OCI-KVM Utility.

Creating a Virtual Machine

You use the create command of the OCI-KVM utility to create virtual machines.

  1. Connect to your KVM instance using ssh, for example:

    $ ssh –i PRIVATE_KEY_PATH opc@PUBLIC_IP_ADDRESS

  2. Select a block storage device for your virtual machine:
    1. Run the oci-iscsi-config --show utility to show details for all attached storage attached to your instance.
    2. Choose a device and note the Attached device name.
    3. When running the create command, add /dev/ in front of the device name to get the device path, for example /dev/sdb.
  3. Choose a specific VNIC for your virtual machine:
    1. Go to the KVM instance on the Oracle Cloud Infrastructure Console and inspect the VNIC configuration for the instance.
    2. Choose an appropriate VNIC and note the private IP address to later specify when you create a virtual machine.
      Note
      • Guests cannot share either a VNIC or a block storage device.
      • Guests can have multiple VNICs assigned and be attached to more than one virtual network.
  4. Create the virtual machine using the oci-kvm create command and with any of the available options. For more information, see Using OCI-KVM Utility.

    For example:

    $ oci-kvm create [-D | --domain VM_NAME] [-d | --disk DEVICE_PATH] [-p | --pool POOL_NAME] [-s | --disk-size DISK_SIZE] [-n | --net IP_VNIC] [-v | --virtual-network VIRTUAL_NETWORK_NAME] [-V | --virt OPT_ARGS]

    Example using block storage

    This example shows how to create an Oracle Linux 7 Update 8 guest using a specific block storage device and a serial console for console output. You can also use other options, such as VNC for console output. If a graphical option is used, you must appropriately configure the Oracle Cloud Infrastructure security list for the subnet this image is attached to.

    $ oci-kvm create -D MY_VM --disk /dev/sdb -V --vcpus 4 --memory 8192 --boot cdrom,hd --location /mnt/OracleLinux-R7-U8-Server-x86_64-dvd.iso --nographics --console pty,target_type=serial --console pty,target_type=virtio --noautoconsole --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

    Example using a storage pool and virtual networks

    This example shows how to create an Oracle Linux 7 Update 8 guest using a storage pool, a virtual network, and a serial console for console output. 

    $ oci-kvm create -D MY_VM -p MY_POOL -s 35 -v MYNET0 -V --vcpus 4 --memory 8192 --boot cdrom,hd --location /tmp/OracleLinux-R7-U8-Server-x86_64-dvd.iso --nographics --console pty,target_type=serial --console pty,target_type=virtio --noautoconsole --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

    Example using storage pool and multiple VNICs

    This example shows how to create an Oracle Linux 7 Update 8 guest that is configured to use a storage pool, multiple VNICs (2 VNIC in this example using the -n option), and a serial console for console output.

    $ oci-kvm create -D MY_VM -p MY_POOL -s 35 -n 10.0.0.97 -n 10.0.1.2 -V --vcpus 4 --memory 8192 --boot cdrom,hd --location /tmp/OracleLinux-R7-U8-Server-x86_64-dvd.iso --nographics --console pty,target_type=serial --console pty,target_type=virtio --noautoconsole --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

    Example using storage pool and multiple virtual networks

    This example shows how to create Oracle Linux 7 Update 8 guest using a storage pool, multiple libvirt networks, and a serial console for console output. 

    $ oci-kvm create -D MY_VM -p MY_POOL -s 35 -v MYNET0 -v MYNET1 -V --vcpus 4 --memory 8192 --boot cdrom,hd --location /tmp/OracleLinux-R7-U8-Server-x86_64-dvd.iso --nographics --console pty,target_type=serial --console pty,target_type=virtio --noautoconsole --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

Removing a Virtual Machine

You can use the destroy command of the OCI-KVM utility to remove and deconfigure all system resources assigned to the guest virtual machine and make them available for re-use. Before you can remove a virtual machine, you must stop it.

To stop a running virtual machine:

$ virsh destroy MY_VM

After the virtual machine stops, you can permanently destroy it:

$ oci-kvm destroy -D MY_VM

Invoking the destroy command undefines the virtual machine in libvirt as well as cleans up any host resources that were created for it. The Oracle Cloud Infrastructure resources that were allocated to the virtual machine are then made available for re-use by new virtual machines.

Using the OCI-KVM Utility

You use the OCI-KVM utility to create and configure KVM guests on Oracle Cloud Infrastructure instances that directly use Oracle Cloud Infrastructure resources, such as block storage and networking. During the automated guest creation process the utility ensures that Oracle Cloud Infrastructure resources have not been assigned to more than one KVM guest. When you no longer need a guest, the utility can remove the guest and unconfigure all system resources assigned to the guest.

The following table details the components included in the OCI-KVM utility.

Name Description
oci-kvm create
  • Performs all actions required to create a KVM guest that uses Oracle Cloud Infrastructure block storage and Oracle Cloud Infrastructure VNICs for both the root disk and network interface, respectively.
  • For block storage, validates, and checks device to ensure it has not been assigned to another guest. A storage pool can also be used.
  • For virtual network interfaces, creates all virtual network infrastructure, including virtual functions, VLANs, individual block storage devices and VNICs that are required for each guest.
  • Guests cannot share either a VNIC or a block storage device.
  • Guests can have multiple VNICs assigned and be attached to more than one virtual network.
oci-kvm destroy
  • Permanently deletes a KVM guest.
oci-kvm create-pool
  • Creates a storage pool for hosting guest virtual disks.
  • Pools can be created on block devices or FSS file systems.
oci-kvm create-network
  • Creates a libvirt network that uses and Oracle Cloud Infrastructure VNIC.
  • The created libvirt network offers an IP range that is usable by other KVM guests.
oci-kvm delete-network
  • Deletes a libvirt network previously created with the oci-kvm create-network command.

oci-kvm create

Description

This command performs all actions required to create a KVM guest that uses Oracle Cloud Infrastructure block storage and Oracle Cloud Infrastructure VNICs for both the root disk and network interface, respectively. For block storage, the device itself is validated and checked to ensure it has not been assigned to another guest. A storage pool can also be used. For virtual network interfaces, all virtual network infrastructure is created automatically, including virtual functions, VLANs, etc. indiviual block storage devices and VNICs that are required for each guest. Guests cannot share either a VNIC or a block storage device.

Usage
oci-kvm create [-h] [-D | --domain vm_name] [-d | --disk device_path] [-p | --pool pool_name] [-s | --disk-size disk_size] [-n | --net ip_vnic] [-v | --virtual-network virtual_network_name] [-V | --virt opt_args]
Options
-h | --help
Displays options for the command.
-D | --domain vm_name
Name of the virtual machine.
-d | --disk device_path
Path to the block device to be used as the root disk of the VM; use with -p | --pool and -s | --disk-size.
-s | --disk-size disk_size
Size of the disk, in gigabytes, to be created when using storage pool; use with -d | --disk and -p | --pool.
-p | --pool pool_name
Name a of storage pool to be used for root disk; use with -d | --disk and -s | --disk-size.
-v | --virtual-network virtual_network_name
The name of libvirt nework to attach the guest to; can be repeated to attach guest to multiple networks.
-n | --net ip_vnic
IP or name of the VNIC that should be assigned to the guest; can be repeated to assign multiple VNICs.
-V | --virt optional_arguments
Additional arguments to provide to virt-install. All arguments that appear after this one are passed unmodified into virt-install, even if they are arguments that oci-kvm would otherwise understand.
Example

This example shows how to create a guest named MY_VM with a root disk of 128GB on storage pool named MY_POOL using the 192.168.100.1 VNIC.

$ oci-kvm create -D MY_VM --disk-size 128 --disk DEVICE_PATH --pool MY_POOL --net 192.168.100.1 --virt --vcpu 1 --memory 8g --pxe

This example shows how to create an Oracle Linux 7 Update 8 guest configured to use a storage pool, multiple VNICs (2 VNICs in this example using the -n option) , and a serial console for console output. 

$ oci-kvm create -D MY_VM -p MY_POOL -s 35 -n 10.0.0.97 -n 10.0.1.2 -V --vcpus 4 --memory 8192 --boot cdrom,hd --location /tmp/OracleLinux-R7-U8-Server-x86_64-dvd.iso --nographics --console pty,target_type=serial --console pty,target_type=virtio --noautoconsole --os-variant=rhel7 --extra-args "console=ttyS0,115200n8"

oci-kvm destroy

Description

This command destroys a previously created guest and optionally deletes the associated storage pool-based disks.

Usage
oci-kvm destroy [-D | --domain vm_name] [--destroy-disks]
Options
-h | --help
Displays options for the command.
-D | --domain vm_name
Name of the virtual machine.
--destroy-disks
Deletes storage pool-based disks.
Example

This example shows how to destroy the MY_VM virtual machine and delete associated storage pool-based disks.

$ oci-kvm destroy -D MY_VM --destroy-disks

oci-kvm create-pool

Description

This command creates a storage pool for hosting guest virtual disks. Pools can be created on block devices or FSS file systems.

Usage
oci-kvm create-pool [-n | --name pool_name] [-d | --disk device_path]
oci-kvm create-pool [-n | --name pool_name] [-N | --netfshost ip_nfs] [-p | --path path_netfs]
Options
-h | --help
Displays options for the command.
-n | --name pool_name
Name of the storage pool.
-d | --disk device_path
Path to the disk where the storage pool is created.
-N | --netfshost ip_nfs
Name or IP of the NFS server where the storage pool is created; use with -p | --path.
-p | --path path_netfs
Path to the NETFS resource; use with -N | --netfshost.
Examples

This example shows how to create a disk-based storage pool on disk /dev/sdb.  

$ oci-kvm create-pool --disk /dev/sdb

This example shows how to create a NETFS-based storage pool named MY_POOL on NFS resource FileSystem-20201212-1454 on NFS server 192.168.100.1.

$ oci-kvm create-pool --netfshost 192.168.100.2 --path /FileSystem-20201212-1454 --name MY_POOL 

oci-kvm create-network

Description

This command creates a virtual (libvirt) network.

Usage
oci-kvm create-network [-n | --net ip_vnic] [-N | --network-name network_name] [-B | --ip-bridge ip_bridge] [-S | --ip-start ip_start] [-E | --ip-end ip_end] [-P | --ip-prefix ip_prefix]
Options
-h | --help
Displays options for the command.
-n | --net ip_vnic
IP of the VNIC used to build the network.
-N | --network-name network_name
Name of the virtual network.
-B | --ip-bridge ip_bridge
Bridge IP for virtual network address space.
-S | --ip-start ip_start
Guest first IP range in virtual network address space.
-E | --ip-end ip_end
Guest last IP range in virtual network address space.
-P | --ip-prefix ip_prefix
IP prefix to be used in virtual network.
Example

This example shows how to create a virtual network named MYNET0 on a VNIC with 10.0.1.2 as the IP address, a bridge IP of 192.168.100.9, an IP range of 192.168.100.10 - 192.268.100.30, and an IP prefix of 24.

$ oci-kvm create-network --network-name=MYNET0 --net=10.0.1.2 --ip-bridge=192.168.100.9 --ip-start=192.168.100.10 --ip-end=192.168.100.30 --ip-prefix=24

oci-kvm delete-network

Description

This command deletes a previously created virtual network.

Usage
oci-kvm delete-network [-N | --network-name network_name]
Options
-h | --help
Displays options for the command.
-N | --network-name network_name
The name of the virtual network.
Example

This example shows how to delete a virtual network named MYNET0.

$ oci-kvm delete-network --network-name=MYNET0

About Previous Releases

Review the following information to see high-level details on the changes to the Oracle Linux KVM image in previous releases.

Release 1.6
  • The base operating system is updated to Oracle Linux 7 Update 8.
  • The oci-utils packages are updated to v0.11.3-6.
  • OCI utilities have been enhanced to provide multi-VNIC support. For more information, see Using OCI-KVM Utility.
  • The Python3 implementation of OCI utilities includes security enhancements for Instance Metadata Service v2.
  • The python36-oci-sdk package installed in the image to provide added functionality for OCI utilities.
  • The Oracle Linux 7 KVM Utilities channel is enabled to provide updates for the qemu-kvm and libvirt packages.
Release 1.5
  • The base operating system is updated to Oracle Linux 7 Update 7.
  • Support for compute shapes have been enhanced to support:
    • Oracle Cloud Infrastructure AMD bare metal (BM) shape.
    • Nested virtualization for Oracle Cloud Infrastructure Intel based virtual machine (VM) shapes.

    For more information, see Creating a KVM instance.

  • New OCI-KVM utilities for Oracle Cloud Infrastructure are included in this release:
    • oci-kvm create-network

      Creates a VNIC virtual network for a KVM guest. Creates a bridged libvirt network on top of a VNIC, allowing a single VNIC to be shared among multiple guests.

    • oci-kvm delete-network

      Deletes a VNIC virtual network for a KVM guest.

    • oci-kvm create-storage-pool

      Creates, mounts and configures a file system on a block storage device or storage allocated on the Oracle Cloud File Storage Service on Oracle Cloud Infrastructure. Enables the use of a single block disk to host several guest disks.

Release 1.4
  • The base operation system is based on Oracle Linux 7 Update 5.
  • The oci-utils packages is updated to version 0.6.
  • The oci-utils package is enhanced to provide the following capabilities:
    • VNIC creation using the oci-network-config --create-vnic command.
    • Block device creation using the oci-iscsi-config --create-volume command.
  • Virtual Function network interfaces are now fully configured using the native Oracle Linux systemd LSB networking (ifcfg network configuration files).