API Overview

API Overview

This section describes some of the most commonly used Cinder API calls and their corresponding CLI commands. It is not meant to be a comprehensive list that is representative of all functionality present in Cinder; for more information, please refer to the OpenStack Configuration Reference.

Note

Block Storage V2 API has been deprecated. To ensure Cinder does not use the V2 API, update enable_v2_api=false and enable_v3_api=true in your cinder.conf file.

Volume API

Table 4.2, “Cinder API Overview - Volume” specifies the valid operations that can be performed on Cinder volumes. Please note that Cinder volumes are identified as CLI command arguments by either their names or UUID.

Operation CLI Command Description
Create cinder create Create a Cinder volume of specified size; optional name, availability zone, volume type
Delete cinder delete Delete an existing Cinder volume; the cinder force-delete command may be required if the Cinder volume is in an error state
Edit cinder metadata Set or unset metadata on a Cinder volume
Extend cinder extend Increase the capacity of a Cinder volume to the specified size
List cinder list List all Cinder volumes
Migrate cinder migrate Move a Cinder volume to a new Cinder backend (specified by name)
Show cinder show Show details about a Cinder volume
Upload as image cinder upload-to-image Upload a Cinder volume to the OpenStack Image Service
Manage cinder manage Bring an existing storage object under Cinder management
Unmanage cinder unmanage Cease management of an existing Cinder volume without deleting the backing storage object
Revert to snapshot cinder revert-to-snapshot Restore a Cinder volume to the state and data of the most recent snapshot. This command is only available in microversion 3.40 and above.

Table 4.2. Cinder API Overview - Volume

Snapshot API

Table 4.3, “Cinder API Overview - Snapshot” specifies the valid operations that can be performed on Cinder snapshots. Please note that Cinder snapshots are identified as CLI command arguments by either their display name or UUID.

Operation CLI Command Description
Create cinder snapshot-create Create a Cinder snapshot of a specific Cinder volume
Delete cinder snapshot-delete Delete a Cinder snapshot
Edit cinder snapshot-metadata Set or unset metadata on a Cinder snapshot
List cinder snapshot-list List all Cinder snapshots
Rename cinder snapshot-rename Change the display-name of a Cinder snapshot
Reset State cinder snapshot-reset-state Reset the state of a Cinder snapshot
Show cinder snapshot-show Show details about a Cinder snapshot

Table 4.3. Cinder API Overview - Snapshot

Consistency Group API

Table 4.4, “Cinder API Overview - Consistency Groups” specifies the valid operations that can be performed on Cinder consistency groups. Please note that Cinder consistency groups and cgsnapshots are identified as CLI command arguments by either their display name or UUID. Consistency group operations support has been deprecated in Block Storage V3 API. Only Block Storage V2 API supports consistency groups. Future releases will involve a migration of existing consistency group operations to use generic volume group operations.

Operation CLI Command Description
Create cinder consisgroup-create Create a consistency group with support for at least one volume type
Show cinder consisgroup-show Display details for a specified consistency group
List cinder consisgroup-list Show a list of all created consistency groups
Create a volume and add it to a consistency group cinder create Expand a consistency group to have another volume by creating a volume with the --consisgroup-id parameter
Create a cgsnapshot cinder cgsnapshot-create Generate a snapshot of a consistency group
Show a snapshot of a consistency group cinder cgsnapshot-show Display details for the cgsnapshot of consistency group
List consistency group snapshots cinder cgsnapshot-list Display all cgsnapshots for a consistency group
Delete a snapshot of a consistency group cinder cgsnapshot-delete Remove a cgsnapshot
Delete a consistency group cinder consisgroup-delete The --force flag is required when volumes are inside the consistency group
Modify a consistency group cinder consisgroup-update Add or remove volumes from a consistency group with --add-volumes [UUID-list] or --remove-volumes [UUID-list] parameters
Create a consistency group from the snapshot of another consistency group cinder consisgroup-create-from-src Use a cgsnapshot to generate a new consistency group
Create a consistency group from a source consistency group cinder consisgroup-create-from-src Copy a consistency group

Table 4.4. Cinder API Overview - Consistency Groups

Backup API

Table 4.5, “Cinder API Overview - Backup” specifies the valid operations that can be performed on Cinder backups. Please note that Cinder backups are identified as CLI command arguments by either their display name or UUID.

