Configuring Image Capabilities for Custom Images

Image capabilities are the configuration options available when launching an instance from an image. Some image capability examples are the firmware used to boot the instance, the volume attachment types supported, and so on. The full set of image capabilities provided by Oracle Cloud Infrastructure Compute are defined in the global image capability schema. You can also create your own custom image capability schemas based on the global image capability schema to specify and configure image capabilities for your custom images. Using these schemas, you can customize the image configuration and options available when users launch instances from your custom images.

Caution

Using this feature allows you to customize image capabilities from the default capabilities that Oracle recommends and should be used for advanced custom image scenarios only. Ensure that you understand the optimal configuration options for your custom image.

Global Image Capability Schema

The following JSON is what's returned when you use the GetComputeGlobalImageCapabilitySchemaVersion API operation or the global-image-capability-schema-version CLI command. It represents the full set of image capabilities available for images. The default values specified for each element are the recommended values for each option.

You can customize these options by creating image capability schemas. When you create an image capability schema, you can specify a subset of the values that are included in the global capabilities schema. Values that are not included in the global capabilities schema cannot be provided in an image capability schema.

{
  "Compute.AMD_SecureEncryptedVirtualization": {
    "descriptorType": "boolean",
    "source": "IMAGE",
    "defaultValue": false
  },
  "Compute.Firmware": {
    "descriptorType": "enumstring",
    "values": [
      "BIOS",
      "UEFI_64"
    ],
    "defaultValue": "UEFI_64"
  },
  "Compute.SecureBoot": {
      "descriptorType": "boolean",
      "defaultValue": false
  },
  "Compute.LaunchMode": {
    "descriptorType": "enumstring",
    "values": [
      "NATIVE",
      "EMULATED",
      "PARAVIRTUALIZED",
      "CUSTOM"
    ],
    "defaultValue": "PARAVIRTUALIZED"
  },
  "Network.AttachmentType": {
    "descriptorType": "enumstring",
    "values": [
      "E1000",
      "VFIO",
      "PARAVIRTUALIZED"
    ],
    "defaultValue": "PARAVIRTUALIZED"
  },
  "Storage.BootVolumeType": {
    "descriptorType": "enumstring",
    "values": [
      "ISCSI",
      "SCSI",
      "IDE",
      "PARAVIRTUALIZED"
    ],
    "defaultValue": "PARAVIRTUALIZED"
  },
  "Storage.LocalDataVolumeType": {
    "descriptorType": "enumstring",
    "values": [
      "ISCSI",
      "SCSI",
      "IDE",
      "PARAVIRTUALIZED"
    ],
    "defaultValue": "PARAVIRTUALIZED"
  },
  "Storage.RemoteDataVolumeType": {
    "descriptorType": "enumstring",
    "values": [
      "ISCSI",
      "SCSI",
      "IDE",
      "PARAVIRTUALIZED"
    ],
    "defaultValue": "PARAVIRTUALIZED"
  },
  "Storage.ConsistentVolumeNaming": {
    "descriptorType": "boolean",
    "defaultValue": "true"
  },
  "Storage.ParaVirtualization.EncryptionInTransit": {
    "descriptorType": "boolean",
    "defaultValue": "true"
  },
  "Storage.ParaVirtualization.AttachmentVersion": {
    "descriptorType": "enuminteger",
    "values": [
      1,
      2
    ],
    "defaultValue": 2
   },
   "Storage.Iscsi.MultipathDeviceSupported": {
    "descriptorType": "boolean",
    "defaultValue": false
   }
}

Schema Elements

The following list describes all the available elements in the global image capabilities schema.

Compute.AMD_SecureEncryptedVirtualization: Provides confidential computing to virtual machine users leveraging AMD Secure Encrypted Virtualization (SEV) on AMD shapes. Data is encrypted in-use and you can verify the confidentiality through a secure attestation process. The default value is false.
Compute.Firmware: The firmware used to boot the virtual machine instance. The default value is UEFI_64.
Compute.SecureBoot: Whether the instance can use Secure Boot. The default value is false.

Important

Custom images do not support Secure Boot.
Compute.LaunchMode: The configuration mode for launching instances. The default value is PARAVIRTUALIZED.
Network.AttachmentType: The emulation type for the primary VNIC, which is automatically created and attached when the instance is launched. The default value is PARAVIRTUALIZED.
Storage.BootVolumeType: Specifies the driver options for the image's boot volume. The default value is PARAVIRTUALIZED.
Storage.LocalDataVolumeType: Specifies the driver options for the image to access local storage volumes. The default value is PARAVIRTUALIZED.
Storage.RemoteDataVolumeType: Specifies the driver options for the image to access remote storage volumes. The default value is PARAVIRTUALIZED.
Storage.ConsistentVolumeNaming: Specifies whether consistent device paths for iSCSI and paravirtualized attached block volumes are enabled for the image. If enabled, the image must support consistent device names. The default value is true.
Storage.ParaVirtualization.EncryptionInTransit: Specifies whether in-transit encryption is enabled for the image's boot volume attachment. Applies only to paravirtualized boot volume attachments. The default value is true.
Storage.ParaVirtualization.AttachmentVersion: Specifies the paravirtualization version for boot volume and block volume attachments. Applies only to paravirtualized volume attachments. The default value is 2.
Storage.Iscsi.MultipathDeviceSupported: Specifies whether multipath-enabled attachments are supported for the image. Applies only to iSCSI volume attachments. The default value is false.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment to work in.

