Jump to: navigation, search

Difference between revisions of "Nova-scheduled-images-extension"

(→‎Additional Query Parameter on List Servers Requests)
Line 268: Line 268:
 
     <extension name="Scheduled Images Extension"
 
     <extension name="Scheduled Images Extension"
 
               namespace="http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0"
 
               namespace="http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0"
−
               alias="OS-SI" updated="2013-01-11T16:40:00-04:00">
+
               alias="os-si-image-schedule" updated="2013-01-11T16:40:00-04:00">
 
         <description>
 
         <description>
 
             Enables automatic daily images to be taken of a server.
 
             Enables automatic daily images to be taken of a server.

Revision as of 15:36, 21 March 2013

This is the full specification for blueprint: https://blueprints.launchpad.net/nova/+spec/scheduled-images

Nova Scheduled Images API Extension

Summary

Name 
Scheduled Images Extension
Namespace 
http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0
Alias 
os-si-image-schedule (OS-SI)
Dependencies 
OpenStack Compute API v2.0
Short Description 
Enables automatic daily images to be taken of a server.
Doc Link (WADL) 
(Forthcoming.)
Doc Link (XSD) 
(Forthcoming.)
New Headers 
None.
New Faults 
None.
New Actions 
None.
New Resources 
Detailed below.

Important Information That Must Be Included Somewhere

When you put an image schedule onto a server, you must specify a positive integer 'retention' value. This is the number of scheduled images of that server that will be retained in your account. The scheduled images service will remove images in excess of that value, keeping the most recently created images of that server.

  • excess image removal will be done at the time the scheduled images service successfully adds a new snapshot to your account
  • the way the scheduled images service recognizes that an image is eligible for removal is by locating the following user metadata on the image:
    org.openstack__1__created-by: scheduled-images-service
    • to "save" an image so that it is not eligible for retention culling, simply remove this metadatum
    • we do not recommend adding the above metadatum to an image manually


The scheduled images service is a best effort service. You may not specify a particular time at which your server snapshot will be taken, nor can we guarantee what time your scheduled image will become active. The times at which scheduled snapshots are taken are spread out so that they will not interfere with each other or with on-demand snapshots; the time before an image becomes active will depend upon the current network traffic load, among other things. We do guarantee, however, that all users will receive the same best-effort service.

You may wish to keep in mind the following:

  • smaller snapshots tend to finish more quickly
  • a very large snapshot may take so long to finish that it may block the next day's scheduled snapshot from occurring
  • if you have a large amount of data to save, you may wish to explore other backup options

New Resources

A new resource is created at /{tenantId}/servers/{serverId}/os-si-image-schedule to indicate that this server will be monitored by the scheduled images service. This resource contains a positive integer value, the retention. The retention value indicates the number of images created by the scheduled images service that will be retained in the user's cloud storage account. Scheduled images (and the associated retention value) are configurable per server. The cloud provider may choose to set a maximum allowable retention value.

Enable scheduled images

POST /{tenantId}/servers/{serverId}/os-si-image-schedule

JSON Request body: 

{
   "image_schedule" : {
      "retention": <positive integer>
   }
}

XML Request body: 

<?xml version='1.0' encoding='UTF-8'?>
<image_schedule xmlns="http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0">
    <retention>7</retention>
</image_schedule>

Retention: Specifies the number of snapshots created by the scheduled images service to keep for a server. If a retention value has already been specified for an server, it is overridden.

Error Conditions: a negative integer or zero is used as the retention value, or a retention value is specified that exceeds a limit set by the cloud provider.

Disable scheduled images

Disable scheduled images by deleting the resource "marker" that indicates that the scheduled images service should create snapshots of this server. 

DELETE /{tenantId}/servers/{serverId}/os-si-image-schedule

No response body.

Show scheduled images setting

 GET /{tenantId}/servers/{serverId}/os-si-image-schedule

(If the scheduled images feature is not enabled for this server, the API will return a 404.)

JSON Response Body: 

{
   "image_schedule" : {
      "retention": <positive integer>
   }
}

XML Response body: 

<?xml version='1.0' encoding='UTF-8'?>
<image_schedule xmlns="http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0">
    <retention>7</retention>
</image_schedule>

Change to Server Detail Response

Addition of the Image Schedule

The image schedule resource is added to the server detail response returned from the existing Nova requests for those servers for which an image_schedule has been created. These requests are: 

GET /{tenantId}/servers/{serverId}
GET /{tenantId}/servers/detail


Sample server detail response (JSON)

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-STS:power_state": 1, 
        "OS-EXT-STS:task_state": null, 
        "OS-EXT-STS:vm_state": "active",
        "OS-SI:image_schedule": {
                "retention": 7
            },
        "accessIPv4": "198.101.241.238", 
        "accessIPv6": "2001:4800:780e:0510:d87b:9cbc:ff04:513a", 
        "addresses": {
            "private": [
                {
                    "addr": "10.180.3.171", 
                    "version": 4
                }
            ], 
            "public": [
                {
                    "addr": "198.101.241.238", 
                    "version": 4
                }, 
                {
                    "addr": "2001:4800:780e:0510:d87b:9cbc:ff04:513a", 
                    "version": 6
                }
            ]
        }, 
        "created": "2012-08-16T18:41:43Z", 
        "flavor": {
            "id": "2", 
            "links": [
                {
                    "href": "https://dfw.servers.api.rackspacecloud.com/010101/flavors/2", 
                    "rel": "bookmark"
                }
            ]
        }, 
        "hostId": "33ccb6c82f3625748b6f2338f54d8e9df07cc583251e001355569056", 
        "id": "ef08aa7a-b5e4-4bb8-86df-5ac56230f841", 
        "image": {
            "id": "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", 
            "links": [
                {
                    "href": "https://dfw.servers.api.rackspacecloud.com/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", 
                    "rel": "bookmark"
                }
            ]
        }, 
        "links": [
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/ef08aa7a-b5e4-4bb8-86df-5ac56230f841", 
                "rel": "self"
            }, 
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/010101/servers/ef08aa7a-b5e4-4bb8-86df-5ac56230f841", 
                "rel": "bookmark"
            }
        ], 
        "metadata": {
            "My Server Name": "API Test Server 2",
        }, 
        "name": "api-test-server 2", 
        "progress": 100, 
        "rax-bandwidth:bandwidth": [], 
        "status": "ACTIVE", 
        "tenant_id": "010101", 
        "updated": "2012-08-16T18:50:38Z", 
        "user_id": "170454"
    }
}

