Block Storage API V1 (DEPRECATED)

Block Storage API V1 (DEPRECATED)

Quota sets extension (os-quota-sets)

Administrators only, depending on policy settings.

Shows, updates, and deletes quotas for a tenant.

GET
/v1/{admin_tenant_id}/os-quota-sets/{tenant_id}/detail/{user_id}

Show quota details for user (v1)

Shows details for quotas for a tenant and user.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
admin_tenant_id (Optional) path string The UUID of the administrative tenant.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
user_id (Optional) path string The user ID. Specify in the URI as user_id={user_id}.

Response Parameters

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
reserved (Optional) body integer Reserved volume size. Visible only if you set the usage=true query parameter.
in_use (Optional) body string The in use data size. Visible only if you set the usage=true query parameter.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
instances body integer The number of instances that are allowed for each tenant.
limit body integer The number of items permitted for this tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
id body string The UUID of the volume.
security_groups body integer The number of security groups that are allowed for each tenant.

Response Example

{
    "quota_set": {
        "cores": {
            "in_use": 0,
            "limit": 20,
            "reserved": 0
        },
        "fixed_ips": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "floating_ips": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "injected_files": {
            "in_use": 0,
            "limit": 5,
            "reserved": 0
        },
        "instances": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "key_pairs": {
            "in_use": 0,
            "limit": 100,
            "reserved": 0
        },
        "metadata_items": {
            "in_use": 0,
            "limit": 128,
            "reserved": 0
        },
        "ram": {
            "in_use": 0,
            "limit": 51200,
            "reserved": 0
        },
        "security_groups": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "injected_file_content_bytes": {
            "in_use": 0,
            "limit": 10240,
            "reserved": 0
        },
        "injected_file_path_bytes": {
            "in_use": 0,
            "limit": 255,
            "reserved": 0
        },
        "security_group_rules": {
            "in_use": 0,
            "limit": 20,
            "reserved": 0
        }
    }
}
GET
/v1/{tenant_id}/os-quota-sets/defaults

Show default quotas

Shows default quotas for a tenant.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Response Parameters

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
reserved (Optional) body integer Reserved volume size. Visible only if you set the usage=true query parameter.
in_use (Optional) body string The in use data size. Visible only if you set the usage=true query parameter.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
instances body integer The number of instances that are allowed for each tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
id body string The UUID of the volume.
security_groups body integer The number of security groups that are allowed for each tenant.

Response Example

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": 10,
        "id": "fake_tenant",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": 20,
        "security_groups": 10
    }
}
GET
/v1/{admin_tenant_id}/os-quota-sets/{tenant_id}

Show quotas (v1)

Shows quotas for a tenant.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
admin_tenant_id (Optional) path string The UUID of the administrative tenant.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
usage (Optional) query boolean Set to usage=true to show quota usage. Default is false.

Response Parameters

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
reserved (Optional) body integer Reserved volume size. Visible only if you set the usage=true query parameter.
in_use (Optional) body string The in use data size. Visible only if you set the usage=true query parameter.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
instances body integer The number of instances that are allowed for each tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
id body string The UUID of the volume.
security_groups body integer The number of security groups that are allowed for each tenant.

Response Example

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": 10,
        "id": "fake_tenant",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": 20,
        "security_groups": 10
    }
}
PUT
/v1/{admin_tenant_id}/os-quota-sets/{tenant_id}

Update quotas (v1)

Updates quotas for a tenant.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
id body string The UUID of the volume.
instances body integer The number of instances that are allowed for each tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
security_groups body integer The number of security groups that are allowed for each tenant.
admin_tenant_id (Optional) path string The UUID of the administrative tenant.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Request Example

{
    "quota_set": {
        "security_groups": 45
    }
}

Response Parameters

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
reserved (Optional) body integer Reserved volume size. Visible only if you set the usage=true query parameter.
in_use (Optional) body string The in use data size. Visible only if you set the usage=true query parameter.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
instances body integer The number of instances that are allowed for each tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
id body string The UUID of the volume.
security_groups body integer The number of security groups that are allowed for each tenant.

Response Example

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": 10,
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": 20,
        "security_groups": 45
    }
}
DELETE
/v1/{admin_tenant_id}/os-quota-sets/{tenant_id}

Delete quotas (v1)

