Quickstart for Cloud Images#

Cloud Images are filesystem snapshots of your Cloud Servers. You can use them to duplicate Cloud Servers, and even share images across multiple Rackspace accounts.

Concepts#

Image

A bundle of files that you use to create or rebuild a server. There are pre-defined images, but you can also create your own custom images from servers that you’ve launched.

  • A standard image is a Rackspace provided image, like Fedora 20 (Heisenbug) (PVHVM)

  • A nonstandard image is one that is imported or exported, end-of-life, shared, not standard for your account service level, or not included in the subset of images provided for RackConnect customers.

Image Member

A user who has been granted access to an image, identified by Rackspace account number.

Authentication#

To use this service you have to authenticate first. To do this, you will need your Rackspace username and API key. Your username is the one you use to login to the Cloud Control Panel at http://mycloud.rackspace.com/.

To find your API key, use the instructions in View and reset your API key.

You can specify a default region. Here is a list of available regions:

  • DFW (Dallas-Fort Worth, TX, US)

  • HKG (Hong Kong, China)

  • IAD (Blacksburg, VA, US)

  • LON (London, England)

  • SYD (Sydney, Australia)

Some users have access to another region in ORD (Chicago, IL). New users will not have this region.

Once you have these pieces of information, you can pass them into the SDK by replacing {username}, {apiKey}, and {region} with your info:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

require 'vendor/autoload.php';

use OpenCloud\Rackspace;

$client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
    'username' => '{username}',
    'apiKey'   => '{apiKey}'
));

import pyrax
pyrax.set_credentials("{username}", "{apiKey}")

# Not currently supported by this SDK

# {username}, {apiKey} below are placeholders, do not enclose '{}' when you replace them with actual credentials.

curl -s -X POST https://identity.api.rackspacecloud.com/v2.0/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "RAX-KSKEY:apiKeyCredentials": {
        "username": "{username}",
        "apiKey": "{apiKey}"
      }
    }
  }' | python -m json.tool

# From the resulting json, set three environment variables: TOKEN, ENDPOINT, and CDN_ENDPOINT.

export TOKEN="{tokenId}"
export ENDPOINT="{publicUrl}" # For the Cloud Images service

Image operations#

List available images#

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

$service = $client->imageService('cloudImages', '{regionId}');
$images  = $service->listImages();

foreach ($images as $image) {
   /** @param $image OpenCloud\Image\Resource\Image */
}

all_images = imgs.list()

# Not currently supported by this SDK

curl -s $ENDPOINT/images -H "X-Auth-Token: $TOKEN" | python -m json.tool

Get image details#

Each image can have arbitrary metadata associated with it, which you can use to share information about the image or to aid filtering and sorting.

Once you know the ID of an image that you care about, you can see its additional information and metadata:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

$image   = $service->getImage('{imageId}');
$imageId = $image['id'];

img = imgs.get("{imageId}")

# Not currently supported by this SDK

curl -s $ENDPOINT/images/{imageId} \
  -H "X-Auth-Token: $TOKEN" | python -m json.tool

Update an image#

You can also update the metadata for a specific image:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

$image->update(array(
    'someAttribute'    => 'someValue',
    'anotherAttribute' => 'anotherValue'
));

# `valueDict` is a dictionary of key/value pairs, where the key is the
# attribute to be updated, and the value is its new value.
imgs.update("{imageId}", {"someAttribute": "someValue",
      "anotherAttribute": "anotherValue"})

# Not currently supported by this SDK

curl -s $ENDPOINT/images/{imageId} -X PATCH \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/openstack-images-v2.1-json-patch" \
  -H "Accent: application/json" \
  -d '[
    {
      "op": "add",
      "path": "/someAttribute",
      "value": "someValue"
    },
    {
      "op": "add",
      "path": "/anotherAttribute",
      "value": "anotherValue"
    }
  ]' | python -m json.tool

Import or export an image#

Images can be imported and exported to and from Cloud Files. This can be useful for moving images between regions.

To export an image to Cloud Files:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported

# Create the export task
task = imgs.export_task("{imageId}", "receivingSwiftContainer")

# Wait for the task to complete
pyrax.utils.wait_for_build(task, verbose=True,
      desired=["success", "failure"])