If you're new to policies, see Getting Started with Policies and Common Policies. For reference material about writing policies for instances, cloud networks, or other Core Services API resources, see Details for Core Services.

For administrators, the following policy provides full access to the image capability schema framework:

Allow group IAM_group_name to manage compute-image-capability-schema in tenancy

Using the Console

Open the navigation menu and click Compute. Under Compute, click Custom Images.
Click the custom image that you're interested in.
Click Edit image capabilities.
Edit the image capabilities that you want to configure. For details about each image capability, see Schema Elements.
Click Save changes.

Using the CLI

For information about using the CLI, see Command Line Interface (CLI). To work with image capability schemas using the CLI, open a command prompt and run any of the following commands.

To list out the global image capability schema:

oci compute global-image-capability-schema list

To list out the global image capability schema versions:

oci compute global-image-capability-schema-version list --global-image-capability-schema-id <global_image_capability_schema_OCID>

To retrieve the global image capability schema version:

oci compute global-image-capability-schema-version get --global-image-capability-schema-id <global_image_capability_schema_OCID> --global-image-capability-schema-version-name <version_name>

To list the image capability schemas in the specified compartment:

oci compute image-capability-schema list --compartment-id <compartment_OCID>

To retrieve the image capability schema for the specified ID:

oci compute image-capability-schema get --image-capability-schema-id <image_capability_schema_OCID>

To update the specified image capability schema:

oci -d compute image-capability-schema update --image-capability-schema-id <image_capability_schema_OCID> --schema-data file://<schema_data_file>.json

To create an image capability schema:

oci compute image-capability-schema create --schema-data file://<schema_data_file>.json --compartment-id <compartment_OCID> --image-id <image_OCID> --global-image-capability-schema-version-name <version_name>

When you create the schema, you specify the image OCID for the custom image you want to apply the image capability schema to.

To delete the specified image capability schema:

oci -d compute image-capability-schema delete --image-capability-schema-id <image_capability_schema_OCID>

Using the API

For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

Use the following API operations for working with image capability schemas:

Example

This example shows how to use the CLI to update the image capability schema for a custom image. For information about using the CLI, see Command Line Interface (CLI).

Open a command prompt, and run the following command to retrieve the current global schema for the region:

oci compute global-image-capability-schema list

The response is similar to the following:

{
  "data":
  [
    {
      "compartment-id": null,
      "current-version-name": "<version_name>",
      "defined-tags":
      {},
      "display-name": "OCI.ComputeGlobalImageCapabilitySchema",
      "freeform-tags":
      {},
      "id": "ocid1.computeglobalimgcapschema.oc1.phx.<unique_ID>",
      "time-created": "2020-03-23T19:20:39.656000+00:00"
    }
  ],
  "opc-next-page": "<unique_ID>"
}

Using the OCID and version name of the global image capability schema that you retrieved in the previous step, run the following command to get the global image capability schema:
```
oci compute global-image-capability-schema-version get --global-image-capability-schema-id <global_image_capability_schema_OCID> --global-image-capability-schema-version-name <version_name>
```
The response contains the global image capability schema.
Locate the schema element that you want to update, and then do the following:
1. Copy the schema element that you want to update. This example uses the Storage.ParaVirtualization.EncryptionInTransit schema element.
2. If the schema element contains a source field, change the value from GLOBAL to IMAGE. For example:
```
{
  "Storage.ParaVirtualization.EncryptionInTransit":
  {
    "default-value": true,
    "descriptor-type": "boolean",
    "source": "IMAGE"
  }
}
```
3. Save the updated schema elements as a .json file.

To verify whether the image is already using image capability, run the following command:

oci compute image-capability-schema list --image-id <image_OCID>

If the image is using image capability, the response contains a line similar to the following:
```
"compute-global-image-capability-schema-version-name": "<version_name>"
```
The response also contains the image capability schema OCID.

If the image is not using image capability, create an image capability schema for the image by running the following command:

oci compute image-capability-schema create --global-image-capability-schema-version-name <version_name> --image-id <image_OCID> --schema-data file://<schema_data_file>.json --compartment-id <compartment_OCID>

<schema_data_file> is the path to the .json file that contains the schema elements that you want to update, which you created in the previous step.