IRC on Freenode #rackspace developer forum

Rackspace Developer Docs


Let’s Build Something Powerful Together!

Submit an issue

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.

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"}}' \
-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",
   "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"
}