Objects’ meta 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.

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,
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
    },
    "resource_uri": "/api/2.0/drives/f17cce62-bcc9-4e0b-a57b-a5582b05aff0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1024000000,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "f17cce62-bcc9-4e0b-a57b-a5582b05aff0"
}

one has to use update call:

PUT /api/2.0/drives/f17cce62-bcc9-4e0b-a57b-a5582b05aff0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "allow_multimount": false,
    "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/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
    },
    "resource_uri": "/api/2.0/drives/f17cce62-bcc9-4e0b-a57b-a5582b05aff0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1024000000,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "f17cce62-bcc9-4e0b-a57b-a5582b05aff0"
}

Response is:

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

{
    "affinities": [],
    "allow_multimount": false,
    "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/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
    },
    "resource_uri": "/api/2.0/drives/f17cce62-bcc9-4e0b-a57b-a5582b05aff0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1024000000,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "f17cce62-bcc9-4e0b-a57b-a5582b05aff0"
}

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,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "hv_relaxed": false,
    "hv_tsc": false,
    "mem": 536870912,
    "meta": {
        "meta_key1": "value1",
        "meta_key2": "value2"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
    },
    "requirements": [],
    "resource_uri": "/api/2.0/servers/cfb395bb-5955-49ec-935d-a7577a646eb2/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "cfb395bb-5955-49ec-935d-a7577a646eb2",
    "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/cfb395bb-5955-49ec-935d-a7577a646eb2/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "hv_relaxed": false,
    "hv_tsc": false,
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
    },
    "requirements": [],
    "resource_uri": "/api/2.0/servers/cfb395bb-5955-49ec-935d-a7577a646eb2/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "cfb395bb-5955-49ec-935d-a7577a646eb2",
    "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,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "hv_relaxed": false,
    "hv_tsc": false,
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
    },
    "requirements": [],
    "resource_uri": "/api/2.0/servers/cfb395bb-5955-49ec-935d-a7577a646eb2/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "cfb395bb-5955-49ec-935d-a7577a646eb2",
    "vnc_password": "updated_password"
}