Sample server detail response (XML)

<?xml version='1.0' encoding='UTF-8'?>
<server
    xmlns:rax-bandwidth="http://docs.rackspace.com/servers/api/ext/server_bandwidth/"
    xmlns:OS-DCF="http://docs.openstack.org/compute/ext/disk_config/api/v1.1"
    xmlns:OS-SI="http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0"
    xmlns:OS-EXT-STS="http://docs.openstack.org/compute/ext/extended_status/api/v1.1"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/compute/api/v1.1" status="BUILD"
    updated="2012-08-16T18:48:41Z"
    hostId="0b88822e7a5db46eb95b69c0608733904b2cd4f18b0c1e418eb06e1c"
    name="api-test-server-xml" created="2012-08-16T18:48:23Z"
    userId="170454" tenantId="010101" accessIPv4="" accessIPv6=""
    progress="25" id="0f828bfb-609c-4042-be41-6dcc1b76228f"
    OS-EXT-STS:vm_state="building" OS-EXT-STS:task_state="spawning"
    OS-EXT-STS:power_state="0" OS-DCF:diskConfig="AUTO">
    <OS-SI:image_schedule>
      <retention>7</retention>
    </OS-SI:image_schedule>
    <image id="3afe97b2-26dc-49c5-a2cc-a2fc8d80c001">
        <atom:link
            href="https://dfw.servers.api.rackspacecloud.com/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001"
            rel="bookmark"/>
    </image>
    <flavor id="2">
        <atom:link
            href="https://dfw.servers.api.rackspacecloud.com/010101/flavors/2"
            rel="bookmark"/>
    </flavor>
    <metadata>
        <meta key="My Server Name">API Test Server XML</meta>
    </metadata>
    <addresses>
        <network id="public">
            <ip version="6"
                addr="2001:4800:780e:0510:d87b:9cbc:ff04:5146"/>
            <ip version="4" addr="198.101.242.212"/>
        </network>
        <network id="private">
            <ip version="4" addr="10.180.15.103"/>
        </network>
    </addresses>
    <atom:link
        href="https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/0f828bfb-609c-4042-be41-6dcc1b76228f"
        rel="self"/>
    <atom:link
        href="https://dfw.servers.api.rackspacecloud.com/010101/servers/0f828bfb-609c-4042-be41-6dcc1b76228f"
        rel="bookmark"/>
    <rax-bandwidth:bandwidth/>
</server>

Additional Query Parameter on List Servers Requests

This extension introduces an additional query parameter for the two Nova list servers requests to filter responses to include either only servers that have an image_schedule resource set on them (or only servers that do not have the image_schedule resource set). 


GET /{tenantId}/servers?OS-SI:image_schedule={boolean}
GET /{tenantId}/servers/detail?OS-SI:image_schedule={boolean}


The {boolean} value is either the keyword `true` or `false`. If it's `true`, then only those servers containing an `image_schedule` resource are included in the list, if it's `false`, only those servers without an `image_schedule` resource are included in the listing.

Sample Extension Query Responses

Extension Query Response: XML

<?xml version="1.0" encoding="UTF-8"?>

<extensions xmlns="http://docs.openstack.org/common/api/v1.0"
            xmlns:atom="http://www.w3.org/2005/Atom">
    <extension name="Scheduled Images Extension"
               namespace="http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0"
               alias="os-si-image-schedule" updated="2013-01-11T16:40:00-04:00">
        <description>
            Enables automatic daily images to be taken of a server.
        </description>
        <atom:link rel="describedby" type="application/pdf"
                   href="http://docs.openstack.org/servers/api/ext/scheduled_images.pdf"/>
        <atom:link rel="describedby" type="application/xml"
                   href="http://docs.openstack.org/servers/api/ext/scheduled_images/scheduled_images.wadl"/>
    </extension>
</extensions>

Extension Query Response: JSON

{
    "extensions": [
        {
            "name": "Scheduled Images Extension",
            "namespace": "http://docs.openstack.org/servers/api/ext/scheduled_images/v1.0",
            "alias": "os-si-image-schedule",
            "updated": "2013-01-11T16:40:00-04:00",
            "description": "Enables automatic daily images to be taken of a server.",
            "links": [
                {
                    "rel": "describedby",
                    "type": "application/pdf",
                    "href": "http://docs.openstack.org/servers/api/ext/scheduled_images.pdf"
                },
                {
                    "rel": "describedby",
                    "type": "application/xml",
                    "href": "http://docs.openstack.org/servers/api/ext/scheduled_images/scheduled_images.wadl"
                }
            ]
        }
    ]
}
Retrieved from "https://wiki.openstack.org/w/index.php?title=Nova-scheduled-images-extension&oldid=19305"