• Buy Now
    • Rackspace Cloud
    • Email & Apps
    • Fanatical Support for AWS
    • Managed Google Cloud Platform
    • Office 365
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Cloud Office Control Panel
  • Rackspace Logo
  • Developer Home
  • Developer Documentation
  • Blogs ▼
    • Technical Blog
    • Rackspace Blog
    • Solve: Thought Leadership
  • Support Documentation

Developer Docs


Let’s Build Something Powerful Together!

End-to-End Multicloud Solutions.   Solving Together.™   Learn more at Rackspace.com

Submit an issue
  • Cloud Images 2.0
  • Getting started
    • Get your credentials
    • Send API requests to Rackspace Cloud Images
      • Convert cURL examples to run on Windows
    • Authenticate to the Rackspace Cloud
      • Send an authentication request
      • Review the authentication response
      • Configure environment variables
    • Concepts
      • Images
        • Standard images
        • Nonstandard images
      • Image entities
      • Image identifiers
      • Image properties
      • Image sharing
        • Sample workflow for image sharing, after image creation
      • Asynchronous tasks
        • High-level process for importing an image
        • High-level process for exporting an image
      • Statuses
        • Image statuses
        • Task statuses
        • Image member statuses
      • HTTP PATCH method
        • Restricted JSON pointers
        • Using the HTTP PATCH method
        • HTTP PATCH add operation
        • HTTP PATCH remove operation
        • HTTP PATCH replace operation
    • Use images
      • Listing images
      • Getting details for an image
      • Updating an image
      • Importing an image by using tasks
      • Exporting an image by using tasks
      • Getting details for a task
    • Share images
      • Creating an image member
      • Listing image members
      • Getting image member details
      • Updating an image member
      • Deleting an image member
  • General API information
    • Service access endpoints
    • Request and response types
      • Media Types
      • JSON Schemas
    • Paginated collections
    • Date and time format
    • Role-based access control (RBAC)
      • Assigning roles to account users
      • Roles available for Cloud Images
      • Multiproduct global roles and permissions
      • Resolving conflicts between RBAC multiproduct and product-specific roles
      • RBAC permissions cross-reference to Cloud Images API operations
  • API reference
    • Images
      • List images
        • Request
        • Response
      • Get image details
        • Request
        • Response
      • Update image
        • Request
        • Response
      • Delete image
        • Request
        • Response
    • Image sharing
      • List image members
        • Request
        • Response
      • Get image member details
        • Request
        • Response
      • Create image member
        • Request
        • Response
      • Delete image member
        • Request
        • Response
      • Update image member
        • Request
        • Response
    • Image tag
      • Add image tag
        • Request
        • Response
      • Delete image tag
        • Request
        • Response
    • Image task
      • List tasks
        • Request
        • Response
      • Get task details
        • Request
        • Response
      • Task to import image
        • Request
        • Response
      • Task to export image
        • Request
        • Response
    • JSON schemas
      • Get images schema
        • Request
        • Response
      • Get image schema
        • Request
        • Response
      • Get image members schema
        • Request
        • Response
      • Get image member schema
        • Request
        • Response
      • Get task schema
        • Request
        • Response
      • Get tasks schema
        • Request
        • Response
  • Glossary
  • Release Notes
    • API v2.0 release, September 9, 2013
      • What's new
      • Resolved issues
      • Known issues
  • Service updates
  • Additional resources
  • Disclaimer

Use images#

The Cloud Images service provides basic operations for managing images, such as listing and updating images. You can also use tasks to import images to and export images from your Cloud Files account. To learn more about the fundamentals of image tasks, see Asynchronous tasks.

To help you get started exploring Cloud Images, the following sections show some basic image operations with cURL examples.

Before running the examples, review the Cloud Images concepts.

Note

These examples use the $API_ENDPOINT and $AUTH_TOKEN environment variables to specify the API endpoint and authentication token values for accessing the service. Make sure you configure these variables before running the code samples.

Listing images#

To find out what images are available, list them.

  1. Issue the following cURL command.

    cURL list images request

    curl -s $API_ENDPOINT/v2/images -H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool
    

    Options:

    • -s: Runs the command in silent mode.
    • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
    • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

    The command returns an array of images. The details for the Ubuntu 12.04 image within the array are shown in following example, with other images removed for brevity.

    List images response

    {
       "images":
       [
          {
            "auto_disk_config": "disabled",
            "cache_in_nova": "True",
            "checksum": "acd9be13a17af33ec8f66ac5b1afc44a",
            "com.rackspace__1__build_core": "1",
            "com.rackspace__1__build_managed": "1",
            "com.rackspace__1__build_rackconnect": "1",
            "com.rackspace__1__options": "0",
            "com.rackspace__1__platform_target": "PublicCloud",
            "com.rackspace__1__release_build_date": "2014-03-19_10-50-10",
            "com.rackspace__1__release_id": "1003",
            "com.rackspace__1__release_version": "3",
            "com.rackspace__1__source": "kickstart",
            "com.rackspace__1__visible_core": "1",
            "com.rackspace__1__visible_managed": "0",
            "com.rackspace__1__visible_rackconnect": "1",
            "container_format": "ovf",
            "created_at": "2014-03-19T16:28:33Z",
            "disk_format": "vhd",
            "file": "/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2/file",
            "id": "c9c7732f-5129-4930-a835-3781255fb1e2",
            "image_type": "base",
            "min_disk": 20,
            "min_ram": 512,
            "name": "Ubuntu 12.04 LTS (Precise Pangolin) (PVHVM)",
            "org.openstack__1__architecture": "x64",
            "org.openstack__1__os_distro": "com.ubuntu",
            "org.openstack__1__os_version": "12.04",
            "os_distro": "ubuntu",
            "os_type": "linux",
            "protected": false,
            "schema": "/v2/schemas/image",
            "self": "/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2",
            "size": 647449489,
            "status": "active",
            "tags": [],
            "updated_at": "2014-03-26T21:44:54Z",
            "visibility": "public",
            "vm_mode": "hvm"
         }
       ],
       "next": "/v2/images?marker=c9c7732f-5129-4930-a835-3781255fb1e2",
       "schema": "/v2/schemas/images"
    }
    
  2. Copy the image ID of the image that you want to use. Find the image ID in the id field of the output. In this example, the id of the Ubuntu 12.04 image is c9c7732f-5129-4930-a835-3781255fb1e2.

If you need to see any additional details about an image, get the details for that image.

Getting details for an image#

Issue the following cURL command to get details for the Ubuntu 12.04 image, using an image ID that you got from the List images step.

cURL get details for an image request

curl -s $API_ENDPOINT/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2 \
-H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool

Options:

  • -s: Runs the command in silent mode.
  • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Get details for an image with cURL response

{
   "auto_disk_config": "disabled",
   "cache_in_nova": "True",
   "checksum": "acd9be13a17af33ec8f66ac5b1afc44a",
   "com.rackspace__1__build_core": "1",
   "com.rackspace__1__build_managed": "1",
   "com.rackspace__1__build_rackconnect": "1",
   "com.rackspace__1__options": "0",
   "com.rackspace__1__platform_target": "PublicCloud",
   "com.rackspace__1__release_build_date": "2014-03-19_10-50-10",
   "com.rackspace__1__release_id": "1003",
   "com.rackspace__1__release_version": "3",
   "com.rackspace__1__source": "kickstart",
   "com.rackspace__1__visible_core": "1",
   "com.rackspace__1__visible_managed": "0",
   "com.rackspace__1__visible_rackconnect": "1",
   "container_format": "ovf",
   "created_at": "2014-03-19T16:28:33Z",
   "disk_format": "vhd",
   "file": "/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2/file",
   "id": "c9c7732f-5129-4930-a835-3781255fb1e2",
   "image_type": "base",
   "min_disk": 20,
   "min_ram": 512,
   "name": "Ubuntu 12.04 LTS (Precise Pangolin) (PVHVM)",
   "org.openstack__1__architecture": "x64",
   "org.openstack__1__os_distro": "com.ubuntu",
   "org.openstack__1__os_version": "12.04",
   "os_distro": "ubuntu",
   "os_type": "linux",
   "protected": false,
   "schema": "/v2/schemas/image",
   "self": "/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2",
   "size": 647449489,
   "status": "active",
   "tags": [],
   "updated_at": "2014-03-26T21:44:54Z",
   "visibility": "public",
   "vm_mode": "hvm"
}