Operation CLI Command Description
Create cinder backup-create Create a Cinder backup
Delete cinder backup-delete Delete a Cinder backup
List cinder backup-list List all Cinder backups
Restore cinder backup-restore Restore a Cinder backup into a Cinder volume
Show cinder backup-show Show details about a Cinder backup

Table 4.5. Cinder API Overview - Backup

Group API

Table 4.6, “Cinder API Overview - Group” specifies the valid operations that can be performed on Cinder groups. Please note that Cinder groups are identified as CLI command arguments by either their display name or UUID.

Note

Currently only the Block Storage V3 API supports group operations. The minimum version for group operations supported by the ONTAP drivers is 3.14. The API version can be specified with the following CLI flag --os-volume-api-version 3.14

Note

The Cinder community plans to migrate existing consistency group operations to group operations in an upcoming release. Please review Cinder release notes for upgrade instructions prior to using group operations.

Note

The ONTAP volume drivers support the consistent_group_snapshot_enabled group type. By default Cinder group snapshots take individual snapshots of each Cinder volume in the group. To enable consistency group snapshots set consistent_group_snapshot_enabled="<is> True" in the group type used. Be aware that only one consistency group snapshot per storage pool (i.e. flexvol) can be performed at a time. Overlapping consistency group snapshot operations can fail.

Operation CLI Command Description
Create cinder group-create Creates a group.
Create a group from a source group cinder group-create-from-src Creates a group from a group snapshot or a source group.
Delete cinder group-delete Removes one or more groups.
List cinder group-list Lists all groups.
Show cinder group-show Shows details of a group.
Update cinder group-update Updates a group.
Create group snapshot cinder group-snapshot-create Creates a group snapshot.
Delete group snapshot cinder group-snapshot-delete Removes one or more group snapshots.
List group snapshot cinder group-snapshot-list Lists all group snapshots.
Show group snapshot cinder group-snapshot-show Shows group snapshot details.
Create group type cinder group-type-create Creates a group type.
Delete group type cinder group-type-delete Deletes group type or types.
List default group type cinder group-type-default List the default group type.
List group types cinder group-type-list Lists available ‘group types’. (Admin only will see private types)
Show group type cinder group-type-show Show group type details.
Update group type cinder group-type-update Updates group type name, description, and/or is_public.
List group specs cinder group-specs-list Lists current group types and specs.
Set group specs cinder group-type-key Set or unset group_spec for a group type.

Table 4.6. Cinder API Overview - Volume Group

Volume Type API

Table 4.7, “Cinder API Overview - Volume Type” specifies the valid operations that can be performed on Cinder volume types. Please note that Cinder volume types are identified as CLI command arguments by either their display name or UUID.

Operation CLI Command Description
Create cinder type-create Create a Cinder volume type
Delete cinder type-delete Delete a Cinder volume type
List cinder type-list List existing Cinder volume type

Table 4.7. Cinder API Overview - Volume Type

Volume Type Extra Specs API

Table 4.8, “Cinder API Overview - Volume Type Extra Specs” specifies the valid operations that can be performed on Cinder volume type extra specs. Please note that Cinder volume type extra specs are properties of Cinder volume types and are identified by their parent object.

Operation CLI Command Description
Set extra specs cinder type-key vtype set Assign extra specs to Cinder volume type
Unset extra specs cinder type-key vtype unset Remove extra specs from Cinder volume type

Table 4.8. Cinder API Overview - Volume Type Extra Specs

Volume Type QoS Specs API

Table 4.9, “Cinder API Overview - Volume Type QoS Specs” specifies the valid operations that can be performed on Cinder volume type QoS specs. Please note that Cinder volume type QoS specs are created independently of Cinder volume types and are subsequently associated with a Cinder volume type.

Operation CLI Command Description
Create QoS specs cinder qos-create Create a Cinder QoS Spec
Delete QoS specs cinder qos-delete Delete a Cinder QoS Spec
List QoS specs cinder qos-list List existing Cinder QoS Specs
Show cinder qos-show Show details about a Cinder QoS Spec
Associate QoS specs cinder qos-associate Associate a Cinder QoS Spec with a Cinder volume type
Disassociate QoS specs cinder qos-disassociate Disassociate a Cinder QoS Spec from a Cinder volume type
Edit QoS spec cinder qos-key Set or unset specifications for a Cinder QoS Spec

Table 4.9. Cinder API Overview - Volume Type QoS Specs