Skip to main content

images

Creates, updates, deletes, gets or lists an images resource.

Overview​

Nameimages
TypeResource
Idoci.compute.images

Fields​

The following fields are returned by SELECT queries:

The image was retrieved.

NameDatatypeDescription
idstringThe OCID of the image.
agentFeaturesobjectOracle Cloud Agent features supported on the image.
baseImageIdstringThe OCID of the image originally used to launch the instance.
billableSizeInGBsinteger (int64)The size of the internal storage for this image that is subject to billing (1 GB = 1,073,741,824 bytes). Example: 100
compartmentIdstringThe OCID of the compartment containing the instance you want to use as the basis for the image.
createImageAllowedbooleanWhether instances launched with this image can be used to create new images. For example, you cannot create an image of an Oracle Database instance. Example: true
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
displayNamestringA user-friendly name for the image. It does not have to be unique, and it's changeable. Avoid entering confidential information. You cannot use a platform image name as a custom image name. Example: My custom Oracle Linux image
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
launchModestringSpecifies the configuration mode for launching virtual machine (VM) instances. The configuration modes are: * NATIVE - VM instances launch with iSCSI boot and VFIO devices. The default value for platform images. * EMULATED - VM instances launch with emulated devices, such as the E1000 network driver and emulated SCSI disk controller. * PARAVIRTUALIZED - VM instances launch with paravirtualized devices using VirtIO drivers. * ACCELERATEDPV - VM instances launch with accelerated paravirtualized networking type. * CUSTOM - VM instances launch with custom configuration settings specified in the LaunchOptions parameter. (NATIVE, EMULATED, PARAVIRTUALIZED, ACCELERATEDPV, CUSTOM)
launchOptionsobjectOptions for tuning the compatibility and performance of VM shapes. The values that you specify override any default values.
lifecycleStatestring (PROVISIONING, IMPORTING, AVAILABLE, EXPORTING, DISABLED, DELETED)
operatingSystemstringThe image's operating system. Example: Oracle Linux
operatingSystemVersionstringThe image's operating system version. Example: 7.2
sizeInMBsinteger (int64)The boot volume size for an instance launched from this image (1 MB = 1,048,576 bytes). Note this is not the same as the size of the image when it was exported or the actual size of the image. Example: 47694
timeCreatedstring (date-time)The date and time the image was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectimageId, regionGets the specified image.
listselectcompartmentId, regiondisplayName, operatingSystem, operatingSystemVersion, shape, limit, page, sortBy, sortOrder, lifecycleStateLists a subset of images available in the specified compartment, including<br />[platform images](/iaas/Content/Compute/References/images.htm) and<br />[custom images](/iaas/Content/Compute/Tasks/managingcustomimages.htm).<br />The list of platform images includes the three most recently published versions<br />of each major distribution. The list does not support filtering based on image tags.<br /><br />The list of images returned is ordered to first show the recent platform images,<br />then all of the custom images.<br /><br />Caution: Platform images are refreshed regularly. When new images are released, older versions are replaced.<br />The image OCIDs remain available, but when the platform image is replaced, the image OCIDs are no longer returned as part of the platform image list.<br />
createinsertregion, compartmentIdopc-retry-tokenCreates a boot disk image for the specified instance or imports an exported image from the Oracle Cloud Infrastructure Object Storage service.<br /><br />When creating a new image, you must provide the OCID of the instance you want to use as the basis for the image, and<br />the OCID of the compartment containing that instance. For more information about images,<br />see [Managing Custom Images](/iaas/Content/Compute/Tasks/managingcustomimages.htm).<br /><br />When importing an exported image from Object Storage, you specify the source information<br />in [ImageSourceDetails](#/en/iaas/latest/requests/ImageSourceDetails).<br /><br />When importing an image based on the namespace, bucket name, and object name,<br />use [ImageSourceViaObjectStorageTupleDetails](#/en/iaas/latest/requests/ImageSourceViaObjectStorageTupleDetails).<br /><br />When importing an image based on the Object Storage URL, use<br />[ImageSourceViaObjectStorageUriDetails](#/en/iaas/latest/requests/ImageSourceViaObjectStorageUriDetails).<br />See [Object Storage URLs](/iaas/Content/Compute/Tasks/imageimportexport.htm#URLs) and [Using Pre-Authenticated Requests](/iaas/Content/Object/Tasks/usingpreauthenticatedrequests.htm)<br />for constructing URLs for image import/export.<br /><br />For more information about importing exported images, see<br />[Image Import/Export](/iaas/Content/Compute/Tasks/imageimportexport.htm).<br /><br />You may optionally specify a display name for the image, which is simply a friendly name or description.<br />It does not have to be unique, and you can change it. See [UpdateImage](#/en/iaas/latest/Image/UpdateImage).<br />Avoid entering confidential information.<br />
updateupdateimageId, regionopc-retry-token, if-matchUpdates the display name of the image. Avoid entering confidential information.<br />
deletedeleteimageId, regionif-matchDeletes an image.
change_compartmentexecimageId, region, compartmentIdif-match, opc-request-id, opc-retry-tokenMoves an image into a different compartment within the same tenancy. For information about moving<br />resources between compartments, see<br />[Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br />
export_imageexecimageId, region, destinationTypeopc-retry-token, if-matchExports the specified image to the Oracle Cloud Infrastructure Object Storage service. You can use the Object Storage URL,<br />or the namespace, bucket name, and object name when specifying the location to export to.<br /><br />For more information about exporting images, see [Image Import/Export](/iaas/Content/Compute/Tasks/imageimportexport.htm).<br /><br />To perform an image export, you need write access to the Object Storage bucket for the image,<br />see [Let Users Write Objects to Object Storage Buckets](/iaas/Content/Identity/Concepts/commonpolicies.htm#Let4).<br /><br />See [Object Storage URLs](/iaas/Content/Compute/Tasks/imageimportexport.htm#URLs) and [Using Pre-Authenticated Requests](/iaas/Content/Object/Tasks/usingpreauthenticatedrequests.htm)<br />for constructing URLs for image import/export.<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
compartmentIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment.
imageIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the image.
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
displayNamestringA filter to return only resources that match the given display name exactly.
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerFor list pagination. The maximum number of results per page, or items to return in a paginated "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine). Example: 50
opc-request-idstringUnique identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
operatingSystemstringThe image's operating system. Example: Oracle Linux
operatingSystemVersionstringThe image's operating system version. Example: 7.2
pagestringFor list pagination. The value of the opc-next-page response header from the previous "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
shapestringShape name.
sortBystringThe field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for DISPLAYNAME is ascending. The DISPLAYNAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by availability domain if the scope of the resource type is within a single availability domain. If you call one of these "List" operations without specifying an availability domain, the resources are grouped by availability domain, then sorted.
sortOrderstringThe sort order to use, either ascending (ASC) or descending (DESC). The DISPLAYNAME sort order is case sensitive.

SELECT examples​

Gets the specified image.

SELECT
id,
agentFeatures,
baseImageId,
billableSizeInGBs,
compartmentId,
createImageAllowed,
definedTags,
displayName,
freeformTags,
launchMode,
launchOptions,
lifecycleState,
operatingSystem,
operatingSystemVersion,
sizeInMBs,
timeCreated
FROM oci.compute.images
WHERE imageId = '{{ imageId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a boot disk image for the specified instance or imports an exported image from the Oracle Cloud Infrastructure Object Storage service.<br /><br />When creating a new image, you must provide the OCID of the instance you want to use as the basis for the image, and<br />the OCID of the compartment containing that instance. For more information about images,<br />see [Managing Custom Images](/iaas/Content/Compute/Tasks/managingcustomimages.htm).<br /><br />When importing an exported image from Object Storage, you specify the source information<br />in [ImageSourceDetails](#/en/iaas/latest/requests/ImageSourceDetails).<br /><br />When importing an image based on the namespace, bucket name, and object name,<br />use [ImageSourceViaObjectStorageTupleDetails](#/en/iaas/latest/requests/ImageSourceViaObjectStorageTupleDetails).<br /><br />When importing an image based on the Object Storage URL, use<br />[ImageSourceViaObjectStorageUriDetails](#/en/iaas/latest/requests/ImageSourceViaObjectStorageUriDetails).<br />See [Object Storage URLs](/iaas/Content/Compute/Tasks/imageimportexport.htm#URLs) and [Using Pre-Authenticated Requests](/iaas/Content/Object/Tasks/usingpreauthenticatedrequests.htm)<br />for constructing URLs for image import/export.<br /><br />For more information about importing exported images, see<br />[Image Import/Export](/iaas/Content/Compute/Tasks/imageimportexport.htm).<br /><br />You may optionally specify a display name for the image, which is simply a friendly name or description.<br />It does not have to be unique, and you can change it. See [UpdateImage](#/en/iaas/latest/Image/UpdateImage).<br />Avoid entering confidential information.<br />

INSERT INTO oci.compute.images (
compartmentId,
definedTags,
displayName,
freeformTags,
imageSourceDetails,
instanceId,
launchMode,
launchOptions,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
'{{ imageSourceDetails }}',
'{{ instanceId }}',
'{{ launchMode }}',
'{{ launchOptions }}',
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
agentFeatures,
baseImageId,
billableSizeInGBs,
compartmentId,
createImageAllowed,
definedTags,
displayName,
freeformTags,
launchMode,
launchOptions,
lifecycleState,
operatingSystem,
operatingSystemVersion,
sizeInMBs,
timeCreated
;

UPDATE examples​

Updates the display name of the image. Avoid entering confidential information.<br />

UPDATE oci.compute.images
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
operatingSystem = '{{ operatingSystem }}',
operatingSystemVersion = '{{ operatingSystemVersion }}'
WHERE 
imageId = '{{ imageId }}' --required
AND region = '{{ region }}' --required
AND opc-retry-token = '{{ opc-retry-token}}'
AND if-match = '{{ if-match}}'
RETURNING
id,
agentFeatures,
baseImageId,
billableSizeInGBs,
compartmentId,
createImageAllowed,
definedTags,
displayName,
freeformTags,
launchMode,
launchOptions,
lifecycleState,
operatingSystem,
operatingSystemVersion,
sizeInMBs,
timeCreated;

DELETE examples​

Deletes an image.

DELETE FROM oci.compute.images
WHERE imageId = '{{ imageId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Lifecycle Methods​

Moves an image into a different compartment within the same tenancy. For information about moving<br />resources between compartments, see<br />[Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br />

EXEC oci.compute.images.change_compartment 
@imageId='{{ imageId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;