Difference between revisions of "Rackspace API/Cloud Images"

Revision as of 08:32, 15 December 2014

HOWTO: share images between Rackspace Cloud accounts

In this section, I will show you how to share a Cloud Image from one Rackspace account to another. The account doing the sharing will be called the "Producer" and the account receiving the share will be called the "Consumer". Note that the image being shared by the Producer can only be used by the Consumer to build Cloud Servers in the same region/data centre as the Producer's image was created in (e.g., DFW, ORD, SYD, etc.).

Export environment variables

These are the shell variables we will use in all the subsequent steps (i.e., in our API calls):

$ TOKEN_PRODUCER=<Token_of_Producer>
$ TOKEN_CONSUMER=<Token_of_Consumer>
$ ACCOUNT_PRODUCER=000001
$ ACCOUNT_CONSUMER=000002
$ REGION=dfw
$ ENDPOINT_SERVERS_PRODUCER=https://${REGION}.servers.api.rackspacecloud.com/v2/${ACCOUNT_PRODUCER}
$ ENDPOINT_SERVERS_CONSUMER=https://${REGION}.servers.api.rackspacecloud.com/v2/${ACCOUNT_CONSUMER}
$ ENDPOINT_IMAGES_PRODUCER=https://${REGION}.images.api.rackspacecloud.com/v2/${ACCOUNT_PRODUCER}
$ ENDPOINT_IMAGES_CONSUMER=https://${REGION}.images.api.rackspacecloud.com/v2/${ACCOUNT_CONSUMER}

$ IMAGE_NAME_PRODUCER="my-saved-image-name"

Producer: Gather information on image to be shared

• Get basic information on Producer's saved image (i.e., "my-saved-image-name"):

$ curl -H "X-Auth-Token: $TOKEN_PRODUCER" -H "Content-Type: application/json" \
       "${ENDPOINT_SERVERS_PRODUCER}/images?type=SNAPSHOT&name=${IMAGE_NAME_PRODUCER}" |\
       python -mjson.tool
$ IMAGE_ID_PRODUCER=fffff  # From "id" in above output

• Get detailed information on Producer's saved image:

$ curl -s -H "X-Auth-Token: $TOKEN_PRODUCER" -H "Content-Type: application/json" \
       "${ENDPOINT_SERVERS_PRODUCER}/images/${IMAGE_ID_PRODUCER}" |\
       python -mjson.tool

• Get all metadata associated with Producer's saved image:

$ curl -s -H "X-Auth-Token: $TOKEN_PRODUCER" -H "Content-Type: application/json" \
       "${ENDPOINT_IMAGES_PRODUCER}/images/${IMAGE_ID_PRODUCER}" |\
       python -mjson.tool

• Get the members (aka "tenant_id"/account number) associated with Producer's saved image (if the image has never been shared, the "members" value will be empty):

$ curl -s -H "X-Auth-Token: $TOKEN_PRODUCER" -H "Content-Type: application/json" \
       "${ENDPOINT_IMAGES_PRODUCER}/images/${IMAGE_ID_PRODUCER}/members" |\
       python -mjson.tool
{
    "members": [],
    "schema": "/v2/schemas/members"
}

Producer: Share the image in question

$ curl -sXPOST -H "Content-Type: application/json" \
       -H "X-Auth-Token: $TOKEN_PRODUCER" \
       "${ENDPOINT_IMAGES_PRODUCER}/images/${IMAGE_ID_PRODUCER}/members" \
       -d "{\"member\":\"$ACCOUNT_CONSUMER\"}" |\
       python -mjson.tool

The image has now been shared to the consumer. However, the status of the share will be in "pending", as the API is waiting on the consumer to accept the shared image.

Consumer: Accept the shared image

• Get shared image details

$ curl -H "X-Auth-Token: $TOKEN_CONSUMER" -H "Content-Type: application/json" \
       "${ENDPOINT_SERVERS_CONSUMER}/images?type=SNAPSHOT&name=${IMAGE_NAME_PRODUCER}" |\
       python -mjson.tool
$ #~AND~
$ curl -s -H "X-Auth-Token: $TOKEN_CONSUMER" -H "Content-Type: application/json" \
       "${ENDPOINT_IMAGES_CONSUMER}/images/${IMAGE_ID_PRODUCER}" |\
       python -mjson.tool

• Get the status of the shared image:

$ curl -s -H "X-Auth-Token: $TOKEN_CONSUMER" -H "Content-Type: application/json" \
       "${ENDPOINT_IMAGES_CONSUMER}/images/${IMAGE_ID_PRODUCER}/members" |\
       python -mjson.tool

From the output of the above command, the image status will be "pending". When a producer shares an image to another account (i.e., the consumer's account), the consumer must first accept the share before the shared image will be visible in the Cloud Control Panel (under "Saved Images").

• Accept the shared image:

$ curl -XPUT -H "X-Auth-Token: $TOKEN_CONSUMER" -H "Content-Type: application/json" \
       "${ENDPOINT_IMAGES_CONSUMER}/images/${IMAGE_ID_PRODUCER}/members/${ACCOUNT_CONSUMER}" \
       -d '{"status":"accepted"}'

The consumer is now free to use that shared image to build new Cloud Servers on their account.

• Reject the shared image:

$ curl -XPUT -H "X-Auth-Token: $TOKEN_CONSUMER" -H "Content-Type: application/json" \
       "${ENDPOINT_IMAGES_CONSUMER}/images/${IMAGE_ID_PRODUCER}/members/${ACCOUNT_CONSUMER}" \
       -d '{"status":"rejected"}'

Note that the consumer can not delete this shared image from their account, as they are simply accepted a share and the image is not stored on their account (nor does the consumer incur any Cloud Images charges for this shared image). If the consumer tries to delete the shared image, they will get a "403 Forbidden You are not permitted to delete this image". If the consumer no longer wishes to use or see this image on their account, they can simply reject the image at any point (see last command).

Producer: Delete consumer from shared image members

If the producer wishes to remove the consumer from a given image's "members" (i.e., those accounts the image has been shared with), the producer must simply delete the consumer's account (aka "member_id") from the shared image and the consumer will no longer have access to that shared image:

$ curl -XDELETE -H "Content-Type: application/json" \
       -H "X-Auth-Token: $TOKEN_PRODUCER" \
       "${ENDPOINT_IMAGES_PRODUCER}/images/${IMAGE_ID_PRODUCER}/members/${ACCOUNT_CONSUMER}"

See also

• Rackspace API

External links

• Cloud Images Frequently Asked Questions