Skip to main content

volumes

Creates, updates, deletes, gets or lists a volumes resource.

Overview​

Namevolumes
TypeResource
Idoci.block_storage.volumes

Fields​

The following fields are returned by SELECT queries:

The volume's information has been retrieved.

NameDatatypeDescription
idstringThe OCID of the volume.
autoTunedVpusPerGBinteger (int64)The number of Volume Performance Units per GB that this volume is effectively tuned to.
autotunePoliciesarrayThe list of autotune policies enabled for this volume.
availabilityDomainstringThe availability domain of the volume. Example: Uocm:PHX-AD-1
blockVolumeReplicasarrayThe list of block volume replicas of this volume.
clusterPlacementGroupIdstringThe clusterPlacementGroup Id of the volume for volume placement.
compartmentIdstringThe OCID of the compartment that contains the volume.
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. Does not have to be unique, and it's changeable. Avoid entering confidential information.
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"}
isAutoTuneEnabledbooleanSpecifies whether the auto-tune performance is enabled for this volume. This field is deprecated. Use the DetachedVolumeAutotunePolicy instead to enable the volume for detached autotune.
isHydratedbooleanSpecifies whether the cloned volume's data has finished copying from the source volume or backup.
isReservationsEnabledbooleanWhen set to true, enables SCSI Persistent Reservation (SCSI PR) for the volume. For more information, see [Persistent Reservations](/iaas/Content/Block/Concepts/persistent-reservations.htm).
kmsKeyIdstringThe OCID of the Vault service key which is the master encryption key for the volume.
lifecycleStatestringThe current state of a volume. (PROVISIONING, RESTORING, AVAILABLE, TERMINATING, TERMINATED, FAULTY)
sizeInGBsinteger (int64)The size of the volume in GBs.
sizeInMBsinteger (int64)The size of the volume in MBs. This field is deprecated. Use sizeInGBs instead.
sourceDetailsobjectSpecifies the volume source details for a new Block volume. The volume source is either another Block volume in the same Availability Domain or a Block volume backup. This is an optional field. If not specified or set to null, the new Block volume will be empty. When specified, the new Block volume will contain data from the source volume or backup.
timeCreatedstring (date-time)The date and time the volume was created. Format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339).
volumeGroupIdstringThe OCID of the source volume group.
vpusPerGBinteger (int64)The number of volume performance units (VPUs) that will be applied to this volume per GB, representing the Block Volume service's elastic performance options. See [Block Volume Performance Levels](/iaas/Content/Block/Concepts/blockvolumeperformance.htm#perf_levels) for more information. Allowed values: * 0: Represents Lower Cost option. * 10: Represents Balanced option. * 20: Represents Higher Performance option. * 30-120: Represents the Ultra High Performance option. For performance autotune enabled volumes, It would be the Default(Minimum) VPUs/GB.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectvolumeId, regionGets information for the specified volume.
listselectcompartmentId, regionavailabilityDomain, limit, page, displayName, sortBy, sortOrder, volumeGroupId, clusterPlacementGroupId, lifecycleStateLists the volumes in the specified compartment and availability domain.<br />
createinsertregion, compartmentIdopc-retry-tokenCreates a new volume in the specified compartment. Volumes can be created in sizes ranging from<br />50 GB (51200 MB) to 32 TB (33554432 MB), in 1 GB (1024 MB) increments. By default, volumes are 1 TB (1048576 MB).<br />For general information about block volumes, see<br />[Overview of Block Volume Service](/iaas/Content/Block/Concepts/overview.htm).<br /><br />A volume and instance can be in separate compartments but must be in the same availability domain.<br />For information about access control and compartments, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm). For information about<br />availability domains, see [Regions and Availability Domains](/iaas/Content/General/Concepts/regions.htm).<br />To get a list of availability domains, use the ListAvailabilityDomains operation<br />in the Identity and Access Management Service API.<br /><br />You may optionally specify a display name for the volume, which is simply a friendly name or<br />description. It does not have to be unique, and you can change it. Avoid entering confidential information.<br />
updateupdatevolumeId, regionif-matchUpdates the specified volume's display name.<br />Avoid entering confidential information.<br />
deletedeletevolumeId, regionif-matchDeletes the specified volume. The volume cannot have an active connection to an instance.<br />To disconnect the volume from a connected instance, see<br />[Disconnecting From a Volume](/iaas/Content/Block/Tasks/disconnectingfromavolume.htm).<br />Warning: All data on the volume will be permanently lost when the volume is deleted.<br />
change_compartmentexecvolumeId, region, compartmentIdopc-request-idMoves a volume into a different compartment within the same tenancy.<br />For information about moving resources between compartments,<br />see [Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<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.
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)
volumeIdstringThe OCID of the volume.
availabilityDomainstringThe name of the availability domain. Example: Uocm:PHX-AD-1
clusterPlacementGroupIdstringA filter to return only resources that match the given cluster placement group Id exactly.
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).
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).
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.
volumeGroupIdstringThe OCID of the volume group.

SELECT examples​

Gets information for the specified volume.

SELECT
id,
autoTunedVpusPerGB,
autotunePolicies,
availabilityDomain,
blockVolumeReplicas,
clusterPlacementGroupId,
compartmentId,
definedTags,
displayName,
freeformTags,
isAutoTuneEnabled,
isHydrated,
isReservationsEnabled,
kmsKeyId,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceDetails,
timeCreated,
volumeGroupId,
vpusPerGB
FROM oci.block_storage.volumes
WHERE volumeId = '{{ volumeId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new volume in the specified compartment. Volumes can be created in sizes ranging from<br />50 GB (51200 MB) to 32 TB (33554432 MB), in 1 GB (1024 MB) increments. By default, volumes are 1 TB (1048576 MB).<br />For general information about block volumes, see<br />[Overview of Block Volume Service](/iaas/Content/Block/Concepts/overview.htm).<br /><br />A volume and instance can be in separate compartments but must be in the same availability domain.<br />For information about access control and compartments, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm). For information about<br />availability domains, see [Regions and Availability Domains](/iaas/Content/General/Concepts/regions.htm).<br />To get a list of availability domains, use the ListAvailabilityDomains operation<br />in the Identity and Access Management Service API.<br /><br />You may optionally specify a display name for the volume, which is simply a friendly name or<br />description. It does not have to be unique, and you can change it. Avoid entering confidential information.<br />

INSERT INTO oci.block_storage.volumes (
autotunePolicies,
availabilityDomain,
backupPolicyId,
blockVolumeReplicas,
clusterPlacementGroupId,
compartmentId,
definedTags,
displayName,
freeformTags,
isAutoTuneEnabled,
isReservationsEnabled,
kmsKeyId,
sizeInGBs,
sizeInMBs,
sourceDetails,
volumeBackupId,
vpusPerGB,
region,
opc-retry-token
)
SELECT 
'{{ autotunePolicies }}',
'{{ availabilityDomain }}',
'{{ backupPolicyId }}',
'{{ blockVolumeReplicas }}',
'{{ clusterPlacementGroupId }}',
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
{{ isAutoTuneEnabled }},
{{ isReservationsEnabled }},
'{{ kmsKeyId }}',
{{ sizeInGBs }},
{{ sizeInMBs }},
'{{ sourceDetails }}',
'{{ volumeBackupId }}',
{{ vpusPerGB }},
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
autoTunedVpusPerGB,
autotunePolicies,
availabilityDomain,
blockVolumeReplicas,
clusterPlacementGroupId,
compartmentId,
definedTags,
displayName,
freeformTags,
isAutoTuneEnabled,
isHydrated,
isReservationsEnabled,
kmsKeyId,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceDetails,
timeCreated,
volumeGroupId,
vpusPerGB
;

UPDATE examples​

Updates the specified volume's display name.<br />Avoid entering confidential information.<br />

UPDATE oci.block_storage.volumes
SET 
autotunePolicies = '{{ autotunePolicies }}',
blockVolumeReplicas = '{{ blockVolumeReplicas }}',
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
isAutoTuneEnabled = {{ isAutoTuneEnabled }},
isReservationsEnabled = {{ isReservationsEnabled }},
sizeInGBs = {{ sizeInGBs }},
vpusPerGB = {{ vpusPerGB }}
WHERE 
volumeId = '{{ volumeId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
autoTunedVpusPerGB,
autotunePolicies,
availabilityDomain,
blockVolumeReplicas,
clusterPlacementGroupId,
compartmentId,
definedTags,
displayName,
freeformTags,
isAutoTuneEnabled,
isHydrated,
isReservationsEnabled,
kmsKeyId,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceDetails,
timeCreated,
volumeGroupId,
vpusPerGB;

DELETE examples​

Deletes the specified volume. The volume cannot have an active connection to an instance.<br />To disconnect the volume from a connected instance, see<br />[Disconnecting From a Volume](/iaas/Content/Block/Tasks/disconnectingfromavolume.htm).<br />Warning: All data on the volume will be permanently lost when the volume is deleted.<br />

DELETE FROM oci.block_storage.volumes
WHERE volumeId = '{{ volumeId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Lifecycle Methods​

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

EXEC oci.block_storage.volumes.change_compartment 
@volumeId='{{ volumeId }}' --required, 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;