Cloud Management API 1.5

Backups

Actions

index

Lists all of the backups with the given lineage tag. Filters can be used to search for a particular backup. If the 'latest_before' filter is set, only one backup is returned (the latest backup before the given timestamp).

To get the latest completed backup, the 'completed' filter should be set to 'true' and the 'latest_before' filter should be set to the current timestamp. The format of the timestamp must be YYYY/MM/DD HH:MM:SS [+/-]ZZZZ e.g. 2011/07/11 00:00:00 +0000.

To get the latest completed backup just before, say 25 June 2009, then the 'completed' filter should be set to 'true' and the 'latest_before' filter should be set to 2009/06/25 00:00:00 +0000.

URLs
GET /api/backups
HTTP response code
200 OK
Content-type
application/vnd.rightscale.backup;type=collection

Required roles

Parameters

name required type values regexp blank? description
filter no Array * * no See below for valid filter parameters.
lineage yes String * * no Backups belonging to this lineage.

Filters

name partial_match? description
cloud_href no Use to filter backups belonging to a particular cloud.
committed no Use to filter backups whose snapshots all have the tag 'rs_backup:committed=true'
completed no Use to filter backups that are completed
from_master no Use to filter backups whose snapshots all have the tag 'rs_backup:from_master=X'
latest_before no Use to get the latest backup that is created before a certain date

Example Responses

Click on a format below to see an example response:

JSON XML
[{
  "name": "test backup",
  "description": "backup description",
  "lineage": "lineage123",
  "from_master": false,
  "volume_snapshot_count": 2,
  "created_at": "2018/10/16 16:04:41 +0000",
  "completed": true,
  "committed": true,
  "links": [
    {"rel":"self","href":"/api/backups/30ef9658-d15d-11e8-9a93-0242d76f50bd"}
  ],
  "actions": [
    {
      "rel": "restore"
    }
  ],
  "volume_snapshots": [
    {
      "resource_uid": "RESOURCE_4091228126",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_4091228126;2231932585"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk1",
      "position": "1",
      "committed": true
    },
    {
      "resource_uid": "RESOURCE_2711625169",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_2711625169;67116635"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk2",
      "position": "2",
      "committed": true
    }
  ]
},{
  "name": "test backup",
  "description": "backup description",
  "lineage": "lineage123",
  "from_master": false,
  "volume_snapshot_count": 2,
  "created_at": "2018/10/16 16:04:43 +0000",
  "completed": true,
  "committed": true,
  "links": [
    {"rel":"self","href":"/api/backups/31e2f398-d15d-11e8-9a93-0242d76f50bd"}
  ],
  "actions": [
    {
      "rel": "restore"
    }
  ],
  "volume_snapshots": [
    {
      "resource_uid": "RESOURCE_2824139168",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_2824139168;1060385884"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk1",
      "position": "1",
      "committed": true
    },
    {
      "resource_uid": "RESOURCE_2743235257",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_2743235257;2554293751"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk2",
      "position": "2",
      "committed": true
    }
  ]
}]
<?xml version="1.0" encoding="UTF-8"?>
<backups>
  <backup>
    <name>test backup</name>
    <description>backup description</description>
    <lineage>lineage123</lineage>
    <from_master>false</from_master>
    <volume_snapshot_count>2</volume_snapshot_count>
    <created_at>2018/10/16 16:04:41 +0000</created_at>
    <completed>true</completed>
    <committed>true</committed>
    <links>
      <link rel="self" href="/api/backups/30ef9658-d15d-11e8-9a93-0242d76f50bd"/>
    </links>
    <actions>
      <action rel="restore"/>
    </actions>
    <volume_snapshots>
      <volume_snapshot>
        <resource_uid>RESOURCE_4091228126</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_4091228126;2231932585"/>
        </links>
        <size/>
        <state>available</state>
        <device>/dev/sdk1</device>
        <position>1</position>
        <committed>true</committed>
      </volume_snapshot>
      <volume_snapshot>
        <resource_uid>RESOURCE_2711625169</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_2711625169;67116635"/>
        </links>
        <size/>
        <state>available</state>
        <device>/dev/sdk2</device>
        <position>2</position>
        <committed>true</committed>
      </volume_snapshot>
    </volume_snapshots>
  </backup>
  <backup>
    <name>test backup</name>
    <description>backup description</description>
    <lineage>lineage123</lineage>
    <from_master>false</from_master>
    <volume_snapshot_count>2</volume_snapshot_count>
    <created_at>2018/10/16 16:04:43 +0000</created_at>
    <completed>true</completed>
    <committed>true</committed>
    <links>
      <link rel="self" href="/api/backups/31e2f398-d15d-11e8-9a93-0242d76f50bd"/>
    </links>
    <actions>
      <action rel="restore"/>
    </actions>
    <volume_snapshots>
      <volume_snapshot>
        <resource_uid>RESOURCE_2824139168</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_2824139168;1060385884"/>
        </links>
        <size/>
        <state>available</state>
        <device>/dev/sdk1</device>
        <position>1</position>
        <committed>true</committed>
      </volume_snapshot>
      <volume_snapshot>
        <resource_uid>RESOURCE_2743235257</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_2743235257;2554293751"/>
        </links>
        <size/>
        <state>available</state>
        <device>/dev/sdk2</device>
        <position>2</position>
        <committed>true</committed>
      </volume_snapshot>
    </volume_snapshots>
  </backup>