Deletes quotas for a tenant so the quotas revert to default values.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
admin_tenant_id (Optional) path string The UUID of the administrative tenant.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Response Example


GET
/v1/{admin_tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Show quotas for user (v1)

Enables an admin user to show quotas for a tenant and user.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
admin_tenant_id (Optional) path string The UUID of the administrative tenant.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
user_id (Optional) path string The user ID. Specify in the URI as user_id={user_id}.

Response Parameters

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
reserved (Optional) body integer Reserved volume size. Visible only if you set the usage=true query parameter.
in_use (Optional) body string The in use data size. Visible only if you set the usage=true query parameter.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
instances body integer The number of instances that are allowed for each tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
id body string The UUID of the volume.
security_groups body integer The number of security groups that are allowed for each tenant.

Response Example

{
    "quota_set": {
        "cores": 20,
        "fixed_ips": -1,
        "floating_ips": 10,
        "id": "fake_tenant",
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 10,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": 20,
        "security_groups": 10
    }
}
POST
/v1/{admin_tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Update quotas for user (v1)

Updates quotas for a tenant and user.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
id body string The UUID of the volume.
instances body integer The number of instances that are allowed for each tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
security_groups body integer The number of security groups that are allowed for each tenant.
admin_tenant_id (Optional) path string The UUID of the administrative tenant.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
user_id (Optional) path string The user ID. Specify in the URI as user_id={user_id}.

Request Example

{
    "quota_set": {
        "force": true,
        "instances": 9
    }
}

Response Parameters

Name In Type Description
injected_file_content_bytes body integer The number of bytes of content that are allowed for each injected file.
metadata_items body integer The number of metadata items that are allowed for each instance.
reserved (Optional) body integer Reserved volume size. Visible only if you set the usage=true query parameter.
in_use (Optional) body string The in use data size. Visible only if you set the usage=true query parameter.
ram body integer The amount of instance RAM in megabytes that are allowed for each tenant.
floating_ips body integer The number of floating IP addresses that are allowed for each tenant.
key_pairs body integer The number of key pairs that are allowed for each user.
injected_file_path_bytes body integer The number of bytes that are allowed for each injected file path.
instances body integer The number of instances that are allowed for each tenant.
security_group_rules (Optional) body integer The number of rules that are allowed for each security group.
injected_files body integer The number of injected files that are allowed for each tenant.
quota_set body object A quota_set object.
cores body integer The number of instance cores that are allowed for each tenant.
fixed_ips body integer The number of fixed IP addresses that are allowed for each tenant. Must be equal to or greater than the number of allowed instances.
id body string The UUID of the volume.
security_groups body integer The number of security groups that are allowed for each tenant.

Response Example

{
    "quota_set": {
        "cores": 20,
        "floating_ips": 10,
        "fixed_ips": -1,
        "injected_file_content_bytes": 10240,
        "injected_file_path_bytes": 255,
        "injected_files": 5,
        "instances": 9,
        "key_pairs": 100,
        "metadata_items": 128,
        "ram": 51200,
        "security_group_rules": 20,
        "security_groups": 10
    }
}
DELETE
/v1/{admin_tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Delete quotas for user (v1)

Deletes quotas for a user so that the quotas revert to default values.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
admin_tenant_id (Optional) path string The UUID of the administrative tenant.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
user_id (Optional) path string The user ID. Specify in the URI as user_id={user_id}.

Response Example


Snapshots

Creates, lists, shows information for, and deletes snapshots. Shows and updates snapshot metadata.

GET
/v1/{tenant_id}/snapshots/{snapshot_id}

Show snapshot details (v1)

Shows details for a snapshot.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.

Response Example

{
    "snapshot": {
        "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "status": "available",
        "size": 30,
        "created_at": "2012-02-29T03:50:07Z"
    }
}
DELETE
/v1/{tenant_id}/snapshots/{snapshot_id}

Delete snapshot (v1)

Deletes a snapshot.

Normal response codes:202,

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
GET
/v1/{tenant_id}/snapshots/detail

List snapshots with details (v1)

Lists all snapshots, with details.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Response Example

{
    "snapshots": [
        {
            "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
            "display_name": "snap-001",
            "display_description": "Daily backup",
            "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "status": "available",
            "size": 30,
            "created_at": "2012-02-29T03:50:07Z",
            "metadata": {
                "contents": "junk"
            }
        },
        {
            "id": "e479997c-650b-40a4-9dfe-77655818b0d2",
            "display_name": "snap-002",
            "display_description": "Weekly backup",
            "volume_id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "status": "available",
            "size": 25,
            "created_at": "2012-03-19T01:52:47Z",
            "metadata": {}
        }
    ]
}
POST
/v1/{tenant_id}/snapshots

Create snapshot (v1)

Creates a snapshot.

Normal response codes:201

Request

Name In Type Description
snapshot body object A snapshot object.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Request Example

{
    "snapshot": {
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "force": true
    }
}
GET
/v1/{tenant_id}/snapshots

List snapshots (v1)

Lists all snapshots.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Response Example

{
    "snapshots": [
        {
            "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
            "display_name": "snap-001",
            "display_description": "Daily backup",
            "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "status": "available",
            "size": 30,
            "created_at": "2012-02-29T03:50:07Z",
            "metadata": {
                "contents": "junk"
            }
        },
        {
            "id": "e479997c-650b-40a4-9dfe-77655818b0d2",
            "display_name": "snap-002",
            "display_description": "Weekly backup",
            "volume_id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "status": "available",
            "size": 25,
            "created_at": "2012-03-19T01:52:47Z",
            "metadata": {}
        }
    ]
}
GET
/v1/{tenant_id}/snapshots/{snapshot_id}/metadata

Show snapshot metadata (v1)

Shows metadata for a snapshot.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.

Response Example

{
    "snapshot": {
        "status": "available",
        "os-extended-snapshot-attributes:progress": "0%",
        "description": null,
        "created_at": "2014-05-06T17:59:52.000000",
        "metadata": {
            "key": "v1"
        },
        "volume_id": "ebd80b99-bc3d-4154-9d28-5583baa80580",
        "os-extended-snapshot-attributes:project_id": "7e0105e19cd2466193729ef78b604f79",
        "size": 10,
        "id": "dfcd17fe-3b64-44ba-b95f-1c9c7109ef95",
        "name": "my-snapshot"
    }
}
PUT
/v1/{tenant_id}/snapshots/{snapshot_id}/metadata

Update snapshot metadata (v1)

Updates metadata for a snapshot.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
metadata (Optional) body object One or more metadata key and value pairs that are associated with the volume.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.

Request Example

{
    "metadata": {
        "key": "v1"
    }
}

Response Example

{
    "metadata": {
        "key": "v1"
    }
}

Volume types

Lists, creates, updates, shows information for, and deletes volume types.

GET
/v1/{tenant_id}/types

List volume types (v1)

Lists volume types.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Response Example

{
    "volume_types": [
        {
            "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "name": "vol-type-001",
            "extra_specs": {
                "capabilities": "gpu"
            }
        },
        {
            "id": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "name": "vol-type-002",
            "extra_specs": {}
        }
    ]
}
POST
/v1/{tenant_id}/types

Create volume type (v1)

Creates a volume type.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
name body string The name of the volume type.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Request Example

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

Response Parameters

Name In Type Description
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
name body string The name of the volume type.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

Response Example

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
PUT
/v1/{tenant_id}/types/{volume_type_id}

Update volume type (v1)

Updates a volume type.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
name body string The name of the volume type.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
volume_type_id (Optional) path string The UUID for an existing volume type.

Request Example

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

Response Parameters

Name In Type Description
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
name body string The name of the volume type.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

Response Example

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
PUT
/v1/{tenant_id}/types/{volume_type_id}

Update extra specs for a volume type (v1)

Updates the extra specifications for a volume type.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
name body string The name of the volume type.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
volume_type_id (Optional) path string The UUID for an existing volume type.

Request Example

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

Response Parameters

Name In Type Description
extra_specs body object A set of key and value pairs that contains the specifications for a volume type.
name body string The name of the volume type.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

Response Example

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
GET
/v1/{tenant_id}/types/{volume_type_id}

Show volume type details (v1)

Shows details for a volume type.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
volume_type_id (Optional) path string The UUID for an existing volume type.

Response Example

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
DELETE
/v1/{tenant_id}/types/{volume_type_id}

Delete volume type (v1)

Deletes a volume type.

Normal response codes: 202

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
volume_type_id (Optional) path string The UUID for an existing volume type.

API versions

Lists information about API versions.

GET
/v1

Show API v1 details

Shows Block Storage API v1 details.

Normal response codes: 200 Error response codes:203,

Request

Response Example

{
    "version": {
        "id": "v1.0",
        "links": [
            {
                "href": "http://23.253.211.234:8776/v1/",
                "rel": "self"
            },
            {
                "href": "http://docs.openstack.org/",
                "rel": "describedby",
                "type": "text/html"
            }
        ],
        "media-types": [
            {
                "base": "application/xml",
                "type": "application/vnd.openstack.volume+xml;version=1"
            },
            {
                "base": "application/json",
                "type": "application/vnd.openstack.volume+json;version=1"
            }
        ],
        "status": "DEPRECATED",
        "updated": "2014-06-28T12:20:21Z"
    }
}
GET
/

List API versions (v1)

Lists information about all Block Storage API versions.

Normal response codes: 300

Request

Response Example

{
    "versions": [
        {
            "id": "v1.0",
            "links": [
                {
                    "href": "http://23.253.211.234:8776/v1/",
                    "rel": "self"
                }
            ],
            "status": "DEPRECATED",
            "updated": "2014-06-28T12:20:21Z"
        },
        {
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.211.234:8776/v2/",
                    "rel": "self"
                }
            ],
            "status": "CURRENT",
            "updated": "2012-11-21T11:33:21Z"
        }
    ]
}

Volumes

The snapshot_id and source_volid parameters specify the ID of the snapshot or volume from which the volume originates. If the volume was not created from a snapshot or source volume, these values are null.

GET
/v1/{tenant_id}/volumes/detail

List volumes, with details (v1)

Lists all volumes, with details.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Response Parameters

Name In Type Description
migration_status body string The volume migration status.
attachments body array Instance attachment information. If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID. Otherwise, this list is empty.
links body array The volume links.
availability_zone (Optional) body string The availability zone.
encrypted body boolean If true, this volume is encrypted.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

replication_status body string The volume replication status.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
user_id (Optional) path string The user ID. Specify in the URI as user_id={user_id}.
metadata (Optional) body object One or more metadata key and value pairs that are associated with the volume.
status body string The volume status.
description (Optional) body string The volume description.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
consistencygroup_id (Optional) body string The UUID of the consistency group.
name body string The name of the volume type.
bootable body boolean Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
volumes body array A list of volume objects.

Response Example

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "status": "active",
            "size": 30,
            "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "metadata": {
                "contents": "junk"
            },
            "availability_zone": "us-east1",
            "snapshot_id": null,
            "attachments": [
                {
                    "attachment_id": "03987cd1-0ad5-40d1-9b2a-7cc48295d4fa",
                    "id": "47e9ecc5-4045-4ee3-9a4b-d859d546a0cf",
                    "volume_id": "6c80f8ac-e3e2-480c-8e6e-f1db92fe4bfe",
                    "server_id": "d1c4788b-9435-42e2-9b81-29f3be1cd01f",
                    "host_name": "mitaka",
                    "device": "/"
                }
            ],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "status": "active",
            "size": 25,
            "volume_type": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "metadata": {},
            "availability_zone": "us-east2",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}
