Snapshots
We provide a backup service for our Instances called snapshots. This takes an exact copy of the instance's virtual hard drive. At any point an instance can be restored to the state it was in when the snapshot was made. These snapshots can also be used to build a new instance to scale identically configured infrastructure.
As snapshot storage is chargeable, at any time these can be deleted. They can also be scheduled rather than immediately created, and if desired repeated at the same schedule each week (although the repeated snapshot will overwrite itself each week not keep multiple weekly snapshots).
Statuses
The possible values for the status
attribute for a snapshot are:
Create a new or update an old snapshot
Any user can create snapshots for their instances, this space is charged separately from their quota.
New snapshots are created by sending a PUT
request to https://api.civo.com/v2/snapshots/:name
.
Request
The only required parameters are the instance ID as a body parameter and the snapshot name in the URL. Two optional parameters of safe
and cron_timing
can also be passed. If the snapshot already exists it will be overwritten.
Name | Description |
---|---|
instance_id | The ID of the instance to snapshot |
safe | If true the instance will be shut down during the snapshot to ensure all files are in a consistent state (e.g. database tables aren't in the middle of being optimised and hence risking corruption). The default is false so you experience no interruption of service, but a small risk of corruption. |
cron_timing | If a valid cron string is passed, the snapshot will be saved as an automated snapshot, continuing to automatically update based on the schedule of the cron sequence provided. The default is nil meaning the snapshot will be saved as a one-off snapshot. |
Response
The response is a JSON object that confirms the details given, with a null
for snapshot_at (as it won't have been taken yet).
{
"id": "0ca69adc-ff39-4fc1-8f08-d91434e86fac",
"instance_id": "44aab548-61ca-11e5-860e-5cf9389be614",
"hostname": "server1.prod.example.com",
"template_id": "0b213794-d795-4483-8982-9f249c0262b9",
"openstack_snapshot_id": null,
"region": "lon1",
"name": "my-instance-snapshot",
"safe": 1,
"size_gb": 0,
"state": "new",
"cron_timing": null,
"requested_at": null,
"completed_at": null
}
Example of creating a snapshot
curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/snapshots/my-instance-snapshot \
-d "instance_id=b177ae0e-60fa-11e5-be02-5cf9389be614&safe=true"
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.post(
'https://api.civo.com/v2/snapshots/my-instance-snapshot',
{
"instance_id": "b177ae0e-60fa-11e5-be02-5cf9389be614",
"safe": true
},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.post('/v2/snapshots/my-instance-snapshot', 'instance_id=b177ae0e-60fa-11e5-be02-5cf9389be614&safe=true', headers)
List snapshots
A list of all snapshots in your account is available by sending a GET
request to https://api.civo.com/v2/snapshots
.
Request
This request takes no parameters.
Response
The response is a JSON array of objects that describes summary details for each instance.
[
{
"id": "0ca69adc-ff39-4fc1-8f08-d91434e86fac",
"instance_id": "44aab548-61ca-11e5-860e-5cf9389be614",
"hostname": "server1.prod.example.com",
"template_id": "0b213794-d795-4483-8982-9f249c0262b9",
"openstack_snapshot_id": null,
"region": "lon1",
"name": "my-instance-snapshot",
"safe": 1,
"size_gb": 0,
"state": "in-progress",
"cron_timing": null,
"requested_at": null,
"completed_at": null
},
// ...
]
Example of listing snapshots
curl -H "Authorization: bearer 12345" https://api.civo.com/v2/snapshots
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.get(
'https://api.civo.com/v2/snapshots',
{},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.get('/v2/snapshots', headers)
Deleting a snapshot
An account holder can remove a snapshot, freeing up the space used (and therefore the cost) by sending a DELETE
request to https://api.civo.com/v2/snapshots/:name
.
Request
This request takes no parameters, only the name of the snapshot to delete is in the URL. No confirmation step is required, this step will remove the snapshot immediately.
Response
The response from the server will be a JSON block. The response will include a result
field and the HTTP status will be 200 OK
.
{
"result": "success"
}
Example of deleting a snapshot
curl -H "Authorization: bearer 12345" \
-X DELETE https://api.civo.com/v2/snapshots/my-instance-snapshot
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.del(
'https://api.civo.com/v2/snapshots/my-instance-snapshot',
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.delete('/v2/snapshots/my-instance-snapshot', headers)