</backups>

show

Lists the attributes of a given backup

URLs
GET /api/backups/:id
HTTP response code
200 OK
Content-type
application/vnd.rightscale.backup

Required roles

Example Responses

Click on a format below to see an example response:

JSON XML
{
  "name": "test backup",
  "description": "backup description",
  "lineage": "lineage123",
  "from_master": false,
  "volume_snapshot_count": 2,
  "created_at": "2018/10/16 16:04:41 +0000",
  "completed": true,
  "committed": true,
  "links": [
    {"rel":"self","href":"/api/backups/30ef9658-d15d-11e8-9a93-0242d76f50bd"}
  ],
  "actions": [
    {
      "rel": "restore"
    }
  ],
  "volume_snapshots": [
    {
      "resource_uid": "RESOURCE_4091228126",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_4091228126;2231932585"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk1",
      "position": "1",
      "committed": true
    },
    {
      "resource_uid": "RESOURCE_2711625169",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_2711625169;67116635"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk2",
      "position": "2",
      "committed": true
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<backup>
  <name>test backup</name>
  <description>backup description</description>
  <lineage>lineage123</lineage>
  <from_master>false</from_master>
  <volume_snapshot_count>2</volume_snapshot_count>
  <created_at>2018/10/16 16:04:41 +0000</created_at>
  <completed>true</completed>
  <committed>true</committed>
  <links>
    <link rel="self" href="/api/backups/30ef9658-d15d-11e8-9a93-0242d76f50bd"/>
  </links>
  <actions>
    <action rel="restore"/>
  </actions>
  <volume_snapshots>
    <volume_snapshot>
      <resource_uid>RESOURCE_4091228126</resource_uid>
      <links>
        <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_4091228126;2231932585"/>
      </links>
      <size/>
      <state>available</state>
      <device>/dev/sdk1</device>
      <position>1</position>
      <committed>true</committed>
    </volume_snapshot>
    <volume_snapshot>
      <resource_uid>RESOURCE_2711625169</resource_uid>
      <links>
        <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_2711625169;67116635"/>
      </links>
      <size/>
      <state>available</state>
      <device>/dev/sdk2</device>
      <position>2</position>
      <committed>true</committed>
    </volume_snapshot>
  </volume_snapshots>
</backup>

create

Takes in an array of volume_attachment_hrefs and takes a snapshot of each. The volume_attachment_hrefs must belong to the same instance.

URLs
POST /api/backups
HTTP response code
201 Created
Location
Href of created Backup.

Required roles

Parameters

name required type values regexp blank? description
backup yes Hash * * no
backup[description] no String * * no The description to be set on each of the volume snapshots
backup[from_master] no String true, false * no Setting this to 'true' will create a tag 'rs_backup:from_master=true' on the snapshots so that one can filter them later.
backup[lineage] yes String * * no A unique value to create backups belonging to a particular system. This will be used to set the tag e.g. 'rs_backup:lineage=prod_mysqldb'.
backup[name] yes String * * no The name to be set on each of the volume snapshots.
backup[volume_attachment_hrefs] yes Array * * no List of volume attachment hrefs that are to be backed-up.

update

Updates the committed tag for all of the VolumeSnapshots in the given Backup to the given value.

URLs
PUT /api/backups/:id
HTTP response code
204 No Content

Required roles

Parameters

name required type values regexp blank? description
backup yes Hash * * no
backup[committed] yes String true, false * no Setting this to 'true' will update the 'rs_backup:committed=false' tag to 'rs_backup:committed=true' on all the snapshots.

destroy

Deletes a given backup by deleting all of its snapshots, this call will succeed even if the backup has not completed.

URLs
DELETE /api/backups/:id
HTTP response code
204 No Content

Required roles

cleanup

Deletes old backups that meet the given criteria. For example, if a user calls cleanup with keep monthlies set to 12, then the latest backup for each month, for 12 months, will be kept.

All backups belong to a particular 'lineage'. Backups are not constrained to a specific cloud or a specific deployment. A lineage is account-specific. Hence, backups having the same lineage but belonging to different clouds are still considered for cleanup.

If backups specific to a single cloud should be cleaned up, see the cloud_href parameter.

Definitions:
Backups are of 3 types:
An imperfect backup is picked up for cleanup only if there exists a perfect backup with a newer created_at timestamp.
No constraints will be applied on such imperfect backups and all of them will be destroyed.

For all the perfect backups, the constraints of keep_last and dailies etc. will be applied.
The algorithm for choosing the perfect backups to keep is simple. It is the union of those set of backups if each of those conditions are applied
independently. i.e backups_to_keep = backups_to_keep(keep_last) U backups_to_keep(dailies) U backups_to_keep(weeklies) U backups_to_keep(monthlies) U backups_to_keep(yearlies)

Hence, it is important to "commit" a backup to make it eligible for cleanup.

Using skip_deletion='true' attribute will return an index of what will be deleted when the action is run.
The status code returned is 200 when using this parameter instead of 204.

URLs
POST /api/backups/cleanup
HTTP response code
204 No Content

Required roles

Parameters

name required type values regexp blank? description
cloud_href no String * * no Backups belonging to only this cloud are considered for cleanup. Otherwise, all backups in the account with the same lineage will be considered.
dailies no String * ^\d+$ no The number of daily backups(the latest one in each day) that should be kept.
keep_last yes String * ^\d+$ no The number of backups that should be kept.
lineage yes String * * no The lineage of the backups that are to be cleaned-up.
monthlies no String * ^\d+$ no The number of monthly backups(the latest one in each month) that should be kept.
skip_deletion no String true, false * no When set to 'true' return an index of what backups would be cleaned-up. Otherwise, the backups will be removed.
weeklies no String * ^\d+$ no The number of weekly backups(the latest one in each week) that should be kept.
yearlies no String * ^\d+$ no The number of yearly backups(the latest one in each year) that should be kept.

restore

Restores the given Backup. This call will:

  1. create the required number of Volumes from the volume_snapshots_hrefs in the given Backup,
  2. attach them to the given Instance at the device specified in the Snapshot. If the devices are already being used on the Instance, the Task will denote that the restore has failed.

URLs
POST /api/backups/:id/restore
HTTP response code
202 Accepted
Location
Href of a Task to follow the status.

Required roles

Parameters

name required type values regexp blank? description
backup no Hash * * no
backup[description] no String * * no Each volume is created with this description instead of the volume snapshot's description
backup[iops] no String * ^\d+$ no The number of IOPS (I/O Operations Per Second) each volume should support. Only available on clouds supporting performance provisioning.
backup[name] no String * * no Each volume is created with this name instead of the volume snapshot's name
backup[size] no String * ^\d+$ no Each volume is created with this size in gigabytes (GB) instead of the volume snapshot's size (must be equal or larger). Some volume types have predefined sizes and do not allow selecting a custom size on volume creation.
backup[volume_type_href] no String * * no The href of the volume type. Each volume is created with this volume type instead of the default volume type for the cloud. A Name, Resource UID and optional Size is associated with a volume type.
instance_href yes String * * no The instance href that the backup will be restored to.