Cloud Management API 1.5

Backups

Actions

index
show
create
update
destroy
cleanup
restore

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

observer||instance

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": "2023/10/09 11:06:01 +0000",
  "completed": true,
  "committed": true,
  "links": [
    {"rel":"self","href":"/api/backups/d4e93af4-6693-11ee-9391-0242ac110002"}
  ],
  "actions": [
    {
      "rel": "restore"
    }
  ],
  "volume_snapshots": [
    {
      "resource_uid": "RESOURCE_677854558",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_677854558;1980770223"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk1",
      "position": "1",
      "committed": true
    },
    {
      "resource_uid": "RESOURCE_1616817983",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_1616817983;3094526156"
        }
      ],
      "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": "2023/10/09 11:06:02 +0000",
  "completed": true,
  "committed": true,
  "links": [
    {"rel":"self","href":"/api/backups/d5cdabee-6693-11ee-9391-0242ac110002"}
  ],
  "actions": [
    {
      "rel": "restore"
    }
  ],
  "volume_snapshots": [
    {
      "resource_uid": "RESOURCE_1053424203",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_1053424203;3428656460"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk1",
      "position": "1",
      "committed": true
    },
    {
      "resource_uid": "RESOURCE_2048394281",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_2048394281;2630020819"
        }
      ],
      "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>2023/10/09 11:06:01 +0000</created_at>
    <completed>true</completed>
    <committed>true</committed>
    <links>
      <link rel="self" href="/api/backups/d4e93af4-6693-11ee-9391-0242ac110002"/>
    </links>
    <actions>
      <action rel="restore"/>
    </actions>
    <volume_snapshots>
      <volume_snapshot>
        <resource_uid>RESOURCE_677854558</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_677854558;1980770223"/>
        </links>
        <size/>
        <state>available</state>
        <device>/dev/sdk1</device>
        <position>1</position>
        <committed>true</committed>
      </volume_snapshot>
      <volume_snapshot>
        <resource_uid>RESOURCE_1616817983</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_1616817983;3094526156"/>
        </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>2023/10/09 11:06:02 +0000</created_at>
    <completed>true</completed>
    <committed>true</committed>
    <links>
      <link rel="self" href="/api/backups/d5cdabee-6693-11ee-9391-0242ac110002"/>
    </links>
    <actions>
      <action rel="restore"/>
    </actions>
    <volume_snapshots>
      <volume_snapshot>
        <resource_uid>RESOURCE_1053424203</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_1053424203;3428656460"/>
        </links>
        <size/>
        <state>available</state>
        <device>/dev/sdk1</device>
        <position>1</position>
        <committed>true</committed>
      </volume_snapshot>
      <volume_snapshot>
        <resource_uid>RESOURCE_2048394281</resource_uid>
        <links>
          <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_2048394281;2630020819"/>
        </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

observer||instance

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": "2023/10/09 11:06:01 +0000",
  "completed": true,
  "committed": true,
  "links": [
    {"rel":"self","href":"/api/backups/d4e93af4-6693-11ee-9391-0242ac110002"}
  ],
  "actions": [
    {
      "rel": "restore"
    }
  ],
  "volume_snapshots": [
    {
      "resource_uid": "RESOURCE_677854558",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_677854558;1980770223"
        }
      ],
      "size": null,
      "state": "available",
      "device": "/dev/sdk1",
      "position": "1",
      "committed": true
    },
    {
      "resource_uid": "RESOURCE_1616817983",
      "links": [
        {
          "rel": "self",
          "href": "/api/clouds/888/volume_snapshots/RESOURCE_1616817983;3094526156"
        }
      ],
      "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>2023/10/09 11:06:01 +0000</created_at>
  <completed>true</completed>
  <committed>true</committed>
  <links>
    <link rel="self" href="/api/backups/d4e93af4-6693-11ee-9391-0242ac110002"/>
  </links>
  <actions>
    <action rel="restore"/>
  </actions>
  <volume_snapshots>
    <volume_snapshot>
      <resource_uid>RESOURCE_677854558</resource_uid>
      <links>
        <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_677854558;1980770223"/>
      </links>
      <size/>
      <state>available</state>
      <device>/dev/sdk1</device>
      <position>1</position>
      <committed>true</committed>
    </volume_snapshot>
    <volume_snapshot>
      <resource_uid>RESOURCE_1616817983</resource_uid>
      <links>
        <link rel="self" href="/api/clouds/888/volume_snapshots/RESOURCE_1616817983;3094526156"/>
      </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

actor||instance

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

actor||instance

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

actor||instance

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:
A snapshot is completed if its status is "available"
A snapshot is committed if it has a tag "rs_backup:committed=true"
A snapshot belongs to a backup "X" if it has a tag "rs_backup:backup_id=X"
A snapshot is part of a backup with size "Y" if it has a tag "rs_backup:count=Y"
A snapshot's position in a backup is "Z" if it has a tag "rs_backup:position=Z"

Backups are of 3 types:
Perfect backup: A backup which is completed (all the snapshots are completed) and committed (all the snapshots are committed) and the number of snapshots it found is equal to the number
in the "rs_backup:count=" tag on each of the Snapshots.
Imperfect backup: A backup which is not committed or if the number of snapshots it found is not equal to the number in the "rs_backup:count=" tag on each of the snapshots.
Partial Perfect backup: A snapshot which is neither perfect nor imperfect

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

actor||instance

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:

create the required number of Volumes from the volume_snapshots_hrefs in the given Backup,
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

actor||instance

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.

MediaTypes:

Resources:

Backups

Actions

index

Required roles

Parameters

Filters

Example Responses

Click on a format below to see an example response:

show

Required roles

Example Responses

Click on a format below to see an example response:

create

Required roles

Parameters

update

Required roles

Parameters

destroy

Required roles

cleanup

Required roles

Parameters

restore

Required roles

Parameters