Listing Devices¶
https://blueprints.launchpad.net/craton/+spec/list-devices
Craton has separate endpoints for different types of device. Devices of different types can be linked in a parent-child relationship. Craton does not offer a mechanism to easily display devices of different types making queries tracking relationships cumbersome.
Problem description¶
As a operator I want to be able to list a device’s descendants so that I can visualise or operate on a collection of related devices.
Currently Craton supports two types of devices - hosts and network-devices. Devices include the optional attribute parent_id to create a parent-child relationship between two devices. So if one has two network-devices and one is the parent of the other, the network-devices endpoint can be queried to find the child device using the ID of the parent, e.g.
GET /v1/network-devices?parent_id=1
If a third device is added, this time as a child device of the second device, it is not possible to directly identify it from the root device. A second query would need to be made using the ID of the second device, e.g.
GET /v1/network-devices?parent_id=2
This means to represent a complete tree could potentially require a large number of queries or the client would need to get all the devices and then link them up itself.
In addition, given that both a host and a network-device can have the same parent, currently both endpoints need to be queried for any parent_id to get all the devices.
Proposed change¶
To meet the needs of the user story and resolve the problems outlined above, this spec proposes the introduction of a new endpoint for devices to allow for the querying of devices as a whole.
The endpoint will be /v1/devices and will support:
- querying against a set of attributes common to all devices
- optionally including the descendants of any query
Alternatives¶
- the traversal of the tree could be left to the client, this would likely be a slow process for large deployments
- the existing endpoints, i.e. /v1/hosts and /v1/network-devices, could be allowed to return other types of device however this is likely to be
confusing and lead to mistakes uses the output.
Data model impact¶
None
REST API impact¶
Endpoint: /v1/devices Method: GET Description: List project devices Normal response code: 200 Expected error response codes: 400
- Parameters schema: {
“type”: “object”, “additionalProperties”: False, “properties”: {
- “id”: {
- “type”: “integer”,
}, “region_id”: {
“type”: “integer”,}, “cell_id”: {
“type”: “integer”,}, “parent_id”: {
“type”: “integer”,}, “active”: {
“type”: “boolean”,}, “descendants”: {
“default”: False, “type”: “boolean”,},
},
}
- Response schema: {
“type”: “object”, “additionalProperties”: False, “properties”: {
- “devices”: {
“type”: “object”, “additionalProperties”: False, “properties”: {
- “hosts”: {
- “type”: “array”, “items”: DefinitionsHost,
}, “network-devices”: {
“type”: “array”, “items”: DefinitionNetworkDeviceResponse,},
},
}, “links”: DefinitionsPaginationLinks, },
},
}
Example: Request
Response {
- “devices”: {
- “hosts”: [
- {
“active”: true, “cell_id”: 4, “created_at”: “2017-02-16T14:28:55.000000”, “device_type”: “server”, “id”: 20, “ip_address”: “192.168.1.20”, “links”: [
- {
- “href”: “http://example.com/v1/cells/4”, “rel”: “up”
}
], “name”: “host1.DFW.C0002.C-2.example2.com”, “note”: null, “parent_id”: null, “project_id”: “b9f10eca-66ac-4c27-9c13-9d01e65f96b4”, “region_id”: 2, “updated_at”: null
} ... more hosts ...,
], “network-devices”: [
- {
“access_secret_id”: null, “active”: true, “cell_id”: 4, “created_at”: “2017-02-16T14:28:55.000000”, “device_type”: “switch”, “id”: 16, “ip_address”: “10.10.1.1”, “links”: [
- {
- “href”: “http://example.com/v1/cells/4”, “rel”: “up”
}
], “model_name”: “model-x”, “name”: “switch1.C0002.DFW.example.com”, “os_version”: “version-1”, “parent_id”: null, “project_id”: “b9f10eca-66ac-4c27-9c13-9d01e65f96b4”, “region_id”: 2, “updated_at”: null, “vlans”: null
}, ... more network-devices ...,
],
}, “links”: [
- {
- “href”: “http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid”, “rel”: “first”
}, {
“href”: “http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid”, “rel”: “prev”}, {
“href”: “http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid”, “rel”: “self”}, {
“href”: “http://example.com/v1/devices?sort_dir=asc&limit=30&sort_keys=created_at%2Cid&marker=20”, “rel”: “next”}
]
}
Example: Request
Response {
- “devices”: {
- “network-devices”: [
- {
“access_secret_id”: null, “active”: true, “cell_id”: 4, “created_at”: “2017-02-16T14:28:55.000000”, “device_type”: “switch”, “id”: 17, “ip_address”: “10.10.1.2”, “links”: [
- {
- “href”: “http://example.com/v1/network-devices/16”, “rel”: “up”
}
], “model_name”: “model-x”, “name”: “switch2.C0002.DFW.example.com”, “os_version”: “version-1”, “parent_id”: 16, “project_id”: “b9f10eca-66ac-4c27-9c13-9d01e65f96b4”, “region_id”: 2, “updated_at”: null, “vlans”: null
}, {
“access_secret_id”: null, “active”: true, “cell_id”: 4, “created_at”: “2017-02-16T14:28:55.000000”, “device_type”: “switch”, “id”: 18, “ip_address”: “10.10.1.3”, “links”: [
- {
- “href”: “http://example.com/v1/network-devices/17”, “rel”: “up”
}
], “model_name”: “model-x”, “name”: “switch3.C0002.DFW.example.com”, “os_version”: “version-1”, “parent_id”: 17, “project_id”: “b9f10eca-66ac-4c27-9c13-9d01e65f96b4”, “region_id”: 2, “updated_at”: null, “vlans”: null
},
], “hosts”: [
- {
“active”: true, “cell_id”: 4, “created_at”: “2017-02-16T14:28:55.000000”, “device_type”: “server”, “id”: 200, “ip_address”: “192.168.1.20”, “links”: [
- {
- “href”: “http://example.com/v1/network-devices/16”, “rel”: “up”
}
], “name”: “host10.DFW.C0002.C-2.example2.com”, “note”: null, “parent_id”: 16, “project_id”: “b9f10eca-66ac-4c27-9c13-9d01e65f96b4”, “region_id”: 2, “updated_at”: null
},
],
}, “links”: [
- {
- “href”: “http://example.com/v1/devices?parent_id=16&descendants=true&sort_dir=asc&limit=30&sort_keys=created_at%2Cid”, “rel”: “first”
}, {
}, {
}, {
}
]
}
Security impact¶
None
Notifications impact¶
None
Other end user impact¶
- /v1/devices with need to be supported by the client.
Performance Impact¶
Given the nature of this new endpoint, there is a strong likelihood that it will be used for most requests where listing devices is required, even if the user is only after one type.
Other deployer impact¶
None
Developer impact¶
None
Dependencies¶
None
Testing¶
A full set of functional and unit tests will need to be added.
Documentation Impact¶
The repo documentation will require updating but this is handled by the project.
References¶
None