POST
/v1/{tenant_id}/volumes

Create volume (v1)

Creates a volume.

Normal response codes: 201,

Request

Name In Type Description
size body integer The size of the volume, in gibibytes (GiB).
description (Optional) body string The volume description.
imageRef (Optional) body string The UUID of the image from which you want to create the volume. Required to create a bootable volume.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
availability_zone (Optional) body string The availability zone.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
name body string The name of the volume type.
volume body object A volume object.
consistencygroup_id (Optional) body string The UUID of the consistency group.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
OS-SCH-HNT:scheduler_hints (Optional) body object The dictionary of data to send to the scheduler.
source_replica (Optional) body string The UUID of the primary volume to clone.
metadata (Optional) body object One or more metadata key and value pairs that are associated with the volume.
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Request Example

{
    "volume": {
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1"
    },
    "OS-SCH-HNT:scheduler_hints": {
        "same_host": [
            "a0cf03a5-d921-4877-bb5c-86d26cf818e1",
            "8c19174f-4220-44f0-824a-cd1eeef10287"
        ]
    }
}

Response Parameters

Name In Type Description
description (Optional) body string The volume description.
imageRef (Optional) body string The UUID of the image from which you want to create the volume. Required to create a bootable volume.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

availability_zone (Optional) body string The availability zone.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
name body string The name of the volume type.
volume body object A volume object.
volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
size body integer The size of the volume, in gibibytes (GiB).
metadata (Optional) body object One or more metadata key and value pairs that are associated with the volume.
GET
/v1/{tenant_id}/volumes

