Objects’ metadata field

Objects, such as servers, drives, IPs, and VLANs have a meta field. This field can be used to store arbitrary information in key-value form. There is no predefined structure for the meta attribute, only keys are limited to 32 characters, and values should be strings. The Web UI uses the meta to store drive and server descriptions.

Note that the whole meta is updated completely so all old key-value pairs should be present in new definition, when updating meta, unless they are to be deleted.

Server’s metadata fields with special meaning

• ssh_public_key is filled with the contents of the “SSH Key” field from the server’s properties section

• cloudinit-user-data if available (and cloud-init 0.7.5 or newer is installed on the server) this field should contains valid cloud-init user data, that will be taken into account from the cloud-init

• base64_fields contains comma-separated meta keys in the metadata that are encoded in base64. This feature is useful when a meta field has more than one lines of text. cloud-init (0.7.5 or newer) for example will automatically decode from base64 the contents of cloudinit-user-data if the name of the meta key is in base64_fields

Drive’s metadata fields with special meaning

When drive is cloned from the library we copy its Metadata to the new drive’s meta as:

• os - drive’s operating system (e.g. GNU/Linux, BSD, Windows…)

• arch - the architecture of the OS (e.g. 32-bit or 64-bit)

• distribution - for GNU/Linux and BSD operating systems (e.g. Debian, Fedora, FreeBSD…)

• version - distribution’s version (if any)

• default_user - used in pre-installed images in order to specify the default user in the installed OS

• install notes - used if the image is not pre-installed

• url - URL to the official website of the OS

• description - description of what the drive contains

• image_type - type of the image on the drive (e.g. Live CD, Install CD, Pre-install)

• category - states what this image is most suitable for (e.g. dbserver, webserver, router, networking, …)

• paid - this boolean field states if cloning the drive from the library is being charged

• favorite - this boolean field states if this drive is among the most popular library drives

These fields with special meaning could still be changed and deleted (even created if missing) just like every other metadata field. Their content don’t change server/drive’s behavior nor any one of them is required.

Examples

Add meta to a drive:

To add meta to the following drive:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

one has to use update call:

PUT /api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {
        "meta_key1": "value",
        "meta_key2": "value\nwith\nnew lines"
    },
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Response is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {
        "meta_key1": "value",
        "meta_key2": "value\nwith\nnew lines"
    },
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Update server meta, by removing one key and adding another:

Suppose a server is updated to have the following definition:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key1": "value1",
        "meta_key2": "value2"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}

In order to remove meta_key1, it is just skipped in the meta definition. Keeping meta_key2 with its value is achieved by redefining it, and new key meta_key3 is added by defining it:

PUT /api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}

The final result is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}