Managing Custom Images

Updating the Image Name

You can only edit custom images. You cannot change the name of a platform image.

Using the Compute Web UI

On the Dashboard, click the Compute/View Images button.
Use the Compartment drop-down menu above the image list to select the compartment where you want to list images.
Use one of the following methods to open the Update Image dialog.
- For the image that you want to update, click the Actions menu, and click the Edit option.
- Click the name of the image that you want to update. On the image details page, click the Controls menu and click Edit Details.
In the Update Image dialog, modify the image name.

The image name does not need to be unique.
Click the Save Changes button.

Using the OCI CLI

Gather the information that you need to run the command:
- Image OCID (oci compute image list)

Run the image update command.

Syntax:

$ oci compute image update --image-id ocid1.image.unique_ID --display-name new_name

Moving an Image to a Different Compartment

To move an image, you must use the OCI CLI.

Using the OCI CLI

Get the following information:
- The OCID of the current compartment, and the OCID of the destination compartment:
```
# oci iam compartment list --compartment-id-in-subtree true
```
- The OCID of the image that you want to move:
```
# oci compute image list --compartment-id current_compartment_OCID
```

Run the image change compartment command.

Syntax:

oci compute image change-compartment \
--compartment-id destination_compartment_OCID \
--image-id image_OCID

Deleting an Image

Using the Compute Web UI

On the Dashboard, click the Compute/View Images button.
Use the Compartment drop-down menu above the image list to select the compartment where you want to list images.
For the custom image that you want to delete, click the Actions menu, then click Delete image.

The image is deleted.

Using the OCI CLI

Gather the information that you need to run the command:
- Image OCID (oci compute image list)

Run the image delete command.

Syntax:

oci compute image delete --image-id image_OCID

Example:

$ oci compute image delete --image-id ocid1.image.unique_ID
Are you sure you want to delete this resource? [y/N]: y
{
  "etag": "bbb9a3df-8f9d-47df-a419-f9d2de912b57",
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

Uploading an Image to an Object Storage Bucket

Advantages of storing an image in an Object Storage bucket are that you can implement object versioning or pre-authenticated requests as described in Managing Object Versioning and Using Pre-Authenticated Requests.

Create an Object Storage bucket as described in Creating a Bucket.
Upload an image from a local file system to the bucket. See Uploading an Object.
Import the image from the Object Storage bucket to a compartment so that the image is available to select when you launch an instance. See Importing an Image from an Object Storage Bucket.

Importing an Image from an Object Storage Bucket

You can import an image into a compartment from an Object Storage bucket.

Alternatively, you can import an image from a URL as described in Importing an Image from a URL.

Before You Begin

Ensure you have read access to the Object Storage bucket, and that the bucket contains the image that you want to use. See Managing Object Storage Buckets.

If the bucket does not contain the image that you want to use, perform the procedure described in Uploading an Image to an Object Storage Bucket.

Using the Compute Web UI

Go to the Custom Images page.
- On the Dashboard, click Compute/View Images. In the menu on the left side of the Images page, click Custom Images.
- In the navigation menu, click Compute, then click Custom Images.
On the Custom Images page, click the Import Image button.
In the Import Image dialog, enter the following information:
- Name: Enter a descriptive name for the image.
- Create in Compartment: Select the compartment where the image will be placed.
- Source Type: Select the Import from an Object Storage Bucket option.
- Bucket: Select a bucket. You might need to change the compartment to locate the bucket.
- Object Name: Select the name of an image object from the list.
- Image Type: Select one of the following options based on the type of image you are importing.
  - VMDK: Virtual machine disk file format (.vmdk), used for virtual machine disk images.
  - QCOW2: For disk image files (.qcow2) used by QEMU copy on write.
  - OCI: For Oracle Cloud Infrastructure files with a QCOW2 image and OCI metadata (.oci).
- Launch Mode: Paravirtualized is the default and cannot be changed.
- Tagging: Optionally, add one or more tags to this image as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Import Image button in the dialog.

The imported image appears in the Custom Images list for the compartment, with a state of Importing. To track the progress of the operation, view the associated work request.

When the import completes successfully, the image state changes to Available, and the image can be used to launch instances as described in Creating an Instance.

Using the OCI CLI

Gather the information that you need to run the command:
- Compartment OCID:
```
oci iam compartment list --compartment-id-in-subtree true
```
- Object Storage bucket name:
```
oci os bucket list -c compartment_OCID
```
- Name of the image object in the bucket:
```
oci os object list --bucket-name bucket_name
```
- Object Storage namespace. See Obtaining the Object Storage Namespace.
- Image type. If the image is a VMDK or QCOW2 image, you must specify that type as the argument to the --source-image-type option. If you do not specify the --source-image-type option, the image is assumed to be an OCI file: a QCOW2 image and OCI metadata. If --source-image-type is not specified and the image type is not OCI, the import will fail.
Run the image import from object command.

Syntax:
```
oci compute image import from-object \
--compartment-id compartment_OCID --bucket-name bucket_name \
--name bucket_image_object_name --namespace namespace
```
You can specify the --display-name option to give the imported image a custom name. The name does not need to be unique, and you can change it later. You cannot use a platform image name as a custom image name.

Important:

If you are importing a Microsoft Windows image, specify the --operating-system option and include the case-insensitive string "Windows" in the value to ensure optimal performance of the instance.

If you specify the --operating-system option and this is not a Microsoft Windows image, make sure the value does not contain the case-insensitive string "Windows".

Importing an Image from a URL

You can import an image into a compartment by specifying the URL of the image file.

Alternatively, you can import an image from an Object Storage bucket as described in Importing an Image from an Object Storage Bucket.

Before You Begin

Get the URL that you need for this procedure. Ensure that the URL is accessible from your tenancy.

Using the Compute Web UI

On the Dashboard, click Compute/View Images. In the menu on the left side of the Images page, click Custom Images.
On the Custom Images page, click the Import Image button.
In the Import Image dialog, enter the following information:
- Name: Enter a descriptive name for the image.
- Create in Compartment: Select the compartment where the image will be placed.
- Source Type: Select the Import from an Object Storage URL option.
- Object Storage URL: Enter the URL of the image. The URL does not need to be an Object Storage URL. It can be any URL that provides access to the image.
- Image Type: Select one of the following options based on the type of image you are importing.
  - VMDK: Virtual machine disk file format (.vmdk), used for virtual machine disk images.
  - QCOW2: For disk image files (.qcow2) used by QEMU copy on write.
  - OCI: For Oracle Cloud Infrastructure files with a QCOW2 image and OCI metadata (.oci).
- Launch Mode: Paravirtualized is the default and cannot be changed.
- Tagging: Optionally, add one or more tags to this image as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Import Image button in the dialog.

The imported image appears in the Custom Images list for the compartment, with a state of Importing. To track the progress of the operation, view the associated work request.

When the import completes successfully, the image state changes to Available, and the image can be used to launch instances as described in Creating an Instance.

Using the OCI CLI

Gather the information that you need to run the command:
- Compartment OCID:
```
oci iam compartment list --compartment-id-in-subtree true
```
- The URL for the image. The URL does not need to be an Object Storage URL. It can be any URL that can be accessed from your tenancy.
- Image type. If the image is a VMDK or QCOW2 image, you must specify that type as the argument to the --source-image-type option. If you do not specify the --source-image-type option, the image is assumed to be an OCI file: a QCOW2 image and OCI metadata. If --source-image-type is not specified and the image type is not OCI, the import will fail.

Run the image import from object URI command.

Syntax:

oci compute image import from-object-uri \
--compartment-id compartment_OCID --uri URL_for_image

You can specify the --display-name option to give the imported image a custom name. The name does not need to be unique, and you can change it later. You cannot use a platform image name as a custom image name.

Important:

If you are importing a Microsoft Windows image, specify the --operating-system option and include the case-insensitive string "Windows" in the value to ensure optimal performance of the instance.

If you specify the --operating-system option and this is not a Microsoft Windows image, make sure the value does not contain the case-insensitive string "Windows".

Example:

$ oci compute image import from-object-uri \
--compartment-id compartment_OCID \
--uri http://fqdn_or_ip_address/compute_images/uln-pca-Oracle-Linux-8-2022.02.25_0.oci \
--display-name "Oracle Linux 8 2-25-22"
{
  "data": {
    "agent-features": null,
    "base-image-id": null,
    "billable-size-in-gbs": null,
    "compartment-id": "ocid1.compartment.unique_ID",
    "create-image-allowed": true,
    "defined-tags": {},
    "display-name": "Oracle Linux 8 2-25-22",
    "freeform-tags": {},
    "id": "ocid1.image.unique_ID",
    "launch-mode": "PARAVIRTUALIZED",
    "launch-options": null,
    "lifecycle-state": "IMPORTING",
    "listing-type": null,
    "operating-system": "UNAVAILABLE",
    "operating-system-version": "UNAVAILABLE",
    "size-in-mbs": 0,
    "time-created": "2022-04-19T20:44:35.163119+00:00"
  },
  "etag": "ab0c6265-c671-4ccb-a9b1-279d9437ba87",
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

Exporting an Image to an Object Storage Bucket

You can export an image to an Object Storage bucket. You need write access to the bucket.

Alternatively, you can export an image to a URL as described in Exporting an Image to a URL.

Exported images are a copy of the boot volume and metadata when the image was created.

Using the Compute Web UI

On the Dashboard, click Compute/View Images. In the menu on the left side of the Images page, click Custom Images.
Click the name of the custom image that you want to export. If the image that you want to export is not listed, use the compartment menu above the image list.
On the image details page, click the Controls menu and then click the Export Image option.
In the Export Custom Image dialog, enter the following information:
- Export Destination: Select the Export to an Object Storage Bucket option.
- Bucket: Select a bucket. If necessary, use the menu to select a different compartment.
- Object Name: Enter a name for the exported image.
- Export Format: Select one of the following options based on the type of image you are exporting.
  - VMDK: Virtual machine disk file format (.vmdk), used for virtual machine disk images.
  - QCOW2: For disk image files (.qcow2) used by QEMU copy on write.
  - OCI: For Oracle Cloud Infrastructure files with a QCOW2 image and OCI metadata (.oci).
Click the Create Export button in the dialog.

The image state changes to Exporting. Exporting a custom image copies the data to the Object Storage location that you specified. To track the progress of the operation, view the associated work request.

You can still launch instances while the image is exporting, but you cannot delete the image until the export has finished.

When the export is complete, the image state changes to Available. If the image state changes to Available, but you do not see the exported image in the Object Storage location you specified, the export failed, and you need to go through the steps again to export the image.

Using the OCI CLI

Ensure that a bucket is available.

See Listing Buckets and Creating a Bucket.
Gather the information that you need to run the command:
- Object Storage bucket name. See Step 1.
- Image OCID (oci compute image list)
- Object Storage namespace. See Obtaining the Object Storage Namespace.
- The name the exported image file will have in object storage. This is the same parameter as my-object in the URL example in the following "Export to a URL" procedure.
- The format of the exported image: OCI, QCOW2, or VMDK. See the preceding Compute Web UI procedure for descriptions.
  
  If the image format is not OCI, then you must use the --export-format option to specify the image format. If --export-format is not specified, the image is exported in OCI format.

Run the image export to object command.

Syntax:

oci compute image export to-object --bucket-name bucketname \
--image-id image_OCID --namespace namespace \
--name exported_image_object_name
--export-format VMDK

Exporting an Image to a URL

You can export an image to a URL. You need write access to the export location.

Alternatively, you can export an image to an Object Storage bucket as described in Exporting an Image to an Object Storage Bucket.

Exported images are a copy of the boot volume and metadata when the image was created.

Using the Compute Web UI

On the Dashboard, click Compute/View Images. In the menu on the left side of the Images page, click Custom Images.
Click the name of the custom image that you want to export. If the image that you want to export is not listed, use the compartment menu above the image list.
On the image details page, click the Controls menu and then click the Export Image option.
In the Export Custom Image dialog, enter the following information:
- Export Destination: Select the Export to an Object Storage URL option.
- Object Storage URL: Enter the URL where you want to export the image. The URL does not need to be an Object Storage URL. It can be any URL that provides access to the image.
- Export Format: Select one of the following options based on the type of image you are exporting.
  - VMDK: Virtual machine disk file format (.vmdk), used for virtual machine disk images.
  - QCOW2: For disk image files (.qcow2) used by QEMU copy on write.
  - OCI: For Oracle Cloud Infrastructure files with a QCOW2 image and OCI metadata (.oci).
Click the Export Image button in the dialog.

The image state changes to Exporting. Exporting a custom image copies the data to the Object Storage location that you specified. To track the progress of the operation, view the associated work request.

You can still launch instances while the image is exporting, but you cannot delete the image until the export has finished.

When the export is complete, the image state changes to Available. If the image state changes to Available, but you do not see the exported image in the Object Storage location you specified, the export failed, and you need to go through the steps again to export the image.

Using the OCI CLI

Ensure that a bucket with a pre-authenticated request is available, and that you have the request URL. See:
Gather the information that you need to run the command:
- Image OCID (oci compute image list)
- URI. See Step 1.
- The format of the exported image: OCI, QCOW2, or VMDK. See the preceding Compute Web UI procedure for descriptions.
  
  If the image format is not OCI, then you must use the --export-format option to specify the image format. If --export-format is not specified, the image is exported in OCI format.

Run the image export to object URI command.

Syntax:

oci compute image export to-object-uri --image-id image_OCID \
--uri URL_to_export_to

Example:

oci compute image export to-object-uri \
--image-id ocid1.image.unique_ID \
--uri https://objectstorage.mypca01.example.com/p/MrxLFkKlFkIlNDhvhcZnrjbUAlsoeah/n/mynamespace/b/my-bucket/o/my-object
{
  "data": {
    "agent-features": null,
    "base-image-id": null,
    "compartment-id": "ocid1.tenancy.unique_ID",
    "create-image-allowed": true,
    "defined-tags": null,
    "display-name": "PCA OL8 Image",
    "freeform-tags": null,
    "id": "ocid1.image.unique_ID",
    "launch-mode": "PARAVIRTUALIZED",
    "launch-options": {
      "boot-volume-type": "PARAVIRTUALIZED",
      "firmware": "UEFI_64",
      "is-consistent-volume-naming-enabled": false,
      "is-pv-encryption-in-transit-enabled": false,
      "network-type": "PARAVIRTUALIZED",
      "remote-data-volume-type": "PARAVIRTUALIZED"
    },
    "lifecycle-state": "EXPORTING",
    "listing-type": null,
    "operating-system": "OracleLinux",
    "operating-system-version": "8",
    "size-in-mbs": 47694,
    "time-created": "2022-01-18T16:29:13.114742+00:00"
  },
  "etag": "5d24f645-b446-42f2-a777-112457f0cafe",
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

You can use image import and export to share custom images across tenancies so that you don't need to recreate the image manually in each tenancy. You create the image in one of the tenancies, and then export the image, making it available for import in additional tenancies.

These are the high-level tasks:

Export the image to an Object Storage bucket. See Exporting an Image to an Object Storage Bucket.
Create a pre-authenticated request with read-only access for the image in the bucket. See Using Pre-Authenticated Requests.
In the destination tenancy, import the image. Use the pre-authenticated request URL as the Object Storage URL. See Importing an Image from a URL.

Updating the Image Name

Moving an Image to a Different Compartment

Deleting an Image

Uploading an Image to an Object Storage Bucket

Importing an Image from an Object Storage Bucket

Importing an Image from a URL

Exporting an Image to an Object Storage Bucket

Exporting an Image to a URL

Sharing Custom Images Across Tenancies