List volumes (v1)

Lists all volumes.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.

Response Parameters

Name In Type Description
volumes body array A list of volume objects.
id body string The UUID of the volume.
links body array The volume links.
name body string The name of the volume type.

Response Example

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "status": "active",
            "size": 30,
            "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "metadata": {
                "contents": "junk"
            },
            "availability_zone": "us-east1",
            "snapshot_id": null,
            "attachments": [
                {
                    "attachment_id": "03987cd1-0ad5-40d1-9b2a-7cc48295d4fa",
                    "id": "47e9ecc5-4045-4ee3-9a4b-d859d546a0cf",
                    "volume_id": "6c80f8ac-e3e2-480c-8e6e-f1db92fe4bfe",
                    "server_id": "d1c4788b-9435-42e2-9b81-29f3be1cd01f",
                    "host_name": "mitaka",
                    "device": "/"
                }
            ],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "status": "active",
            "size": 25,
            "volume_type": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "metadata": {},
            "availability_zone": "us-east2",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}
GET
/v1/{tenant_id}/volumes/{volume_id}

Show volume details (v1)

Shows details for a volume.

Normal response codes: 200 Error response codes:

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
volume_id (Optional) path string The UUID of the volume.

Response Parameters

Name In Type Description
migration_status body string The volume migration status.
attachments body array Instance attachment information. If this volume is attached to a server instance, the attachments list includes the UUID of the attached server, an attachment UUID, the name of the attached host, if any, the volume UUID, the device, and the device UUID. Otherwise, this list is empty.
links body array The volume links.
availability_zone (Optional) body string The availability zone.
encrypted body boolean If true, this volume is encrypted.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

