volume_groups

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

Overview

Name	volume_groups
Type	Resource
Id	oci.block_storage.volume_groups

Fields

The following fields are returned by SELECT queries:

get

The volume group's information has been retrieved.

Name	Datatype	Description
id	string	The OCID for the volume group.
availabilityDomain	string	The availability domain of the volume group.
compartmentId	string	The OCID of the compartment that contains the volume group.
definedTags	object	Defined 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"}}
displayName	string	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
freeformTags	object	Free-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"}
isHydrated	boolean	Specifies whether the newly created cloned volume group's data has finished copying from the source volume group or backup.
lifecycleState	string	The current state of a volume group. (PROVISIONING, AVAILABLE, TERMINATING, TERMINATED, FAULTY)
sizeInGBs	integer (int64)	The aggregate size of the volume group in GBs.
sizeInMBs	integer (int64)	The aggregate size of the volume group in MBs.
sourceDetails	object	Specifies the source for a volume group.
timeCreated	string (date-time)	The date and time the volume group was created. Format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339).
volumeGroupReplicas	array	The list of volume group replicas of this volume group.
volumeIds	array	OCIDs for the volumes in this volume group.

list

Specifies a volume group which is a collection of<br />volumes. For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br /><br />Warning: Oracle recommends that you avoid using any confidential information when you<br />supply string values using the API.<br />

Name	Datatype	Description
id	string	The OCID for the volume group.
availabilityDomain	string	The availability domain of the volume group.
compartmentId	string	The OCID of the compartment that contains the volume group.
definedTags	object	Defined 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"}}
displayName	string	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
freeformTags	object	Free-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"}
isHydrated	boolean	Specifies whether the newly created cloned volume group's data has finished copying from the source volume group or backup.
lifecycleState	string	The current state of a volume group. (PROVISIONING, AVAILABLE, TERMINATING, TERMINATED, FAULTY)
sizeInGBs	integer (int64)	The aggregate size of the volume group in GBs.
sizeInMBs	integer (int64)	The aggregate size of the volume group in MBs.
sourceDetails	object	Specifies the source for a volume group.
timeCreated	string (date-time)	The date and time the volume group was created. Format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339).
volumeGroupReplicas	array	The list of volume group replicas of this volume group.
volumeIds	array	OCIDs for the volumes in this volume group.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	volumeGroupId, region		Gets information for the specified volume group. For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).
list	select	compartmentId, region	availabilityDomain, limit, page, displayName, sortBy, sortOrder, lifecycleState	Lists the volume groups in the specified compartment and availability domain.<br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />
create	insert	region, availabilityDomain, compartmentId, sourceDetails	opc-retry-token	Creates a new volume group in the specified compartment.<br />A volume group is a collection of volumes and may be created from a list of volumes, cloning an existing<br />volume group, or by restoring a volume group backup.<br />You may optionally specify a display name for the volume group, 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 /><br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />
update	update	volumeGroupId, region	if-match, preserveVolumeReplica	Updates the set of volumes in a volume group along with the display name. Use this operation<br />to add or remove volumes in a volume group. Specify the full list of volume IDs to include in the<br />volume group. If the volume ID is not specified in the call, it will be removed from the volume group.<br />Avoid entering confidential information.<br /><br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />
delete	delete	volumeGroupId, region	if-match	Deletes the specified volume group. Individual volumes are not deleted, only the volume group is deleted.<br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />
change_compartment	exec	volumeGroupId, region, compartmentId	opc-request-id	Moves a volume group 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.

Name	Datatype	Description
compartmentId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment.
region	string	OCI 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)
volumeGroupId	string	The Oracle Cloud ID (OCID) that uniquely identifies the volume group.
availabilityDomain	string	The name of the availability domain. Example: Uocm:PHX-AD-1
displayName	string	A filter to return only resources that match the given display name exactly.
if-match	string	For 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.
lifecycleState	string	A filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limit	integer	For 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-id	string	Unique identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-token	string	A 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).
page	string	For 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).
preserveVolumeReplica	boolean	Specifies whether to disable or preserve the individual volume replication when removing a volume from the replication enabled volume group. When set to true, the individual volume replica is preserved. The default value is true.
sortBy	string	The 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.
sortOrder	string	The sort order to use, either ascending (ASC) or descending (DESC). The DISPLAYNAME sort order is case sensitive.

SELECT examples

get

Gets information for the specified volume group. For more information, see Volume Groups.

SELECT
id,
availabilityDomain,
compartmentId,
definedTags,
displayName,
freeformTags,
isHydrated,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceDetails,
timeCreated,
volumeGroupReplicas,
volumeIds
FROM oci.block_storage.volume_groups
WHERE volumeGroupId = '{{ volumeGroupId }}' -- required
AND region = '{{ region }}' -- required
;

list

Lists the volume groups in the specified compartment and availability domain.<br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />

SELECT
id,
availabilityDomain,
compartmentId,
definedTags,
displayName,
freeformTags,
isHydrated,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceDetails,
timeCreated,
volumeGroupReplicas,
volumeIds
FROM oci.block_storage.volume_groups
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND availabilityDomain = '{{ availabilityDomain }}'
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND displayName = '{{ displayName }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND lifecycleState = '{{ lifecycleState }}'
;

INSERT examples

create

Creates a new volume group in the specified compartment.<br />A volume group is a collection of volumes and may be created from a list of volumes, cloning an existing<br />volume group, or by restoring a volume group backup.<br />You may optionally specify a display name for the volume group, 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 /><br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />

INSERT INTO oci.block_storage.volume_groups (
availabilityDomain,
backupPolicyId,
clusterPlacementGroupId,
compartmentId,
definedTags,
displayName,
freeformTags,
sourceDetails,
volumeGroupReplicas,
region,
opc-retry-token
)
SELECT 
'{{ availabilityDomain }}' /* required */,
'{{ backupPolicyId }}',
'{{ clusterPlacementGroupId }}',
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
'{{ sourceDetails }}' /* required */,
'{{ volumeGroupReplicas }}',
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
availabilityDomain,
compartmentId,
definedTags,
displayName,
freeformTags,
isHydrated,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceDetails,
timeCreated,
volumeGroupReplicas,
volumeIds
;

Manifest

# Description fields are for documentation purposes
- name: volume_groups
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the volume_groups resource.
  - name: availabilityDomain
    value: "{{ availabilityDomain }}"
    description: |
      The availability domain of the volume group.
  - name: backupPolicyId
    value: "{{ backupPolicyId }}"
    description: |
      If provided, specifies the ID of the volume backup policy to assign to the newly
      created volume group. If omitted, no policy will be assigned.
  - name: clusterPlacementGroupId
    value: "{{ clusterPlacementGroupId }}"
    description: |
      The clusterPlacementGroup Id of the volume group for volume group placement.
  - name: compartmentId
    value: "{{ compartmentId }}"
    description: |
      The OCID of the compartment that contains the volume group.
  - name: definedTags
    value: "{{ definedTags }}"
    description: |
      Defined 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"}}`
  - name: displayName
    value: "{{ displayName }}"
    description: |
      A user-friendly name. Does not have to be unique, and it's changeable.
      Avoid entering confidential information.
  - name: freeformTags
    value: "{{ freeformTags }}"
    description: |
      Free-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"}`
  - name: sourceDetails
    description: |
      Specifies the source for a volume group.
    value:
      type: "{{ type }}"
  - name: volumeGroupReplicas
    description: |
      The list of volume group replicas that this volume group will be enabled to have
      in the specified destination availability domains.
    value:
      - availabilityDomain: "{{ availabilityDomain }}"
        displayName: "{{ displayName }}"
  - name: opc-retry-token
    value: "{{ opc-retry-token }}"
    description: A 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). 
    description: A 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). 

UPDATE examples

update

Updates the set of volumes in a volume group along with the display name. Use this operation<br />to add or remove volumes in a volume group. Specify the full list of volume IDs to include in the<br />volume group. If the volume ID is not specified in the call, it will be removed from the volume group.<br />Avoid entering confidential information.<br /><br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />

UPDATE oci.block_storage.volume_groups
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
volumeGroupReplicas = '{{ volumeGroupReplicas }}',
volumeIds = '{{ volumeIds }}'
WHERE 
volumeGroupId = '{{ volumeGroupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND preserveVolumeReplica = {{ preserveVolumeReplica}}
RETURNING
id,
availabilityDomain,
compartmentId,
definedTags,
displayName,
freeformTags,
isHydrated,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceDetails,
timeCreated,
volumeGroupReplicas,
volumeIds;

DELETE examples

delete

Deletes the specified volume group. Individual volumes are not deleted, only the volume group is deleted.<br />For more information, see [Volume Groups](/iaas/Content/Block/Concepts/volumegroups.htm).<br />

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

Lifecycle Methods

change_compartment

Moves a volume group 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.volume_groups.change_compartment 
@volumeGroupId='{{ volumeGroupId }}' --required, 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;