How to schedule a VM snapshot

Owned by JM Lopez
Last updated: Feb 03, 2017
7 min read

Prerequisites

  1. Read the VSS Snapshot Management guidelines.
  2. Valid access token. 
  3. Access to Virtual Machine
  4. Snapshot creation date and time, duration in hours (maximum 72).

REST API Snapshot Lifecycle

The following diagram describes the REST API virtual machine snapshot lifecycle:

Step-by-step guide

  1. Get virtual machine UUID using the search feature in the /vm resource:

    Request
    http GET "https://vss-api.eis.utoronto.ca/v2/vm?name=coreos0&summary" "Authorization: Bearer $TK"
    Response Body 
    {
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/vm"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>"
            },
            "name": "1606T-coreos0",
            "uuid": "<vm_uuid>"
        }
    ],
    "meta": {
        "count": 1,
        "time": "1.13983s",
        "user": "jm"
    }
}

  2. According to the Virtual Machine - Attributes - Snapshot documentation, a virtual machine snapshot is created by submitting a POST request to the /vm/<uuid>/snapshot URI, then having that we require the snapshot to be taken on 2016-07-29 at 22:00 and be valid for at least 12 hours, the JSON payload sent to the snapshot endpoint would look as following:

    {"from_date": "2016-07-29 22:00",
 "valid_for": 12,
 "description": "before upgrading very important module"}

  3. Using CURL or HTTPie to make the request would look something like:

    # HTTPie
http POST https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/snapshot from_date="2016-07-29 22:00" valid_for=12 description="before upgrading very important module" "Authorization: Bearer $TK"
# CURL
curl -H "Authorization: Bearer $TK" -H "Content-Type: application/json" -X POST "https://vss-ws.eis.utoronto.ca/v2/vm/<vm_uuid>/snapshot" -d '{"from_date": "2016-07-29 22:00", "valid_for": 12, "description": "before upgrading very important module"}'
    Response Body 
    {
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/snapshot/2"
        },
        "message": "VM Snapshot Creation Request has been accepted for processing",
        "name": "Accepted",
        "state": "Submitted",
        "status": 202
    },
    "meta": {
        "time": "0.10541s",
        "user": "jm"
    }
}

  4. If you make a GET request endpoint returned upon submission /request/snapshot/2, you would get more information about the status of request and other elements such as snapshotid, creation date, validity date, task id, etc.

    When the request has been submitted, and the snapshot hasn't been taken, the snapshot.snap_id and task_id attributes will be null. Also, the action will be set to Create.

    Snapshot Request - Before Running 
    {
    "_link": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/snapshot",
        "self": "https://vss-api.eis.utoronto.ca/v2/request/snapshot/2"
    },
    "data": {
        "_links": {
            "vm": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>"
        },
        "action": "Create",
        "created_on": "2016-07-29 12:30:59 EDT",
        "id": 2,
        "message": {},
        "snapshot": {
            "description": "before upgrading from 2016-07-29 22:00:00-04:00 valid for 12",
            "from_date": "2016-07-29 22:00:00 EDT",
            "name": "SR-2",
            "snap_id": null,
            "to_date": "2016-07-30 10:00:00 EDT",
            "valid_for": "1"
        },
        "status": "Submitted",
        "task_id": null,
        "updated_on": "2016-07-29 12:30:59 EDT",
        "user": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/user"
            },
            "username": "jm"
        },
        "vm_name": "1606T-coreos0",
        "vm_uuid": "<vm_uuid>"
    },
    "meta": {
        "count": 12,
        "time": "0.01018s",
        "user": "jm"
    }
}

    Once the snapshot has been taken, the snapshot.snap_id, task_id and message are filled out. Now, the request action has been set to Delete and it will change when the snapshot is deleted, which according to the request, this will happen at 2016-07-30 10:00:00 EDT.

    Snapshot Request - After Running 
    {
    "_link": {
        "request": "https://vss-api.eis.utoronto.ca/v2/request/snapshot",
        "self": "https://vss-api.eis.utoronto.ca/v2/request/snapshot/2"
    },
    "data": {
        "_links": {
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/6309d431-5f68-425a-9608-bb646b896e90",
            "vm": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>"
        },
        "action": "Delete",
        "created_on": "2016-07-29 12:30:59 EDT",
        "id": 2,
        "message": {
            "errors": [],
            "warnings": [
                "Snapshot created SR-2 (1): before upgrading from 2016-07-29 22:00:00-04:00 valid for 12",
                "Snapshot Delete has been Scheduled to 2016-07-30 10:00:00 EDT"
            ]
        },
        "snapshot": {
            "description": "before upgrading from 2016-07-29 22:00:00-04:00 valid for 12",
            "from_date": "2016-07-29 22:00:00 EDT",
            "name": "SR-2",
            "snap_id": "1",
            "to_date": "2016-07-30 10:00:00 EDT",
            "valid_for": "1"
        },
        "status": "Scheduled",
        "task_id": "6309d431-5f68-425a-9608-bb646b896e90",
        "updated_on": "2016-07-29 12:31:50 EDT",
        "user": {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/user"
            },
            "username": "jm"
        },
        "vm_name": "1606T-coreos0",
        "vm_uuid": "<vm_uuid>"
    },
    "meta": {
        "count": 12,
        "time": "0.01028s",
        "user": "jm"
    }
}

  5. To get information about the specific snapshot, please do a GET request to /<vm_uuid>/snapshot/<snap_id> endpoint as follows:

    Response Body 
    {
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>/snapshot/1",
        "vm": "https://vss-api.eis.utoronto.ca/v2/vm/<vm_uuid>"
    },
    "data": [
        {
            "age": "0:30:14.466488",
            "createTime": "2016-07-29 12:31:51",
            "description": "before upgrading from 2016-07-29 22:00:00-04:00 valid for 12",
            "fileKeys": [
                4,
                5
            ],
            "id": 1,
            "name": "SR-2",
            "powerState": "poweredOff",
            "quiesced": false,
            "sizeGB": 0
        }
    ],
    "meta": {
        "count": 1,
        "time": "0.04497s",
        "user": "jm"
    }
}

    Refer to Virtual Machine - Attributes - Snapshot documentation for more information about the response body.