Volumes

We provide a flexible size additional storage service for our Instances called volumes. This creates and attaches an additional virtual disk to the instance, allowing you to put backups or database files on the separate volume and later move the volume to another instance.

As volume storage is chargeable, at any time these can be deleted.

Create a new volume

Any user can create volumes to be attached to their instances, this takes up usage from Disk space under their quota.

New volumes are created by sending a POST request to https://api.civo.com/v2/volumes. Important: the creation of a volume and attaching it to an instance are two completely separate steps.

Request

The only required parameters are the name of the volume and the size required in gigabytes as a body parameter.

Response

The response is a JSON object that confirms the details given.

{
    "id": "c424c69d-e4bc-4a8f-9169-dccc8fe5b2c0",
    "name": "test-volume",
    "cluster_id": "",
    "network_id": "5c16ab17-933a-46ed-96c6-8a093a0179e1",
    "instance_id": null,
    "mountpoint": null,
    "size_gb": 1,
    "status": null
}

Example of creating a volume

• Curl
• Node.js
• Ruby

curl -X POST -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes \
  -d "name=test-volume&size_gb=1&network_id=5c16ab17-933a-46ed-96c6-8a093a0179e1"

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/volumes',
  {
    "name": "my-volume",
    "size_gb": 25
  },
  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/volumes', 'name=my-volume&size_gb=25', headers)

List volumes

A list of all volumes in your account is available by sending a GET request to https://api.civo.com/v2/volumes.

Request

This request accepts an optional region parameter (query string) containing the name of the region where the network is located. A random one will be picked by the system if not specified.

Response

The response is a JSON array of objects that describes summary details for each instance.

[
    {
        "id": "c424c69d-e4bc-4a8f-9169-dccc8fe5b2c0",
        "name": "test-volume",
        "cluster_id": "",
        "network_id": "5c16ab17-933a-46ed-96c6-8a093a0179e1",
        "instance_id": null,
        "mountpoint": null,
        "size_gb": 1,
        "status": "creating"
    }
]

Example of listing volumes

• Curl
• Node.js
• Ruby

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/volumes',
  {},
  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/volumes', headers)

Attach a volume to an instance

Once the volume is created and has an instance_id, you can attach it to the instance (which is like plugging a USB drive into a computer - it still needs partitioning, formatting and mounting).

Volumes are attached by sending a PUT request to https://api.civo.com/v2/volumes/:id/attach. Important: volumes can only be attached to one instance at a time.

Request

The required parameters are the id of the volume in the URL and the ID of the instance as a body parameter.

Response

The response is a JSON object that confirms the details given.

{
  "result": "success"
}

Example of attaching a volume to an instance

• Curl
• Node.js
• Ruby

curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/attach \
  -d "instance_id=862eddfe-404a-40a7-a55f-13e287595340&region=LON1"

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/attach',
  {
    "instance_id": "862eddfe-404a-40a7-a55f-13e287595340"
  },
  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.put('/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/attach', 'name=862eddfe-404a-40a7-a55f-13e287595340', headers)

Detach a volume from an instance

If you've finished with the volume or want to move it to another instance, you can detach it from the instance (which is like unplugging a USB drive from a computer - you should still have safely unmounted the drive first or you risk corruption).

Volumes are detached by sending a PUT request to https://api.civo.com/v2/volumes/:id/detach.

Request

Response

The response is a JSON object that confirms the action is being taken.

{
  "result": "success"
}

Example of detaching a volume

• Curl
• Node.js
• Ruby

curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/detach \
 -d "region=LON1"

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/detach',
  {},
  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.put('/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/detach', '', headers)

Deleting a volume

An account holder can remove a volume, freeing up the space used (and therefore the cost) by sending a DELETE request to https://api.civo.com/v2/volumes/:id.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the volume is located. No confirmation step is required; this step will remove the volume 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 volume

• Curl
• Node.js
• Ruby

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614?region=LON1

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614',
  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/volumes/44aab548-61ca-11e5-860e-5cf9389be614', headers)