replication_status body string The volume replication status.
snapshot_id (Optional) body string To create a volume from an existing snapshot, specify the UUID of the volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
id body string The UUID of the volume.
size body integer The size of the volume, in gibibytes (GiB).
user_id (Optional) path string The user ID. Specify in the URI as user_id={user_id}.
metadata (Optional) body object One or more metadata key and value pairs that are associated with the volume.
status body string The volume status.
description (Optional) body string The volume description.
multiattach (Optional) body boolean To enable this volume to attach to more than one server, set this value to true. Default is false.
source_volid (Optional) body string The UUID of the source volume. The API creates a new volume with the same size as the source volume.
volume body object A volume object.
consistencygroup_id (Optional) body string The UUID of the consistency group.
name body string The name of the volume type.
bootable body boolean Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

volume_type (Optional) body string The volume type. To create an environment with multiple-storage back ends, you must specify a volume type. Block Storage volume back ends are spawned as children to cinder- volume, and they are keyed from a unique queue. They are named cinder- volume.HOST.BACKEND. For example, cinder- volume.ubuntu.lvmdriver. When a volume is created, the scheduler chooses an appropriate back end to handle the request based on the volume type. Default is None. For information about how to use volume types to create multiple- storage back ends, see Configure multiple-storage back ends.

Response Example

{
    "volume": {
        "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "status": "active",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1",
        "bootable": "false",
        "snapshot_id": null,
        "attachments": [
            {
                "attachment_id": "03987cd1-0ad5-40d1-9b2a-7cc48295d4fa",
                "id": "47e9ecc5-4045-4ee3-9a4b-d859d546a0cf",
                "volume_id": "6c80f8ac-e3e2-480c-8e6e-f1db92fe4bfe",
                "server_id": "d1c4788b-9435-42e2-9b81-29f3be1cd01f",
                "host_name": "mitaka",
                "device": "/"
            }
        ],
        "created_at": "2012-02-14T20:53:07Z"
    }
}
DELETE
/v1/{tenant_id}/volumes/{volume_id}

Delete volume (v1)

Deletes a volume.

Normal response codes: 202,

Request

Name In Type Description
tenant_id (Optional) path string The UUID of the tenant in a multi-tenancy cloud.
volume_id (Optional) path string The UUID of the volume.
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.