Updating an image#

If you need to change certain details about an image, such as adding, removing, or modifying image properties, you can update that image. For more information about how to update images by using the HTTP PATCH method and how to use the request body parameters (op, path, and value), see HTTP PATCH method. For more information about which properties can be updated, see Update image.

Issue the following cURL command to update an image. In this example, you are changing the name of image c9c7732f-5129-4930-a835-3781255fb1e2 from Ubuntu 12.04 LTS (Precise Pangolin) (PVHVM) to My Favorite Ubuntu 12.04.

cURL update an image request

curl -s $API_ENDPOINT/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2 \
-X PATCH \
-d'{{"op": "replace", "path": "/name", "value": "My Favorite Ubuntu 12.04"}}' \
-H "Content-Type: application/json" -H "X-Auth-Token: $AUTH_TOKEN" \
-H "Accept: application/openstack-images-v2.1-json-patch" |python -m json.tool

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.
  • -s: Runs the command in silent mode.
  • -H: Specified header information. In this case, it provides the content type, the authentication token, and the special format for the response body (application/openstack-images-v2.1-json-patch instead of application/json). If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable. To learn more about the response body format, see HTTP PATCH method.
  • -d: Specifies the JSON request body.
  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Update an image response

{
   "id":"c9c7732f-5129-4930-a835-3781255fb1e2",
   "name":"My Favorite Ubuntu 12.04",
   "status":"queued",
   "visibility":"public",
   "tags": [],
   "created_at":"2012-08-11T17:15:52Z",
   "updated_at":"2012-08-11T17:15:52Z",
   "self":"/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2",
   "file":"/v2/images/c9c7732f-5129-4930-a835-3781255fb1e2/file",
   "schema":"/v2/schemas/image"
}

Importing an image by using tasks#

To import an image to the Cloud Images service so that it is available to use and to share, create an import task. For more information about image tasks, see Asynchronous tasks.

  1. Issue the following cURL command to create a task to import an image. In this example, the source file for the my-excellent-image.vhd image, is in the exports directory on your Cloud Files account.

    cURL import an image request

    curl -s $API_ENDPOINT/v2/tasks \
    -X POST \
    -d '{"type": "import","input":{"image_properties": {"name": "My excellent custom image"},"import_from": "exports/my-excellent-image.vhd"}}' \
    -H "Content-Type: application/json" -H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool
    

    Options:

    • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.
    • -s: Runs the command in silent mode.
    • -H: Specified header information. In this case, it provides the content type and the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
    • -d: Specifies the JSON request body.
    • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

    Import an image response

    {
        "created_at": "2014-02-26T02:58:46Z",
        "id": "fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
        "input": {
            "image_properties": {
                "name": "My excellent custom image"
            },
            "import_from": "exports/my-excellent-image.vhd"
        },
        "message": "None",
        "owner": "00000123",
        "schema": "/v2/schemas/task",
        "self": "/v2/tasks/fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
        "status": "pending",
        "type": "import",
        "updated_at": "2014-02-26T02:58:46Z"
    }
    
  2. Note the task ID in the id parameter (in this example, fc29a67c-ad76-49bc-a317-a5f38dcb44c0), so you can poll the status of the task by using the instructions in Get details for a task until the task succeeds or fails.

Exporting an image by using tasks#

To export an image from the Cloud Images service so that you can store a copy offline, create an export task. For more information about image tasks, see Asynchronous tasks.

  1. Issue the following cURL command to create a task to export the image. In this example, the image ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6 is exported to the exports directory on your Cloud Files account.

cURL export an image with cURL request

curl -s $API_ENDPOINT/v2/tasks \
-X POST \
-d '{"type": "export","input":{"image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6","receiving_swift_container": "exports"}}' \
-H "Content-Type: application/json" -H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.
  • -s: Runs the command in silent mode.
  • -H: Specified header information. In this case, it provides the content type and the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
  • -d: Specifies the JSON request body.
  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Export an image with cURL response