# The task's `status` attribute will be either "success" or "failure".
# In the case of a failure, its `message` attribute will explain why.

# Not currently supported by this SDK

curl -s -X POST $ENDPOINT/tasks \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "type": "export",
    "input": {
      "image_uuid": "{imageId}",
      "receiving_swift_container": "receivingSwiftContainer"
    }
  }' | python -m json.tool

To import an image from Cloud Files:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported

# Create the import task. This is the most basic format for the call.
task = imgs.import_task("My Image", "exportSwiftContainer")

# You can optionally specify the format (default=VHD), and give the imported
# image a new name.
# task = imgs.import_task("My Image", "exportSwiftContainer",
#      img_format="someOddFormat", img_name = "My New Image"))

# Wait for the task to complete
pyrax.utils.wait_for_build(task, verbose=True,
      desired=["success", "failure"])

# The task's `status` attribute will be either "success" or "failure".
# In the case of a failure, its `message` attribute will explain why.

# Not currently supported by this SDK

curl -s $ENDPOINT/tasks -X POST \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "type": "import",
    "input": {
      "image_properties": {
        "name": "My New Image"
      },
      "import_from": "exportSwiftContainer/my-image.vhd"
    }
  }' | python -m json.tool

Share an image#

Rackspace Cloud Images enables you and others to share custom images. You accomplish this by manipulating image members.

The operations that you can execute on a specific image depend on your role. If you are an image producer, you can’t update an image member for an image you’re sharing with someone else. Similarly, if you’re an image consumer, you can’t create additional image members for someone else’s image.

First, the image producer initiates the sharing process by adding a member to the image.

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

$image->createMember('{tenantId}');

# Call the `add_image_member()` method, passing in the ID of the image
# and the Rackspace account number of the member to add.
member = imgs.add_image_member("{imageId}", "{memberId}")

# Not currently supported by this SDK

# Use the prospective image consumer's Rackspace account number for {memberId}.

curl -s -X POST $ENDPOINT/images/{imageId}/members \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "member": "{memberId}" }' | python -m json.tool

The image does not automatically appear in the images list for the consuming user. Instead, the consumer must explicitly accept or reject the image member.

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

use OpenCloud\Images\Enum\MemberStatus;

/** @param $member OpenCloud\Image\Resource\Member */
$member = $image->getMember('{tenantId}');
$member->updateStatus(MemberStatus::ACCEPTED);

# This needs to be called by the member with whom the image is being shared.
# Valid values for `status` are:
#    pending
#    accepted
#    rejected
# Any other value will result in an InvalidImageMemberStatus exception
# being raised.

imgs.update_image_member("{imageId}", "accepted")

# Not currently supported by this SDK

curl -s -X PUT $ENDPOINT/images/{imageId}/members/{memberId} \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "status": "accepted" }' | python -m json.tool

To check on the status of these transactions, either party can view the image member’s details:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

/** @param $member OpenCloud\Image\Resource\Member */
$member = $image->getMember('{tenantId}');

# {projectId} is the account ID of the member.
member = imgs.get_image_member("{imageId}", "{projectId}")

# Not currently supported by this SDK

curl -s $ENDPOINT/images/{imageId}/members/{memberId} \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json" | python -m json.tool

Both users can also list all of the members for a given image:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

$members = $image->listMembers();

foreach ($members as $member) {
    /** @param $member OpenCloud\Image\Resource\Member */
}

members = imgs.list_image_members("{imageId}")

# Not currently supported by this SDK

curl -s $ENDPOINT/images/{imageId}/members \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json" | python -m json.tool

If you’re an image producer and you want to unshare an image from another user, you can delete the image member:

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

// Not currently supported by this SDK

$image->deleteMember('{tenantId}');

# Use the Rackspace account number of the user to remove as {memberId}.
imgs.delete_image_member("{imageId}", "{memberId}")

# Not currently supported by this SDK

curl -i -X DELETE $ENDPOINT/images/{imageId}/members/{memberId} \
    -H "X-Auth-Token: $TOKEN"

More information#

This quickstart is intentionally brief, demonstrating only a few basic operations. To learn more about interacting with Rackspace cloud services, explore the following sites: