Integrating with Oracle Cloud Infrastructure

This section describes how to use the features of Oracle VM VirtualBox to integrate with Oracle Cloud Infrastructure.

Integrating with Oracle Cloud Infrastructure involves the following steps:

Preparing for Oracle Cloud Infrastructure Integration

Perform the following configuration steps before using Oracle VM VirtualBox to integrate with your Oracle Cloud Infrastructure account.

  1. Install the Extension Pack. Cloud integration features are only available when you install the Oracle VM VirtualBox Extension Pack. See .

  2. Create a key pair. Generate an API signing key pair that is used for API requests to Oracle Cloud Infrastructure. See .

    Upload the public key of the key pair from your client device to the cloud service. See .

  3. Create a cloud profile. The cloud profile contains resource identifiers for your cloud account, such as your user OCID, and details of your key pair. See .

Creating an API Signing Key Pair

To use the cloud integration features of Oracle VM VirtualBox, you must generate an API signing key pair that is used for API requests to Oracle Cloud Infrastructure.

Your API requests are signed with your private key, and Oracle Cloud Infrastructure uses the public key to verify the authenticity of the request. You must upload the public key to the Oracle Cloud Infrastructure Console.

Note

This key pair is not the same SSH key that you use to access compute instances on Oracle Cloud Infrastructure.

  1. (Optional) Create a .oci directory to store the key pair. 

    $ mkdir ~/.oci

    The key pair is usually installed in the .oci folder in your home directory. For example, ~/.oci on a Linux system.

  2. Generate the private key.

    Use the openssl command.

    • To generate a private key with a passphrase: 

      $ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048

    • To generate a private key without a passphrase: 

      $ openssl genrsa -out ~/.oci/oci_api_key.pem 2048

  3. Change permissions for the private key. 

    $ chmod 600 ~/.oci/oci_api_key.pem

    Generate the public key. 

    $ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem

Uploading the Public Key to Oracle Cloud Infrastructure

Use the following steps to upload your public key to Oracle Cloud Infrastructure.

  1. Log in to the Oracle Cloud Infrastructure Console.

  2. Display the User Settings page.

    Click Profile, User Settings.

  3. Display your current API signing keys.

    Click Resources, API Keys.

  4. Upload the public key.

    Click Add Public Key.

    The Add Public Key dialog is displayed.

    Figure 1.13. Upload Public Key Dialog in Oracle Cloud Infrastructure Console

    upload public key dialog in oracle cloud infrastructure console

    Select one of the following options:

    • Choose Public Key File. This option enables you to browse to the public key file on your local hard disk.

    • Paste Public Keys. This option enables you to paste the contents of the public key file into the window in the dialog box.

    Click Add to upload the public key.

Creating a Cloud Profile

Oracle VM VirtualBox uses a cloud profile to connect to Oracle Cloud Infrastructure. A cloud profile is a text file that contains details of your key files and Oracle Cloud Identifier (OCID) resource identifiers for your cloud account, such as the following:

You can create a cloud profile in the following ways:

Using the Cloud Profile Manager

This section describes how to use the Cloud Profile Manager to create a cloud profile.

To open the Cloud Profile Manager click File, Cloud Profile Manager in the VirtualBox Manager window.

Figure 1.14. The Cloud Profile Manager

the cloud profile manager

You can use the Cloud Profile Manager in the following ways:

Perform the following steps to create a new cloud profile automatically, using the Cloud Profile Manager:

  1. Click the Add icon and specify a Name for the profile.

  2. Click Properties and specify the following property values for the profile:

    • Compartment OCID

    • Fingerprint of the public key

    • Location of the private key on the client device

    • Region OCID

    • Tenancy OCID

    • User OCID

    Some of these are settings for your Oracle Cloud Infrastructure account, which you can view from the Oracle Cloud Infrastructure Console.

  3. Click Apply to save your changes.

    The cloud profile settings are saved in the oci_config file in your Oracle VM VirtualBox global settings directory.

Perform the following steps to import an existing Oracle Cloud Infrastructure configuration file into the Cloud Profile Manager:

  1. Ensure that a config file is present in your Oracle Cloud Infrastructure configuration directory. For example, this is $HOME/.oci/config on a Linux host.

  2. Click the Import icon to open a dialog that prompts you to import cloud profiles from external files.

    Warning

    This action overwrites any cloud profiles that are in your Oracle VM VirtualBox global settings directory.

  3. Click Import.

    Your cloud profile settings are saved to the oci_config file in your Oracle VM VirtualBox global settings directory.

  4. Click Properties to show the cloud profile settings.

    Double-click on the appropriate field to change the value.

  5. Click Apply to save your changes.

Using Oracle VM VirtualBox With Oracle Cloud Infrastructure

This section describes how you can use Oracle VM VirtualBox with Oracle Cloud Infrastructure to do the following tasks:

Exporting an Appliance to Oracle Cloud Infrastructure

Oracle VM VirtualBox supports the export of VMs to an Oracle Cloud Infrastructure service. The exported VM is stored on Oracle Cloud Infrastructure as a custom Linux image. You can configure whether a cloud instance is created and started after the export process has completed.

Note

Before you export a VM to Oracle Cloud Infrastructure, you must prepare the VM as described in .

Use the following steps to export a VM to Oracle Cloud Infrastructure:

  1. Select File, Export Appliance to open the Export Virtual Appliance wizard.

    Select a VM to export and click Next to open the Appliance Settings screen.

  2. From the Format drop-down list, select Oracle Cloud Infrastructure.

    In the Account drop-down list, select the cloud profile for your Oracle Cloud Infrastructure account.

    The list after the Account field shows the profile settings for your cloud account.

    Figure 1.15. Appliance Settings Screen, Showing Cloud Profile and Machine Creation Settings

    appliance settings screen, showing cloud profile and machine creation settings

    In the Machine Creation field, select an option to configure settings for a cloud instance created when you export to Oracle Cloud Infrastructure. The options enable you to do one of the following:

    • Configure settings for the cloud instance after you have finished exporting the VM.

    • Configure settings for the cloud instance before you start to export the VM.

    • Do not create a cloud instance when you export the VM.

    Click Next to make an API request to the Oracle Cloud Infrastructure service and open the Virtual System Settings screen.

  3. (Optional) Edit storage settings used for the exported virtual machine in Oracle Cloud Infrastructure. You can change the following settings:

    • The name of the bucket used to store the exported files.

    • Whether to store the custom image in Oracle Cloud Infrastructure.

    • The name for the custom image in Oracle Cloud Infrastructure.

    • The launch mode for the custom image.

      Paravirtualized mode gives improved performance and should be suitable for most Oracle VM VirtualBox VMs.

      Emulated mode is suitable for legacy OS images.

    Click Export to continue.

  4. Depending on the selection in the Machine Creation field, the Cloud Virtual Machine Settings screen may be displayed before or after export. This screen enables you to configure settings for the cloud instance, such as Shape and Disk Size.

    Click Create. The VM is exported to Oracle Cloud Infrastructure.

    Depending on the Machine Creation setting, a cloud instance may be started after upload to Oracle Cloud Infrastructure is completed.

  5. Monitor the export process by using the Oracle Cloud Infrastructure Console.

You can also use the VBoxManage export command to export a VM to Oracle Cloud Infrastructure. See .

Preparing a VM for Export to Oracle Cloud Infrastructure

Oracle Cloud Infrastructure provides the option to import a custom Linux image. Before an Oracle VM VirtualBox image can be exported to Oracle Cloud Infrastructure, the custom image needs to be prepared to ensure that instances launched from the custom image can boot correctly and that network connections will work. This section provides advice on how to prepare a Linux image for export from Oracle VM VirtualBox.

The following list shows some tasks to consider when preparing an Oracle Linux VM for export:

For more information about importing a custom Linux image into Oracle Cloud Infrastructure, see also:

Importing an Instance from Oracle Cloud Infrastructure

Perform the following steps to import a cloud instance from Oracle Cloud Infrastructure into Oracle VM VirtualBox:

  1. Select File, Import Appliance to open the Import Virtual Appliance wizard.

    In the Source drop-down list, select Oracle Cloud Infrastructure.

    In the Account drop-down list, select the cloud profile for your Oracle Cloud Infrastructure account.

    The list after the Account field shows the profile settings for your cloud account.

    Choose the required cloud instance from the list in the Machines field.

    Click Next to make an API request to the Oracle Cloud Infrastructure service and display the Appliance Settings screen.

  2. (Optional) Edit settings for the new local virtual machine.

    For example, you can edit the VM name and description.

    Figure 1.16. Import Cloud Instance Screen, Showing Profile Settings and VM Settings

    import cloud instance screen, showing profile settings and vm settings

    Click Import to import the instance from Oracle Cloud Infrastructure.

  3. Monitor the import process by using the Oracle Cloud Infrastructure Console.