{
    "created_at": "2014-02-26T02:01:13Z",
    "id": "7bdc8ede-9098-4d79-9477-697f586cb333",
    "input":{
        "image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6",
        "receiving_swift_container": "exports"
    },
    "message": "None",
    "owner": "00000123",
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/7bdc8ede-9098-4d79-9477-697f586cb333",
    "status": "pending",
    "type": "export",
    "updated_at": "2014-02-26T02:01:13Z"
}
  1. Note the task ID in the id parameter (in this example, 7bdc8ede-9098-4d79-9477-697f586cb333), so you can poll the status of the task by using the instructions in Get details for a task until the task succeeds or fails.

Getting details for a task#

To find when an import or export task finishes and whether it worked, get the details for that task.

  1. Issue the following cURL command to get details for an import task, by using the task ID that you got from importing or exporting an image. In this example, you poll task fc29a67c-ad76-49bc-a317-a5f38dcb44c0 and get a status of pending. If you continue polling, you will eventually get a status of success or failure.

    cURL get details for a task request

    curl -s $API_ENDPOINT/v2/tasks/fc29a67c-ad76-49bc-a317-a5f38dcb44c0  \
    -H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool
    

    Options:

    • -s: Runs the command in silent mode.
    • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
    • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

    Get details for a task response (pending)

    {
        "created_at": "2014-02-26T02:58:46Z",
        "id": "fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
        "input": {
            "image_properties": {
                "name": "My excellent custom image"
            },
            "import_from": "exports/my-excellent-image.vhd"
        },
        "message": "None",
        "owner": "00000123",
        "schema": "/v2/schemas/task",
        "self": "/v2/tasks/fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
        "status": "pending",
        "type": "import",
        "updated_at": "2014-02-26T02:58:46Z"
    }
    
  2. Continue to reissue the operation, until the status is either success or failure.

    When an import task completes successfully, note the image ID so that you can share it or use it to boot a server. In this example, the image ID is 1d944ab7-6748-4f3c-b7e2-3553bf006677.

    Get details for an import task response (success)

    {
        "created_at": "2014-02-26T03:02:23Z",
        "expires_at": "2014-02-28T03:28:18Z",
        "id": "d8dd8c24-2534-473c-881f-9097bc784068",
        "input": {
            "image_properties": {
                "name": "My excellent custom image"
            },
            "import_from": "exports/my-excellent-image.vhd"
        },
        "message": "None",
        "owner": "00000123",
        "result": {
            "image_id": "1d944ab7-6748-4f3c-b7e2-3553bf006677"
        },
        "schema": "/v2/schemas/task",
        "self": "/v2/tasks/d8dd8c24-2534-473c-881f-9097bc784068",
        "status": "success",
        "type": "import",
        "updated_at": "2014-02-26T03:28:18Z"
    }
    

    When an export task completes successfully, note the export_location so that you can find the image file in your Cloud Files account. In this example, the export_location is exports/ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6.vhd.

    Get details for an export task with cURL response (success)

    {
        "created_at": "2014-02-26T02:01:13Z",
        "expires_at": "2014-02-28T02:16:50Z",
        "id": "7bdc8ede-9098-4d79-9477-697f586cb333",
        "input":{
            "image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6",
            "receiving_swift_container": "exports"
        },
        "message": "None",
        "owner": "00000123",
        "result":{
            "export_location": "exports/ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6.vhd"
        },
        "schema": "/v2/schemas/task",
        "self": "/v2/tasks/7bdc8ede-9098-4d79-9477-697f586cb333",
        "status": "success",
        "type": "export",
        "updated_at": "2014-02-26T02:16:50Z"
    }
    
Previous Concepts
Next Share images
Developer Network
  • Developer Center
  • API Documentation and User Guides
  • SDKs
  • Rackspace How-To
Blogs
  • Technical Blog
  • Rackspace Blog
  • Solve: Thought Leadership
Other Information
  • Customer Stories
  • Events
  • Programs
  • Careers
  • Style Guide for Technical Content
©2020 Rackspace US, Inc.
  • ©2020 Rackspace US, Inc.
  • About Rackspace
  • Privacy Statement
  • Website Terms
  • Trademarks