parallelvirtualcluster
/
pvc
1
0
Fork 0
Code Issues 11 Pull Requests Projects Releases 112 Wiki Activity

Merge branch 'api-restfulness' 

Implement a more RESTful API with proper use of HTTP verbs and better
organization.
This commit is contained in:
Joshua Boniface 2019-07-26 11:41:09 -04:00
parent 4284a0fae3 17b463afd4
commit d2b1a80a8b
6 changed files with 987 additions and 1129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
client-api/api_lib/pvcapi.py
View File

@ -41,7 +41,7 @@ def node_list(limit=None):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -55,7 +55,7 @@ def node_secondary(node):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -72,7 +72,7 @@ def node_primary(node):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -89,7 +89,7 @@ def node_flush(node):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -106,7 +106,7 @@ def node_ready(node):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -117,6 +117,13 @@ def node_ready(node):
# #
# VM functions # VM functions
# #
def vm_is_migrated(vm):
"""
Determine if a VM is migrated or not
"""
zk_conn = pvc_common.startZKConnection(config['coordinators'])
return pvc_vm.is_migrated(zk_conn, vm)
def vm_list(node=None, state=None, limit=None, is_fuzzy=True): def vm_list(node=None, state=None, limit=None, is_fuzzy=True):
""" """
Return a list of VMs with limit LIMIT. Return a list of VMs with limit LIMIT.
@ -132,7 +139,7 @@ def vm_list(node=None, state=None, limit=None, is_fuzzy=True):
'message': 'VM not found.' 'message': 'VM not found.'
} }
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -153,7 +160,7 @@ def vm_define(name, xml, node, selector):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -170,7 +177,7 @@ def vm_modify(name, restart, xml):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -187,7 +194,7 @@ def vm_undefine(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -204,7 +211,7 @@ def vm_remove(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -212,20 +219,6 @@ def vm_remove(name):
} }
return flask.jsonify(output), retcode return flask.jsonify(output), retcode
def vm_dump(name):
"""
Dump a VM Libvirt XML configuration.
"""
zk_conn = pvc_common.startZKConnection(config['coordinators'])
retflag, retdata = pvc_vm.dump_vm(zk_conn, name)
if retflag:
retcode = 200
else:
retcode = 510
pvc_common.stopZKConnection(zk_conn)
return retdata, retcode
def vm_start(name): def vm_start(name):
""" """
Start a VM in the PVC cluster. Start a VM in the PVC cluster.
@ -235,7 +228,7 @@ def vm_start(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -252,7 +245,7 @@ def vm_restart(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -269,7 +262,7 @@ def vm_shutdown(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -286,7 +279,7 @@ def vm_stop(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -303,7 +296,7 @@ def vm_move(name, node, selector):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -320,7 +313,7 @@ def vm_migrate(name, node, selector, flag_force):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -337,7 +330,7 @@ def vm_unmigrate(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -357,7 +350,7 @@ def net_list(limit=None):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -375,7 +368,7 @@ def net_add(vni, description, nettype, domain,
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -383,20 +376,21 @@ def net_add(vni, description, nettype, domain,
} }
return flask.jsonify(output), retcode return flask.jsonify(output), retcode
def net_modify(vni, description, nettype, domain, def net_modify(vni, description, domain,
ip4_network, ip4_gateway, ip6_network, ip6_gateway, ip4_network, ip4_gateway,
ip6_network, ip6_gateway,
dhcp4_flag, dhcp4_start, dhcp4_end): dhcp4_flag, dhcp4_start, dhcp4_end):
""" """
Modify a virtual client network in the PVC cluster. Modify a virtual client network in the PVC cluster.
""" """
zk_conn = pvc_common.startZKConnection(config['coordinators']) zk_conn = pvc_common.startZKConnection(config['coordinators'])
retflag, retmsg = pvc_network.add_network(zk_conn, vni, description, nettype, domain, retflag, retmsg = pvc_network.modify_network(zk_conn, vni, description, domain,
ip4_network, ip4_gateway, ip6_network, ip6_gateway, ip4_network, ip4_gateway, ip6_network, ip6_gateway,
dhcp4_flag, dhcp4_start, dhcp4_end) dhcp4_flag, dhcp4_start, dhcp4_end)
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -404,16 +398,16 @@ def net_modify(vni, description, nettype, domain,
} }
return flask.jsonify(output), retcode return flask.jsonify(output), retcode
def net_remove(description): def net_remove(network):
""" """
Remove a virtual client network from the PVC cluster. Remove a virtual client network from the PVC cluster.
""" """
zk_conn = pvc_common.startZKConnection(config['coordinators']) zk_conn = pvc_common.startZKConnection(config['coordinators'])
retflag, retmsg = pvc_network.remove_network(zk_conn, description) retflag, retmsg = pvc_network.remove_network(zk_conn, network)
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -430,7 +424,7 @@ def net_dhcp_list(network, limit=None, static=False):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -444,7 +438,7 @@ def net_dhcp_add(network, ipaddress, macaddress, hostname):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -461,7 +455,7 @@ def net_dhcp_remove(network, macaddress):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -478,7 +472,7 @@ def net_acl_list(network, limit=None, direction=None):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -495,7 +489,7 @@ def net_acl_add(network, direction, description, rule, order):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -512,7 +506,7 @@ def net_acl_remove(network, direction, description):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -532,7 +526,7 @@ def ceph_status():
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -546,7 +540,7 @@ def ceph_radosdf():
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -560,11 +554,24 @@ def ceph_osd_list(limit=None):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
def ceph_osd_state(osd):
zk_conn = pvc_common.startZKConnection(config['coordinators'])
retflag, retdata = pvc_ceph.get_list_osd(zk_conn, osd)
if retflag:
retcode = 200
else:
retcode = 400
in_state = retdata['stats']['in']
up_state = retdata['stats']['up']
return flask.jsonify([{ "id": osd, "in": in_state, "up": up_state }]), retcode
def ceph_osd_add(node, device, weight): def ceph_osd_add(node, device, weight):
""" """
Add a Ceph OSD to the PVC Ceph storage cluster. Add a Ceph OSD to the PVC Ceph storage cluster.
@ -574,7 +581,7 @@ def ceph_osd_add(node, device, weight):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -591,7 +598,7 @@ def ceph_osd_remove(osd_id):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -608,7 +615,7 @@ def ceph_osd_in(osd_id):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -625,7 +632,7 @@ def ceph_osd_out(osd_id):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -642,7 +649,7 @@ def ceph_osd_set(option):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -659,7 +666,7 @@ def ceph_osd_unset(option):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -676,7 +683,7 @@ def ceph_pool_list(limit=None):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -690,7 +697,7 @@ def ceph_pool_add(name, pgs):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -707,7 +714,7 @@ def ceph_pool_remove(name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -724,7 +731,7 @@ def ceph_volume_list(pool=None, limit=None):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -738,7 +745,7 @@ def ceph_volume_add(pool, name, size):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -755,7 +762,7 @@ def ceph_volume_remove(pool, name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -772,7 +779,7 @@ def ceph_volume_snapshot_list(pool=None, volume=None, limit=None):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
return flask.jsonify(retdata), retcode return flask.jsonify(retdata), retcode
@ -787,7 +794,7 @@ def ceph_volume_snapshot_add(pool, volume, name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {
@ -804,7 +811,7 @@ def ceph_volume_snapshot_remove(pool, volume, name):
if retflag: if retflag:
retcode = 200 retcode = 200
else: else:
retcode = 510 retcode = 400
pvc_common.stopZKConnection(zk_conn) pvc_common.stopZKConnection(zk_conn)
output = { output = {

1364
client-api/pvc-api.py
View File

File diff suppressed because it is too large Load Diff

2
client-api/pvc-api.sample.yaml
View File

@ -8,6 +8,8 @@
# Copy this example to /etc/pvc/pvc-api.conf and edit to your needs # Copy this example to /etc/pvc/pvc-api.conf and edit to your needs
pvc: pvc:
# debug: Enable/disable API debug mode
debug: True
# coordinators: The list of cluster coordinator hostnames # coordinators: The list of cluster coordinator hostnames
coordinators: coordinators:
- pvc-hv1 - pvc-hv1

3
client-common/common.py
View File

@ -200,7 +200,8 @@ def getInformationFromXML(zk_conn, uuid):
'emulator': domain_emulator, 'emulator': domain_emulator,
'features': domain_features, 'features': domain_features,
'disks': domain_disks, 'disks': domain_disks,
'controllers': domain_controllers 'controllers': domain_controllers,
'xml': lxml.etree.tostring(parsed_xml, encoding='ascii', method='xml').decode().replace('\"', '\'')
} }
return domain_information return domain_information

14
client-common/vm.py
View File

@ -106,6 +106,20 @@ def getDomainName(zk_conn, domain):
# #
# Direct functions # Direct functions
# #
def is_migrated(zk_conn, domain):
# Validate that VM exists in cluster
dom_uuid = getDomainUUID(zk_conn, domain)
if not dom_uuid:
common.stopZKConnection(zk_conn)
return False, 'ERROR: Could not find VM "{}" in the cluster!'.format(domain)
last_node = zkhandler.readdata(zk_conn, '/domains/{}/lastnode'.format(dom_uuid))
common.stopZKConnection(zk_conn)
if last_node:
return True
else:
return False
def define_vm(zk_conn, config_data, target_node, selector): def define_vm(zk_conn, config_data, target_node, selector):
# Parse the XML data # Parse the XML data
try: try:

596
docs/manuals/api.md
View File

@ -22,7 +22,7 @@ For one-time authentication, the `token` value can be specified to any API endpo
The PVC API consistently accepts values (variables) as either HTTP query string arguments, or as HTTP POST form body arguments, in either GET or POST mode. The PVC API consistently accepts values (variables) as either HTTP query string arguments, or as HTTP POST form body arguments, in either GET or POST mode.
Some values are `flag_` values; these do not require a data component, and signal an option by their presence. Some values are `` values; these do not require a data component, and signal an option by their presence.
### Data formats ### Data formats
@ -36,26 +36,36 @@ The PCI API consistently returns JSON bodies as its responses, with the one exce
#### `/api/v1` #### `/api/v1`
* Methods: `GET` * Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A ###### `GET`
* Mandatory values: `GET`: N/A
* Optional values: `GET`: N/A
Return a JSON `message` containing the API description with HTTP return code 209. Useful for determining if the API is listening and responding properly. Return a JSON `message` containing the API description with HTTP return code 209. Useful for determining if the API is listening and responding properly.
#### `/api/v1/auth/login` #### `/api/v1/auth/login`
* Methods: `GET`, `POST` * Methods: `GET`, `POST`
* Mandatory values: `token`
* Optional values: N/A
On `GET`, return an HTTP login form accepting a token to authorize a Flask session. ###### `GET`:
On `POST`, compare the specified token to the database and authorize a session. If this comparison fails to find a match, return a JSON `message` of `Authentication failed` and HTTP code 401.
#### `/api/v1/auth/logout`
* Methods: `GET`, `POST`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
On `GET` or `POST`, deactivate the current Flask session for the active token. Return an HTTP login form accepting a token to authorize a Flask session.
###### `POST`:
* Mandatory values: `token`
* Optional values: N/A
Compare the specified `token` to the database and authorize a Flask session.
#### `/api/v1/auth/logout`
* Methods: `GET`, `POST`
###### `GET`/`POST`
* Mandatory values: N/A
* Optional values: N/A
Deactivate the current Flask session for the active token.
### Node endpoints ### Node endpoints
@ -63,64 +73,57 @@ These endpoints manage PVC node state and operation.
#### `/api/v1/node` #### `/api/v1/node`
* Methods: `GET` * Methods: `GET`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `limit` * Optional values: `limit`
Return a JSON document containing information about all cluster nodes . Return a JSON document containing information about all cluster nodes. If `limit` is specified, return a JSON document containing information about cluster nodes with names matching `limit` as fuzzy regex.
If `limit` is specified, return a JSON document containing information about cluster nodes with names matching `limit` as fuzzy regex.
#### `/api/v1/node/<node>` #### `/api/v1/node/<node>`
* Methods: `GET` * Methods: `GET`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about `<node>`. The output is identical to `/api/v1/node?limit=<node>` without fuzzy regex. Return a JSON document containing information about `<node>`. The output is identical to `/api/v1/node?limit=<node>` without fuzzy regex matching.
If `<node>` is not valid, return an empty JSON document. **NOTE:** Nodes are created automatically during daemon startup; they cannot be created by the client tools.
#### `/api/v1/node/<node>/secondary` #### `/api/v1/node/<node>/coordinator-state`
* Methods: `POST` * Methods: `GET`, `POST`
###### `GET`:
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Set node `<node>` into Secondary coordinator mode. Return the coordinator state of `<node>`.
Attempting to `secondary` a non-primary node will return a failure. ###### `POST`:
* Mandatory values: `coordinator-state`
* Optional values: N/A
#### `/api/v1/node/<node>/primary` Set node `<node>` into the specified coordinator state. Attempting to re-set an existing state has no effect.
* Methods: `POST`
Valid `coordinator-state` values are: `primary`, `secondary`.
#### `/api/v1/node/<node>/domain-state`
* Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Set node `<node>` into Primary coordinator mode. Return the domain state of `<node>`.
Attempting to `primary` an already-primary node will return a failure. ###### `POST`
* Mandatory values: `domain-state`
#### `/api/v1/node/<node>/flush`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Flush node `<node>` of running VMs. This command does not wait for completion of the flush and returns immediately. Set node `<node>` to the specified domain state. Attempting to re-set an existing state has effect only if a previous state change did not complete fully, as this triggers a fresh change of state.
Attempting to `flush` an already flushed node will **NOT** return a failure. Valid `coordinator-state` values are: `flush`, `ready`.
#### `/api/v1/node/<node>/unflush`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Unflush (return to ready) node `<node>`, restoring migrated VMs. This command does not wait for completion of the flush and returns immediately.
Attempting to `unflush` a non-flushed node will **NOT** return a failure.
#### `/api/v1/node/<node>/ready`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
This endpoint is an alias for `/api/v1/node/<node>/unflush`.
### VM endpoints ### VM endpoints
@ -129,171 +132,125 @@ These endpoints manage PVC virtual machine (VM) state and operation.
**NOTE:** The `<vm>` variable in all VM endpoints can be either a `name` or a `uuid`. UUIDs are used internally by PVC to track and identify VMs, but are not human-readable, so the clients treat both as equally valid and will automatically determine the `uuid` for any given `name`. **NOTE:** The `<vm>` variable in all VM endpoints can be either a `name` or a `uuid`. UUIDs are used internally by PVC to track and identify VMs, but are not human-readable, so the clients treat both as equally valid and will automatically determine the `uuid` for any given `name`.
#### `/api/v1/vm` #### `/api/v1/vm`
* Methods: `GET` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `limit` * Optional values: `limit`
Return a JSON document containing information about all cluster VMs . Return a JSON document containing information about all cluster VMs. If `limit` is specified, return a JSON document containing information about VMs with names matching `limit` as fuzzy regex.
If `limit` is specified, return a JSON document containing information about VMs with names matching `limit` as fuzzy regex. ###### `POST`
* Mandatory values: `xml`
* Optional values: `node`, `selector`
Define a new VM with Libvirt XML configuration `xml` (either single-line or human-readable multi-line).
If `node` is specified and is valid, the VM will be assigned to `node` instead of automatically determining the target node. If `node` is specified and not valid, auto-selection occurrs instead.
If `selector` is specified and no specific and valid `node` is specified, the automatic node determination will use `selector` to determine the optimal node instead of the default for the cluster.
Valid `selector` values are: `mem`: the node with the least allocated VM memory; `vcpus`: the node with the least allocated VM vCPUs; `load`: the node with the least current load average; `vms`: the node with the least number of provisioned VMs.
**NOTE:** The `POST` operation assumes that the VM resources (i.e. disks, operating system, etc.) are already created. This is equivalent to the `pvc vm define` command in the PVC CLI client. *[todo v0.6]* Creating a new VM using the provisioner uses the `POST /api/vm/<vm>` endpoint instead.
#### `/api/v1/vm/<vm>` #### `/api/v1/vm/<vm>`
* Methods: `GET` * Methods: `GET`, *[todo v0.6]* `POST`, `PUT`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about `<vm>`. The output is identical to `/api/v1/vm?limit=<vm>` without fuzzy regex. Return a JSON document containing information about `<vm>`. The output is identical to `GET /api/v1/vm?limit=<vm>` without fuzzy regex matching.
If `<vm>` is not valid, return an empty JSON document. ###### *[todo v0.6]* `POST`
* Mandatory values: `vm_template`
* Optional values: `description`
#### `/api/v1/vm/<vm>/define` Create a new virtual machine `<vm>` with the specified VM template `vm_template` and optional text `description`.
* Methods: `POST`
###### `PUT`
* Mandatory values: `xml` * Mandatory values: `xml`
* Optional values: `node`, `selector` * Optional values: `restart`
Define a new VM with name or UUID `<vm>`. Replace the existing Libvirt XML definition for `<vm>` with the specified Libvirt XML configuration `xml` (either single-line or human-readable multi-line).
**NOTE:** While included for consistency, the specified `<vm>` value is ignored and the values from the Libvirt XML configuration will be used instead. If `restart` is specified, the cluster will automatically `restart` the VM with the new configuration; if not, the administrator must do so manually.
`xml` must be a valid Libvirt XML definition; human-readable, multi-line formatted definitions are fully supported. ###### `DELETE`
* Mandatory values: N/A
* Optional values: `delete_disks`
If `node` is specified and is valid, the VM will be assigned to `node` instead of automatically determining the target node. If `node` is specified and not valid, return a failure. Forcibly stop and undefine `<vm>`.
If `selector` is specified, the automatic node determination will use `selector` to determine the optimal node instead of the default (`mem`, least allocated VM memory). If `node` is also specified, this value is ignored. If `delete_disks` is specified, also remove all Ceph storage volumes for the VM.
#### `/api/v1/vm/<vm>/modify` #### `/api/v1/vm/<vm>/state`
* Methods: `POST` * Methods: `GET`, `POST`
* Mandatory values: `xml`
* Optional values: `flag_restart`
Replace an existing VM Libvirt XML definition for a VM with name or UUID `<vm>`. ###### `GET`
`xml` must be a valid Libvirt XML definition; human-readable, multi-line formatted definitions are fully supported.
By default the cluster will not restart the VM to load the new configuration; the administrator must do so manually.
If `flag_restart` is specified, the cluster will automatically `restart` the VM with the new configuration.
#### `/api/v1/vm/<vm>/undefine`
* Methods: `POST`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Forcibly stop and undefine the VM with name or UUID `<vm>`, preserving Ceph volumes. Return the state of `<vm>`.
#### `/api/v1/vm/<vm>/remove` ###### `POST`
* Methods: `POST` * Mandatory values: `state`
* Optional values: N/A
Set `<vm>` to the specified state. Attempting to re-set an existing state has no effect.
Valid `state` values are: `start`, `shutdown`, `stop`, `restart`
**NOTE:** The `shutdown` state will attempt to gracefully shutdown the VM with a 90s timeout, after which it will forcibly `stop` the VM.
#### `/api/v1/vm/<vm>/node`
* Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Forcibly stop, undefine, and remove Ceph volumes of the VM with name or UUID `<vm>`. Return the current host node and previous node, if applicable, for `<vm>`.
#### `/api/v1/vm/<vm>/dump` ###### `POST`
* Methods: `GET` * Mandatory values: `action`
* Mandatory values: N/A * Optional values: `node`, `selector`, `permanent`, `force`
* Optional values: N/A
Obtain the raw Libvirt XML configuration of the VM with name or UUID `<vm>`. Change the current host node for `<vm>` by `action`, using live migration if possible, and using `shutdown` then `start` if not. `action` must be either `migrate` or `unmigrate`.
Return an XML document containing the Libvirt XML and HTTP code 200 on success. If `node` is specified and is valid, the VM will be assigned to `node` instead of automatically determining the target node. If `node` is specified and not valid, auto-selection occurrs instead.
#### `/api/v1/vm/<vm>/start` If `selector` is specified and no specific and valid `node` is specified, the automatic node determination will use `selector` to determine the optimal node instead of the default for the cluster.
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Start the VM with name or UUID `<vm>`. Valid `selector` values are: `mem`: the node with the least allocated VM memory; `vcpus`: the node with the least allocated VM vCPUs; `load`: the node with the least current load average; `vms`: the node with the least number of provisioned VMs.
#### `/api/v1/vm/<vm>/restart` If `permanent` is specified, the PVC system will not track the previous node and the VM will not be considered migrated. This is equivalent to the `pvc vm move` CLI command.
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Restart (`shutdown` then `start`) the VM with name or UUID `<vm>`. If `force` is specified, and the VM has been previously migrated, force through a new migration to the selected target and do not update the previous node value.
#### `/api/v1/vm/<vm>/shutdown`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Gracefully shutdown the VM with name or UUID `<vm>`. The shutdown event will time out after 90s and `stop` the VM.
#### `/api/v1/vm/<vm>/stop`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Forcibly terminate the VM with name or UUID `<vm>` immediately.
#### `/api/v1/vm/<vm>/move`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: `node`, `selector`
Permanently move (do not track previous node) the VM with name or UUID `<vm>`. Use Libvirt live migration if possible; otherwise `shutdown` then `start` on the new node.
If `node` is specified and is valid, the VM will be assigned to `node` instead of automatically determining the target node. If `node` is specified and not valid, return a failure.
If `selector` is specified, the automatic node determination will use `selector` to determine the optimal node instead of the default (`mem`, least allocated VM memory). If `node` is also specified, this value is ignored.
#### `/api/v1/vm/<vm>/migrate`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: `node`, `selector`, `flag_force`
Temporarily move (track the previous node and migrated state) the VM with name or UUID `<vm>`. Use Libvirt live migration if possible; otherwise `shutdown` then `start` on the new node.
If `node` is specified and is valid, the VM will be assigned to `node` instead of automatically determining the target node. If `node` is specified and not valid, return a failure.
If `selector` is specified, the automatic node determination will use `selector` to determine the optimal node instead of the default (`mem`, least allocated VM memory). If `node` is also specified, this value is ignored.
Attempting to `migrate` an already-migrated VM will return a failure.
If `flag_force` is specified, migrate the VM even if it has already been migrated. The previous node value will not be replaced; e.g. if VM `test` was on `pvchv1`, then `migrate`ed to `pvchv2`, then `flag_force` `migrate`ed to `pvchv3`, the `previous_node` would still be `pvchv1`. This can be repeated indefinitely.
#### `/api/v1/vm/<vm>/unmigrate`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Unmigrate the `migrate`ed VM with name or UUID `<vm>`, returning it to its previous node. Use Libvirt live migration if possible; otherwise `shutdown` then `start` on the previous node.
Attempting to `unmigrate` a non-migrated VM will return a failure.
### Network endpoints ### Network endpoints
These endpoints manage PVC client virtual network state and operation. These endpoints manage PVC client virtual network state and operation.
#### `/api/v1/network` #### `/api/v1/network`
* Methods: `GET` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `limit` * Optional values: `limit`
Return a JSON document containing information about all cluster networks. Return a JSON document containing information about all cluster networks. If `limit` is specified, return a JSON document containing information about cluster networks with descriptions matching `limit` as fuzzy regex.
If `limit` is specified, return a JSON document containing information about cluster VMs with names matching `limit` as fuzzy regex. ###### `POST`
* Mandatory values: `vni`, `description`, `nettype`
* Optional values: `domain`, `ip4_network`, `ip4_gateway`, `ip6_network`, `ip6_gateway`, `dhcp4`, `dhcp4_start`, `dhcp4_end`
#### `/api/v1/network/<network>` Add a new virtual network to the cluster. `vni` must be a valid VNI, either a vLAN ID (for `bridged` networks) or a VXLAN ID (or `managed` networks). `description` must be a whitespace-free description of the network.
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
Return a JSON document containing information about `<network>`. The output is identical to `/api/v1/network?limit=<network>` without fuzzy regex. `nettype` must be one of the following network types:
If `<network>` is not valid, return an empty JSON document. * `bridged` for unmanaged, vLAN-based bridged networks. All additional optional values are ignored by this type
#### `/api/v1/network/<network>/add`
* Methods: `POST`
* Mandatory values: `vni`, `nettype`
* Optional values: `domain`, `ip4_network`, `ip4_gateway`, `ip6_network`, `ip6_gateway`, `flag_dhcp4`, `dhcp4_start`, `dhcp4_end`
Add a new virtual network with (whitespace-free) description `<network>`.
`vni` must be a valid VNI, either a vLAN ID (for `bridged` networks) or VXLAN ID (for `managed`) networks).
`nettype` must be one of:
* `bridged` for unmanaged, vLAN-based bridged networks. All optional values are ignored with this type.
* `managed` for PVC-managed, VXLAN-based networks. * `managed` for PVC-managed, VXLAN-based networks.
@ -307,94 +264,89 @@ Add a new virtual network with (whitespace-free) description `<network>`.
`ip6_gateway` specifies an IP address from the `ip6_network` for the primary coordinator node to provide gateway services to the network. If `ip6_network` is specified but `ip6_gateway` is not specified or is invalid, default to `<ip6_network>::1`. `ip6_gateway` specifies an IP address from the `ip6_network` for the primary coordinator node to provide gateway services to the network. If `ip6_network` is specified but `ip6_gateway` is not specified or is invalid, default to `<ip6_network>::1`.
`flag_dhcp4` specifies that DHCPv4 should be used for the IPv4 network. `dhcp4` specifies that DHCPv4 should be used for the IPv4 network.
`dhcp4_start` specifies an IP address for the start of the DHCPv4 IP pool. If `flag_dhcp4` is specified but `dhcp4_start` is not specified or is invalid, return a failure. `dhcp4_start` specifies an IP address for the start of the DHCPv4 IP pool. If `dhcp4` is specified but `dhcp4_start` is not specified or is invalid, return a failure.
`dhcp4_end` specifies an IP address for the end of the DHCPv4 IP pool. If `flag_dhcp4` is specified but `dhcp4_end` is not specified or is invalid, return a failure. `dhcp4_end` specifies an IP address for the end of the DHCPv4 IP pool. If `dhcp4` is specified but `dhcp4_end` is not specified or is invalid, return a failure.
#### `/api/v1/network/<network>/modify` #### `/api/v1/network/<network>`
* Methods: `POST` * Methods: `GET`, `PUT`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `vni`, `nettype` `domain`, `ip4_network`, `ip4_gateway`, `ip6_network`, `ip6_gateway`, `flag_dhcp4`, `dhcp4_start`, `dhcp4_end` * Optional values: N/A
Modify the options of an existing virtual network with description `<network>`. Return a JSON document containing information about the virtual network `<network>`. The output is identical to `/api/v1/network?limit=<network>` without fuzzy regex matching.
###### `PUT`
* Mandatory values: N/A
* Optional values: `domain`, `ip4_network`, `ip4_gateway`, `ip6_network`, `ip6_gateway`, `dhcp4`, `dhcp4_start`, `dhcp4_end`
Modify the options of an existing virtual network `<network>`.
All values are optional and are identical to the values for `add`. Only those values specified will be updated. All values are optional and are identical to the values for `add`. Only those values specified will be updated.
**NOTE:** Changing the `vni` or `nettype` of a virtual network is technically possible, but is not recommended. This would require updating all VMs in the network. It is usually advisable to create a new virtual network with the new VNI and type, move VMs to it, then finally remove the old virtual network. ###### `DELETE`
#### `/api/v1/network/<network>/remove` Remove a virtual network `<network>`.
* Methods: `POST`
#### `/api/v1/network/<network>/lease`
* Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: `limit`, `static`
Remove a virtual network with description `<network>`. Return a JSON document containing information about all active DHCP leases in virtual network `<network>`.
#### `/api/v1/network/<network>/dhcp`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`, `flag_static`
Return a JSON document containing information about all active DHCP leases in virtual network with description `<network>`.
If `limit` is specified, return a JSON document containing information about all active DHCP leases with MAC addresses matching `limit` as fuzzy regex. If `limit` is specified, return a JSON document containing information about all active DHCP leases with MAC addresses matching `limit` as fuzzy regex.
If `flag_static` is specified, only return static DHCP leases. If `static` is specified, only return static DHCP leases.
#### `/api/v1/network/<network>/dhcp/<lease>` ###### `POST`
* Methods: `GET` * Mandatory values: `macaddress`, `ipaddress`
* Mandatory values: N/A
* Optional values: N/A
Return a JSON document containing information about DHCP lease with MAC address `<lease>` in virtual network with description `<network>`. The output is identical to `/api/v1/network/<network>/dhcp?limit=<lease>` without fuzzy regex.
If `<lease>` is not valid, return an empty JSON document.
#### `/api/v1/network/<network>/dhcp/<lease>/add`
* Methods: `POST`
* Mandatory values: `ipaddress`
* Optional values: `hostname` * Optional values: `hostname`
Add a new static DHCP lease for MAC address `<lease>` in virtual network with description `<network>`. Add a new static DHCP lease for MAC address `<macaddress>` in virtual network `<network>`.
`ipaddress` must be a valid IP address in the specified `<network>` IPv4 netblock, and ideally outside of the DHCPv4 range. `ipaddress` must be a valid IP address in the specified `<network>` IPv4 netblock, and ideally outside of the DHCPv4 range.
`hostname` specifies a static hostname hint for the lease. `hostname` specifies a static hostname hint for the lease.
#### `/api/v1/network/<network>/dhcp/<lease>/remove` #### `/api/v1/network/<network>/dhcp/<lease>`
* Methods: `POST` * Methods: `GET`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Remove a static DHCP lease for MAC address `<lease`> in virtual network with description `<network>`. Return a JSON document containing information about DHCP lease with MAC address `<lease>` in virtual network `<network>`. The output is identical to `/api/v1/network/<network>/dhcp?limit=<lease>` without fuzzy regex matching.
###### `DELETE`
* Mandatory values: N/A
* Optional values: N/A
Remove a static DHCP lease for MAC address `<lease`> in virtual network `<network>`.
#### `/api/v1/network/<network>/acl` #### `/api/v1/network/<network>/acl`
* Methods: `GET` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `limit`, `direction` * Optional values: `limit`, `direction`
Return a JSON document containing information about all active NFTables ACLs in virtual network with description `<network>`. Return a JSON document containing information about all active NFTables ACLs in virtual network `<network>`.
If `limit` is specified, return a JSON document containing information about all active NFTables ACLs with descriptions matching `limit` as fuzzy regex. If `limit` is specified, return a JSON document containing information about all active NFTables ACLs with descriptions matching `limit` as fuzzy regex.
If `direction` is specified and is one of `in` or `out`, return a JSON codument listing all active NFTables ACLs in the specified direction only. If `direction` is invalid, return a failure. If `direction` is specified and is one of `in` or `out`, return a JSON codument listing all active NFTables ACLs in the specified direction only. If `direction` is invalid, return a failure.
#### `/api/v1/network/<network>/acl/<acl>` ###### `POST`
* Methods: `GET` * Mandatory values: `description`, `direction`, `rule`
* Mandatory values: N/A
* Optional values: N/A
Return a JSON document containing information about NFTables ACL with description `<acl>` in virtual network with description `<network>`. The output is identical to `/api/v1/network/<network>/acl?limit=<acl>` without fuzzy regex.
If `<acl>` is not valid, return an empty JSON document.
#### `/api/v1/network/<network>/acl/<acl>/add`
* Methods: `POST`
* Mandatory values: `direction`, `rule`
* Optional values: `order` * Optional values: `order`
Add a new NFTables ACL with description `<acl>` in virtual network with description `<network>`. Add a new NFTables ACL with `description` in virtual network `<network>`.
`direction` must be one of `in` or `out`. `direction` must be one of `in` or `out`.
@ -402,12 +354,22 @@ Add a new NFTables ACL with description `<acl>` in virtual network with descript
`order` specifies the order of the rule in the current chain. If not specified, the rule will be placed at the end of the rule chain. `order` specifies the order of the rule in the current chain. If not specified, the rule will be placed at the end of the rule chain.
#### `/api/v1/network/<network>/acl/<acl>/remove` #### `/api/v1/network/<network>/acl/<acl>`
* Methods: `POST` * Methods: `GET`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Remove an NFTables ACL with description `<acl>` from virtual network with description `<network>`. Return a JSON document containing information about NFTables ACL with description `<acl>` in virtual network `<network>`. The output is identical to `/api/v1/network/<network>/acl?limit=<acl>` without fuzzy regex matching.
If `<acl>` is not valid, return an empty JSON document.
###### `DELETE`
* Mandatory values: `direction`
* Optional values: N/A
Remove an NFTables ACL with description `<acl>` in direction `direction` from virtual network `<network>`.
### Storage (Ceph) endpoints ### Storage (Ceph) endpoints
@ -420,12 +382,12 @@ These endpoints manage PVC Ceph storage cluster state and operation. This sectio
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about the current Ceph cluster status. Return a JSON document containing information about the current Ceph cluster status. The JSON element `ceph_data` contains the raw output of a `ceph status` command.
The JSON element `ceph_data` contains the raw output of a `ceph status` command.
#### `/api/v1/storage/ceph/status` #### `/api/v1/storage/ceph/status`
* Methods: `GET` * Methods: `GET`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
@ -433,185 +395,169 @@ This endpoint is an alias for `/api/v1/storage/ceph`.
#### `/api/v1/storage/ceph/df` #### `/api/v1/storage/ceph/df`
* Methods: `GET` * Methods: `GET`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about the current Ceph cluster utilization. Return a JSON document containing information about the current Ceph cluster utilization. The JSON element `ceph_data` contains the raw output of a `rados df` command.
The JSON element `ceph_data` contains the raw output of a `rados df` command. #### `/api/v1/storage/ceph/cluster-option`
* Methods: `POST`
###### `POST`
* Mandatory values: `action`, `option`
* Optional values: N/A
Perform `action` to a global Ceph OSD `option` on the storage cluster. `action` must be either `set` or `unset`. `option` must be a valid option to the `ceph osd set/unset` commands, e.g. `noout` or `noscrub`.
#### `/api/v1/storage/ceph/osd` #### `/api/v1/storage/ceph/osd`
* Methods: `GET` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `limit` * Optional values: `limit`
Return a JSON document containing information about all Ceph OSDs in the storage cluster. Return a JSON document containing information about all Ceph OSDs in the storage cluster. If `limit` is specified, return a JSON document containing information about all Ceph OSDs with names matching `limit` as fuzzy regex.
If `limit` is specified, return a JSON document containing information about all Ceph OSDs with names matching `limit` as fuzzy regex. ###### `POST`
* Mandatory values: `node`, `device`, `weight`
* Optional values: N/A
Add a new Ceph OSD to PVC node `<node>`. `device` must be a valid block device on the specified `<node>`, e.g. `/dev/sdb`. `weight` must be a valid Ceph OSD weight, usually `1.0` if all OSD disks are the same size.
#### `/api/v1/storage/ceph/osd/<osd>` #### `/api/v1/storage/ceph/osd/<osd>`
* Methods: `GET` * Methods: `GET`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about Ceph OSD with ID `<osd>` in the storage cluster. Unlike other similar endpoints, this is **NOT** equivalent to any limit within the list, since that limit is based off names rather than just the ID. Return a JSON document containing information about Ceph OSD with ID `<osd>` in the storage cluster. Unlike other similar endpoints, this is **NOT** equivalent to any limit within the list, since that limit is based off names rather than just the ID.
#### `/api/v1/storage/ceph/osd/set` ###### `DELETE`
* Methods: `POST` * Mandatory values: `yes_i_really_mean_it`
* Mandatory values: `option`
* Optional values: N/A
Set a global Ceph OSD option on the storage cluster.
`option` must be a valid option to the `ceph osd set` command, e.g. `noout` or `noscrub`.
#### `/api/v1/storage/ceph/osd/unset`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Unset a global Ceph OSD option on the storage cluster.
`option` must be a valid option to the `ceph osd unset` command, e.g. `noout` or `noscrub`.
#### `/api/v1/storage/ceph/osd/<node>/add`
* Methods: `POST`
* Mandatory values: `device`, `weight`
* Optional values: N/A
Add a new Ceph OSD to PVC node with name `<node>`.
`device` must be a valid block device on the specified `<node>`, e.g. `/dev/sdb`.
`weight` must be a valid Ceph OSD weight, usually `1.0` if all OSD disks are the same size.
#### `/api/v1/storage/ceph/osd/<osd>/remove`
* Methods: `POST`
* Mandatory values: `flag_yes_i_really_mean_it`
* Optional values: N/A * Optional values: N/A
Remove a Ceph OSD device with ID `<osd>` from the storage cluster. Remove a Ceph OSD device with ID `<osd>` from the storage cluster.
**NOTE:** This is a command with potentially dangerous unintended consequences that should not be scripted. To acknowledge the danger, the `flag_yes_i_really_mean_it` must be set or the endpoint will return a failure. **NOTE:** This is a command with potentially dangerous unintended consequences that should not be scripted. To acknowledge the danger, the `yes_i_really_mean_it` must be set or the endpoint will return a failure.
**WARNING:** Removing an OSD without first setting it `out` (and letting it flush) triggers an unclean PG recovery. This could potentially cause data loss if other OSDs were to fail or be removed. OSDs should not normally be removed except in the case of failed OSDs during replacement or during a replacement with a larger disk. **WARNING:** Removing an OSD without first setting it `out` (and letting it flush) triggers an unclean PG recovery. This could potentially cause data loss if other OSDs were to fail or be removed. OSDs should not normally be removed except in the case of failed OSDs during replacement or during a replacement with a larger disk. For more information please see the Ceph documentation.
#### `/api/v1/storage/ceph/osd/<osd>/in` #### `/api/v1/storage/ceph/osd/<osd>/state`
* Methods: `POST` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Set in (active) a Ceph OSD device with ID `<osd>` in the storage cluster. Return the state state of OSD `<osd>`.
#### `/api/v1/storage/ceph/osd/<osd>/out` ###### `POST`
* Methods: `POST` * Mandatory values: `state`
* Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Set out (inactive) a Ceph OSD device with ID `<osd>` in the storage cluster. Set a Ceph OSD device with ID `<osd>` to `state`. `state` must be either `in` or `out`.
#### `/api/v1/storage/ceph/pool` #### `/api/v1/storage/ceph/pool`
* Methods: `GET` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `limit` * Optional values: `limit`
Return a JSON document containing information about all Ceph RBD pools in the storage cluster. Return a JSON document containing information about all Ceph RBD pools in the storage cluster. If `limit` is specified, return a JSON document containing information about all Ceph RBD pools with names matching `limit` as fuzzy regex.
If `limit` is specified, return a JSON document containing information about all Ceph RBD pools with names matching `limit` as fuzzy regex. ###### `POST`
* Mandatory values: `pool`, `pgs`
* Optional values: N/A
Add a new Ceph RBD pool `<pool>` to the storage cluster. `pgs` must be a valid number of Placement Groups for the pool, taking into account the number of OSDs and the replication of the pool (`copies=3`). `256` is a safe and sane number of PGs for 3 nodes and 2 disks per node. This value can be grown later via `ceph` commands as required.
#### `/api/v1/storage/ceph/pool/<pool>` #### `/api/v1/storage/ceph/pool/<pool>`
* Methods: `GET` * Methods: `GET`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about Ceph RBD pool with name `<pool>`. The output is identical to `/api/v1/storage/ceph/pool?limit=<pool>` without fuzzy regex. Return a JSON document containing information about Ceph RBD pool `<pool>`. The output is identical to `/api/v1/storage/ceph/pool?limit=<pool>` without fuzzy regex matching.
#### `/api/v1/storage/ceph/pool/<pool>/add` ###### `DELETE`
* Methods: `POST` * Mandatory values: `yes_i_really_mean_it`
* Mandatory values: `pgs`
* Optional values: N/A * Optional values: N/A
Add a new Ceph RBD pool with name `<pool>` to the storage cluster. Remove a Ceph RBD pool `<pool>` from the storage cluster.
`pgs` must be a valid number of Placement Groups for the pool, taking into account the number of OSDs and the replication of the pool (`copies=3`). `256` is a safe number for 3 nodes and 2 disks per node. This value can be grown later via `ceph` commands as required. **NOTE:** This is a command with potentially dangerous unintended consequences that should not be scripted. To acknowledge the danger, the `yes_i_really_mean_it` must be set or the endpoint will return a failure.
#### `/api/v1/storage/ceph/pool/<pool>/remove`
* Methods: `POST`
* Mandatory values: `flag_yes_i_really_mean_it`
* Optional values: N/A
Remove a Ceph RBD pool with name `<pool>` from the storage cluster.
**NOTE:** This is a command with potentially dangerous unintended consequences that should not be scripted. To acknowledge the danger, the `flag_yes_i_really_mean_it` must be set or the endpoint will return a failure.
**WARNING:** Removing an RBD pool will delete all data on that pool, including all Ceph RBD volumes on the pool. Do not run this command lightly and without ensuring the pool is safely removable first. **WARNING:** Removing an RBD pool will delete all data on that pool, including all Ceph RBD volumes on the pool. Do not run this command lightly and without ensuring the pool is safely removable first.
#### `/api/v1/storage/ceph/volume` #### `/api/v1/storage/ceph/volume`
* Methods: `GET` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `pool`, `limit` * Optional values: `pool`, `limit`
Return a JSON document containing information about all Ceph RBD volumes in the storage cluster. Return a JSON document containing information about all Ceph RBD volumes in the storage cluster. If `pool` is specified, return a JSON document containing information about all Ceph RBD volumes in Ceph RBD pool `pool`. If `limit` is specified, return a JSON document containing information about all Ceph RBD volumes with names matching `limit` as fuzzy regex.
If `pool` is specified, return a JSON document containing information about all Ceph RBD volumes in Ceph RBD pool with name `pool`. ###### `POST`
* Mandatory values: `volume`, `pool`, `size`
* Optional values: N/A
If `limit` is specified, return a JSON document containing information about all Ceph RBD volumes with names matching `limit` as fuzzy regex. Add a new Ceph RBD volume `<volume>` to Ceph RBD pool `<pool>`. `size` must be a valid size, in bytes or a single-character metric prefix of bytes, e.g. `1073741824` (1GB), `4096M`, or `20G`.
#### `/api/v1/storage/ceph/volume/<pool>/<volume>` #### `/api/v1/storage/ceph/volume/<pool>/<volume>`
* Methods: `GET` * Methods: `GET`, `PUT`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about Ceph RBD volume with name `<volume>` in Ceph RBD pool with name `<pool>`. The output is identical to `/api/v1/storage/ceph/volume?pool=<pool>&limit=<volume>` without fuzzy regex. Return a JSON document containing information about Ceph RBD volume `<volume>` in Ceph RBD pool `<pool>`. The output is identical to `/api/v1/storage/ceph/volume?pool=<pool>&limit=<volume>` without fuzzy regex matching.
#### `/api/v1/storage/ceph/volume/<pool>/<volume>/add` ###### `PUT`
* Methods: `POST` * Mandatory values: N/A
* Mandatory values: `size` * Optional values: `name`, `size`
* Optional values: N/A
Add a new Ceph RBD volume with name `<volume>` to Ceph RBD pool with name `<pool>`. Change the configuration of the volume `<volume>`. If `name` is specified, rename the volume to the specified name. If `size` is specified, resize the volume to the specified size (see `POST /api/v1/storage/ceph/volume` for restrictions).
`size` must be a valid size, in bytes or a single-character metric prefix of bytes, e.g. `1073741824` (1GB), `4096M`, or `2G`. ###### `DELETE`
#### `/api/v1/storage/ceph/volume/<pool>/<volume>/remove`
* Methods: `POST`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Remove a Ceph RBD volume with name `<volume>` from Ceph RBD pool `<pool>`. Remove a Ceph RBD volume `<volume>` from Ceph RBD pool `<pool>`.
#### `/api/v1/storage/ceph/volume/snapshot` #### `/api/v1/storage/ceph/volume/snapshot`
* Methods: `GET` * Methods: `GET`, `POST`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: `pool`, `volume`, `limit` * Optional values: `pool`, `volume`, `limit`
Return a JSON document containing information about all Ceph RBD volume snapshots in the storage cluster. Return a JSON document containing information about all Ceph RBD volume snapshots in the storage cluster. If `pool` is specified, return a JSON document containing information about all Ceph RBD volume snapshots in Ceph RBD pool `pool`. If `volume` is specified, return a JSON document containing information about all Ceph RBD volume snapshots of Ceph RBD volume `volume`. If `limit` is specified, return a JSON document containing information about all Ceph RBD volume snapshots with names matching `limit` as fuzzy regex.
If `pool` is specified, return a JSON document containing information about all Ceph RBD volume snapshots in Ceph RBD pool with name `pool`.
If `volume` is specified, return a JSON document containing information about all Ceph RBD volume snapshots of Ceph RBD volume with name `volume`.
If `limit` is specified, return a JSON document containing information about all Ceph RBD volume snapshots with names matching `limit` as fuzzy regex.
The various limit options can be combined freely, e.g. one can specify a `volume` without `pool`, which would match all snapshots of the named volume(s) regardless of pool, or a `pool` and `limit` without a `volume`, which would match all named snapshots on any volume in `pool`. The various limit options can be combined freely, e.g. one can specify a `volume` without `pool`, which would match all snapshots of the named volume(s) regardless of pool, or a `pool` and `limit` without a `volume`, which would match all named snapshots on any volume in `pool`.
###### `POST`
* Mandatory values: `snapshot`, `volume`, `pool`
* Optional values: N/A
Add a new Ceph RBD volume snapshot `snapshot` of Ceph RBD volume `volume` on Ceph RBD pool `pool`.
#### `/api/v1/storage/ceph/volume/snapshot/<pool>/<volume>/<snapshot>` #### `/api/v1/storage/ceph/volume/snapshot/<pool>/<volume>/<snapshot>`
* Methods: `GET` * Methods: `GET`, `DELETE`
###### `GET`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Return a JSON document containing information about Ceph RBD volume snapshot with name `<snapshot>` of Ceph RBD volume with name `<volume>` in Ceph RBD pool with name `<pool>`. The output is identical to `/api/v1/storage/ceph/volume?pool=<pool>&volume=<volume>&limit=<snapshot>` without fuzzy regex. Return a JSON document containing information about Ceph RBD volume snapshot `<snapshot>` of Ceph RBD volume `<volume>` in Ceph RBD pool `<pool>`. The output is identical to `/api/v1/storage/ceph/volume?pool=<pool>&volume=<volume>&limit=<snapshot>` without fuzzy regex matching.
#### `/api/v1/storage/ceph/volume/snapshot/<pool>/<volume>/<snapshot>/add` ###### `DELETE`
* Methods: `POST`
* Mandatory values: N/A * Mandatory values: N/A
* Optional values: N/A * Optional values: N/A
Add a new Ceph RBD volume snapshot with name `<volume>` of Ceph RBD volume with name `<volume>` on Ceph RBD pool with name `<pool>`. Remove a Ceph RBD volume snapshot `<snapshot>` of Ceph RBD volume `<volume>` on Ceph RBD pool `<pool>`.
#### `/api/v1/storage/ceph/volume/snapshot/<pool>/<volume>/<snapshot>/remove`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Remove a Ceph RBD volume snapshot with name `<volume>` of Ceph RBD volume with name `<volume>` on Ceph RBD pool with name `<pool>`.