You can also use the VBoxManage import command to import an instance from Oracle Cloud Infrastructure. See .

Importing an Instance: Overview of Events

The following describes the sequence of events when you import an instance from Oracle Cloud Infrastructure.

Creating New Cloud Instances from a Custom Image

You can use Oracle VM VirtualBox to create new instances from a custom image on your cloud service.

describes how to create a custom image when you are exporting a VM to Oracle Cloud Infrastructure. Using a custom image means that you can quickly create cloud instances without having to upload your image to the cloud service every time.

Perform the following steps to create a new cloud instance on Oracle Cloud Infrastructure:

  1. Select File, New Cloud VM to open the Create Cloud Virtual Machine wizard.

  2. From the Destination drop-down list, select Oracle Cloud Infrastructure.

    In the Account drop-down list, select the cloud profile for your Oracle Cloud Infrastructure account.

    The list after the Account field shows the profile settings for your cloud account.

    In the Images list, select from the custom images available on Oracle Cloud Infrastructure.

    Figure 1.17. New Cloud VM Wizard, Showing List of Custom Images

    new cloud vm wizard, showing list of custom images

    Click Next to make an API request to the Oracle Cloud Infrastructure service and open the Cloud Virtual Machine Settings screen.

  3. (Optional) Edit settings used for the new instance on Oracle Cloud Infrastructure.

    For example, you can edit the Disk Size and Shape used for the VM instance and the networking configuration.

    Click Create to create the new cloud instance.

  4. Monitor the instance creation process by using the Oracle Cloud Infrastructure Console.

You can also use the VBoxManage cloud instance command to create and manage instances on a cloud service. See .

Using VBoxManage Commands With Oracle Cloud Infrastructure

This section includes some examples of how VBoxManage commands can be used to integrate with Oracle Cloud Infrastructure and perform common cloud operations.

Creating a Cloud Profile

To create a cloud profile called vbox-oci: 

VBoxManage cloudprofile --provider "OCI" --profile="vbox-oci" add \
--clouduser="ocid1.user.oc1..."  --keyfile="/home/username/.oci/oci_api_key.pem" \
--tenancy="ocid1.tenancy.oc1..."  --compartment="ocid1.compartment.oc1..."  --region="us-ashburn-1"

The new cloud profile is added to the oci_config file in your Oracle VM VirtualBox global configuration directory. For example, this is $HOME/.VirtualBox/oci_config on a Windows host.

Listing Cloud Instances

To list the instances in your Oracle Cloud Infrastructure compartment: 

VBoxManage cloud --provider="OCI" --profile="vbox-oci" list instances

Exporting an Oracle VM VirtualBox VM to the Cloud

To export a VM called myVM and create a cloud instance called myVM_Cloud: 

VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \
--cloudprofile "vbox-oci" --cloudbucket myBucket \
--cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50  \
--cloudocivcn ocid1.vcn.oc1... --cloudocisubnet ocid1.subnet.oc1... \
--cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true

Importing a Cloud Instance Into Oracle VM VirtualBox

To import a cloud instance and create an Oracle VM VirtualBox VM called oci_Import: 

VBoxManage import OCI:// --cloud --vmname oci_Import --memory 4000
--cpus 3 --ostype FreeBSD_64 --cloudprofile "vbox-oci"
--cloudinstanceid ocid1.instance.oc1... --cloudbucket myBucket

Creating a New Cloud Instance From a Custom Image

To create a new cloud instance from a custom image on Oracle Cloud Infrastructure: 

VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance create \
--domain-name="oraclecloud.com" --image-id="ocid1.image.oc1..." --display-name="myInstance" \
--shape="VM.Standard2.1" --subnet="ocid1.subnet.oc1..."

Terminating a Cloud Instance

To terminate an instance in your compartment on Oracle Cloud Infrastructure: 

VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance terminate \
--id="ocid1.instance.oc1..."

For more details about the available commands for cloud operations, see .