Volume transfer#

You can transfer a volume from one owner to another by using the volumes transfer methods. The volume donor, or original owner, creates a transfer request and sends the created transfer_id and auth_key to the volume recipient. The volume recipient, or new owner, accepts the transfer by using the ID and key.

Note

The procedure for volume transfer is intended for tenants (both the volume donor and recipient) within the same cloud.

Use cases include:

  • Create a custom bootable volume or a volume with a large data set and transfer it to a customer.

Create a volume transfer#

POST /v1/{tenant_id}/os-volume-transfer

This operation creates a volume transfer.

Request parameters#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

The request has the following body parameters.

Name

Type

Description

transfer

String (Required)

A representation of a volume transfer in the creation process.

transfer.volume_id

UUID (Required)

The UUID of the volume.

transfer.name

String

The volume transfer name.

Request example#

The following JSON example creates a volume transfer.

{
     "transfer": {
         "volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
         "name": "first volume"
     }
}

Response parameters#

The response has the following body parameters.

Name

Type

Description

transfer

String

A representation of a volume transfer in the creation process.

transfer.id

UUID

The UUID of the volume transfer.

transfer.created_at

Datetime

The date and time when the volume was created.

transfer.name

String

The volume transfer name.

transfer.volume_id

UUID

The UUID of the volume.

transfer.auth_key

String

The authentication key for the volume transfer.

transfer.links

List

The links for the volume transfer.

Response example#

The following example shows the JSON response for creating a volume transfer.

{
    "transfer": {
        "id": "1a7059f5-8ed7-45b7-8d05-2811e5d09f24",
        "created_at": "2015-02-25T03:56:53.081642",
        "name": "first volume",
        "volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
        "auth_key": "9266c59563c84664",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/3",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/3",
                "rel": "bookmark"
            }
        ]
    }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

202

Accepted

The request has been accepted for processing.

Retrieve the volume transfers#

GET /v1/{tenant_id}/os-volume-transfer

This operation retrieves the volume transfers for the specified tenant_id.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

This operation does not accept a request body.

Response parameters#

The response has the following body parameters.

Name

Type

Description

transfer

String

A representation of a volume transfer in the creation process.

transfer.id

UUID

The UUID of the volume transfer.

transfer.name

String

The volume transfer name.

transfer.volume_id

UUID

The UUID of the volume.

transfer.links

List

The links for the volume transfer.

Response example#

The following example shows the JSON response for retrieving the volume transfers for the specified tenant_id.

{
    "transfers": [
        {
            "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
            "name": "first volume transfer",
            "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/1",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/1",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "id": "f26c0dee-d20d-4e80-8dee-a8d91b9742a1",
            "name": "second volume transfer",
            "volume_id": "673db275-379f-41af-8371-e1652132b4c1",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/2",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                 "rel": "bookmark"
                }
            ]
        }
    ]
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success

Retrieve the volume transfers (detailed)#

GET /v1/{tenant_id}/os-volume-transfer/detail

This operation retrieves detailed information for the volume transfers for the specified tenant_id.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

This operation does not accept a request body.

Response parameters#

The response has the following body parameters.

Name

Type

Description

transfer

String

A representation of a volume transfer in the creation process.

transfer.id

UUID

The UUID of the volume transfer.

transfer.created_at

Datetime

The date and time when the volume was created.

transfer.name

String

The volume transfer name.

transfer.volume_id

UUID

The UUID of the volume.

transfer.links

List

The links for the volume transfer.

Response example#

The following example shows the JSON response for retrieving detailed information for the volume transfers for a specified tenant_id.

{
    "transfers": [
        {
            "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
            "created_at": "2015-02-25T03:56:53.081642",
            "name": "first volume transfer",
            "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/1",
                    "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/1",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "id": "f26c0dee-d20d-4e80-8dee-a8d91b9742a1",
            "created_at": "2015-03-25T03:56:53.081642",
            "name": "second volume transfer",
            "volume_id": "673db275-379f-41af-8371-e1652132b4c1",
            "links": [
                {
                    "href": "http://localhost/v2/firstproject/volumes/2",
                 "rel": "self"
                },
                {
                    "href": "http://localhost/firstproject/volumes/2",
                 "rel": "bookmark"
                }
            ]
        }
    ]
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success

Retrieve a volume transfer (detailed)#

GET /v1/{tenant_id}/os-volume-transfer/​{transfer_id}​

This operation retrieves details for a volume transfer specified by transfer_id.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

{transfer_id}

String

The unique identifier for a volume transfer.

This operation does not accept a request body.

Response parameters#

The response has the following body parameters.

Name

Type

Description

transfer

String

A representation of a volume transfer in the creation process.

transfer.id

UUID

The UUID of the volume transfer.

transfer.created_at

Datetime

The date and time when the volume was created.

transfer.name

String

The volume transfer name.

transfer.volume_id

UUID

The UUID of the volume.

transfer.links

List

The links for the volume transfer.

Response example#

The following example shows the JSON response for retrieving details for a specified volume transfer.

{
    "transfer": {
        "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
        "created_at": "2015-02-25T03:56:53.081642",
        "name": "first volume transfer",
        "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/1",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/1",
                "rel": "bookmark"
            }
        ]
    }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

200

OK

Success

Delete a volume transfer#

DELETE /v1/{tenant_id}/os-volume-transfer/​{transfer_id}​

This operation deletes a volume transfer specified by transfer_id.

Request#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

{transfer_id}

String

The unique identifier of a volume transfer.

This operation does not accept a request body.

Response#

This operation does not return a response body.

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

202

Accepted

The request has been accepted for processing.

Accept a volume transfer#

POST /v1/{tenant_id}/os-volume-transfer/​{transfer_id}​/accept

This operation accepts a volume transfer.

Request parameters#

The request has the following URI parameters.

Name

Type

Description

{tenant_id}

String

The unique identifier of the tenant or account.

{transfer_id}

String

The unique identifier of a volume transfer.

The request has the following body parameters.

Name

Type

Description

accept

String (Required)

A partial representation of a volume transfer acceptance.

accept.auth_key

String (Required)

The authentication key for the volume transfer.

Request example#

The following example accepts a volume transfer.

{
    "accept": {
        "auth_key": "9266c59563c84664"
    }
}

Response parameters#

The response has the following body parameters.

Name

Type

Description

transfer

String

A representation of a volume transfer in the creation process.

transfer.id

UUID

The UUID of the volume transfer.

transfer.name

String

The volume transfer name.

transfer.volume_id

UUID

The UUID of the volume.

transfer.links

List

The links for the volume transfer.

Response example#

The following example shows the JSON response for accepting a volume transfer.

{
    "transfer": {
        "id": "cac5c677-73a9-4288-bb9c-b2ebfb547377",
        "name": "first volume transfer",
        "volume_id": "894623a6-e901-4312-aa06-4275e6321cce",
        "links": [
            {
                "href": "http://localhost/v2/firstproject/volumes/1",
                "rel": "self"
            },
            {
                "href": "http://localhost/firstproject/volumes/1",
                "rel": "bookmark"
            }
        ]
    }
}

Response codes#

This operation can have the following response codes.

Response Code

Name

Description

202

Accepted

The request has been accepted for processing.