parallelvirtualcluster
/
pvc
1
0
Fork 0
Code Issues 15 Pull Requests Projects Releases 106 Wiki Activity

Add fixed-width tags around endpoint addresses

This commit is contained in:
Joshua Boniface 2019-07-07 14:49:36 -04:00
parent b18e282987
commit 5e15c171da
1 changed files with 58 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
docs/manuals/api.md
View File

@ -34,14 +34,14 @@ The PCI API consistently returns JSON bodies as its responses, with the one exce
### General endpoints
#### /api/v1
#### `/api/v1`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: 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.
#### /api/v1/auth/login
#### `/api/v1/auth/login`
* Methods: `GET`, `POST`
* Mandatory values: `token`
* Optional values: N/A
@ -50,7 +50,7 @@ On `GET`, return an HTTP login form accepting a token to authorize a Flask sessi
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
#### `/api/v1/auth/logout`
* Methods: `GET`, `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -61,7 +61,7 @@ On `GET` or `POST`, deactivate the current Flask session for the active token.
These endpoints manage PVC node state and operation.
#### /api/v1/node
#### `/api/v1/node`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`
@ -70,7 +70,7 @@ Return a JSON document containing information about all cluster nodes .
If `limit` is specified, return a JSON document listing cluster nodes with names matching `limit` as fuzzy regex.
#### /api/v1/node/<node>
#### `/api/v1/node/<node>`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
@ -79,7 +79,7 @@ Return a JSON document containing information about `<node>`. The output is iden
If `<node>` is not valid, return an empty JSON document.
#### /api/v1/node/<node>/secondary
#### `/api/v1/node/<node>/secondary`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -88,7 +88,7 @@ Set node `<node>` into Secondary coordinator mode.
Attempting to `secondary` a non-primary node will return a failure.
#### /api/v1/node/<node>/primary
#### `/api/v1/node/<node>/primary`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -97,7 +97,7 @@ Set node `<node>` into Primary coordinator mode.
Attempting to `primary` an already-primary node will return a failure.
#### /api/v1/node/<node>/flush
#### `/api/v1/node/<node>/flush`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -106,7 +106,7 @@ Flush node `<node>` of running VMs. This command does not wait for completion of
Attempting to `flush` an already flushed node will **NOT** return a failure.
#### /api/v1/node/<node>/unflush
#### `/api/v1/node/<node>/unflush`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -115,7 +115,7 @@ Unflush (return to ready) node `<node>`, restoring migrated VMs. This command do
Attempting to `unflush` a non-flushed node will **NOT** return a failure.
#### /api/v1/node/<node>/ready
#### `/api/v1/node/<node>/ready`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -128,7 +128,7 @@ These endpoints manage PVC virtual machine (VM) state and operation.
**NOTE:** The `<vm>` variable in all VM endpoints can be either a VM `name`, or a VM `uuid`. UUIDs are used internally to track and identify VMs, but are not human-readable, so the API treats both as equally valid and will automatically determine the `uuid` for any given `name`.
#### /api/v1/vm
#### `/api/v1/vm`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`
@ -137,7 +137,7 @@ Return a JSON document containing information about all cluster VMs .
If `limit` is specified, return a JSON document listing cluster VMs with names matching `limit` as fuzzy regex.
#### /api/v1/vm/<vm>
#### `/api/v1/vm/<vm>`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
@ -146,7 +146,7 @@ Return a JSON document containing information about `<vm>`. The output is identi
If `<vm>` is not valid, return an empty JSON document.
#### /api/v1/vm/<vm>/define
#### `/api/v1/vm/<vm>/define`
* Methods: `POST`
* Mandatory values: `xml`
* Optional values: `node`, `selector`
@ -161,7 +161,7 @@ If `node` is specified and is valid, the VM will be assigned to `node` instead o
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>/modify
#### `/api/v1/vm/<vm>/modify`
* Methods: `POST`
* Mandatory values: `xml`
* Optional values: `flag_restart`
@ -174,21 +174,21 @@ By default the cluster will not restart the VM to load the new configuration; th
If `flag_restart` is specified, the cluster will automatically `restart` the VM with the new configuration.
#### /api/v1/vm/<vm>/undefine
#### `/api/v1/vm/<vm>/undefine`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Forcibly stop and undefine the VM with name or UUID `<vm>`, preserving Ceph volumes.
#### /api/v1/vm/<vm>/remove
#### `/api/v1/vm/<vm>/remove`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Forcibly stop, undefine, and remove Ceph volumes of the VM with name or UUID `<vm>`.
#### /api/v1/vm/<vm>/dump
#### `/api/v1/vm/<vm>/dump`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
@ -197,35 +197,35 @@ Obtain the raw Libvirt XML configuration of the VM with name or UUID `<vm>`.
Return an XML document containing the Libvirt XML and HTTP code 200 on success.
#### /api/v1/vm/<vm>/start
#### `/api/v1/vm/<vm>/start`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Start the VM with name or UUID `<vm>`.
#### /api/v1/vm/<vm>/restart
#### `/api/v1/vm/<vm>/restart`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Restart (`shutdown` then `start`) the VM with name or UUID `<vm>`.
#### /api/v1/vm/<vm>/shutdown
#### `/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
#### `/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
#### `/api/v1/vm/<vm>/move`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: `node`, `selector`
@ -236,7 +236,7 @@ If `node` is specified and is valid, the VM will be assigned to `node` instead o
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
#### `/api/v1/vm/<vm>/migrate`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: `node`, `selector`, `flag_force`
@ -251,7 +251,7 @@ 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 be replaced with the current node; e.g. if VM `test` was on `pvchv1`, then `migrate`ed to `pvchv2`, then `flag_force` `migrate`ed to `pvchv3`, the `previous_node` would then be `pvchv2`. This can be repeated indefinitely. Note however that `move` is almost always better and more consistent than repeated `flag_force` `migrate` actions.
#### /api/v1/vm/<vm>/unmigrate
#### `/api/v1/vm/<vm>/unmigrate`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -264,7 +264,7 @@ Attempting to `unmigrate` a non-migrated VM will return a failure.
These endpoints manage PVC client virtual network state and operation.
#### /api/v1/network
#### `/api/v1/network`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`
@ -273,7 +273,7 @@ Return a JSON document containing information about all cluster networks.
If `limit` is specified, return a JSON document listing cluster VMs with names matching `limit` as fuzzy regex.
#### /api/v1/network/<network>
#### `/api/v1/network/<network>`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
@ -282,7 +282,7 @@ Return a JSON document containing information about `<network>`. The output is i
If `<network>` is not valid, return an empty JSON document.
#### /api/v1/network/<network>/add
#### `/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`
@ -311,7 +311,7 @@ Add a new virtual network with (whitespace-free) description `<network>`.
`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.
#### /api/v1/network/<network>/modify
#### `/api/v1/network/<network>/modify`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: `vni`, `nettype` `domain`, `ip4_network`, `ip4_gateway`, `ip6_network`, `ip6_gateway`, `flag_dhcp4`, `dhcp4_start`, `dhcp4_end`
@ -322,14 +322,14 @@ All values are optional and are identical to the values for `add`. Only those va
**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, then moving VMs to it, then finally removing the old virtual network.
#### /api/v1/network/<network>/remove
#### `/api/v1/network/<network>/remove`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Remove a virtual network with description `<network>`.
#### /api/v1/network/<network>/dhcp
#### `/api/v1/network/<network>/dhcp`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`, `flag_static`
@ -340,7 +340,7 @@ If `limit` is specified, return a JSON document listing all active DHCP leases w
If `flag_static` is specified, only return static DHCP leases.
#### /api/v1/network/<network>/dhcp/<lease>
#### `/api/v1/network/<network>/dhcp/<lease>`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
@ -349,7 +349,7 @@ Return a JSON document containing information about DHCP lease with MAC address
If `<lease>` is not valid, return an empty JSON document.
#### /api/v1/network/<network>/dhcp/<lease>/add
#### `/api/v1/network/<network>/dhcp/<lease>/add`
* Methods: `POST`
* Mandatory values: `ipaddress`
* Optional values: `hostname`
@ -360,14 +360,14 @@ Add a new static DHCP lease for MAC address `<lease>` in virtual network with de
`hostname` specifies a static hostname hint for the lease.
#### /api/v1/network/<network>/dhcp/<lease>/remove
#### `/api/v1/network/<network>/dhcp/<lease>/remove`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Remove a static DHCP lease for MAC address `<lease`> in virtual network with description `<network>`.
#### /api/v1/network/<network>/acl
#### `/api/v1/network/<network>/acl`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`, `direction`
@ -378,7 +378,7 @@ If `limit` is specified, return a JSON document listing all active NFTables ACLs
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>
#### `/api/v1/network/<network>/acl/<acl>`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
@ -387,7 +387,7 @@ Return a JSON document containing information about NFTables ACL with descriptio
If `<acl>` is not valid, return an empty JSON document.
#### /api/v1/network/<network>/acl/<acl>/add
#### `/api/v1/network/<network>/acl/<acl>/add`
* Methods: `POST`
* Mandatory values: `direction`, `rule`
* Optional values: `order`
@ -400,7 +400,7 @@ 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.
#### /api/v1/network/<network>/acl/<acl>/remove
#### `/api/v1/network/<network>/acl/<acl>/remove`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -413,14 +413,14 @@ These endpoints manage PVC Ceph storage cluster state and operation.
**NOTE:** Unlike the other API endpoints, Ceph endpoints will wait until the command completes successfully before returning. This is a safety measure to prevent the critical storage subsystem from going out-of-sync with the PVC Zookeeper database; the cluster objects are only created after the storage subsystem commands complete. Because of this, *be careful with HTTP timeouts when running Ceph commands via the API*. 30s or longer may be required for some commands, especially OSD addition or removal.
#### /api/v1/ceph
#### `/api/v1/ceph`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: N/A
Return a JSON document containing information about the current Ceph cluster status.
#### /api/v1/ceph/osd
#### `/api/v1/ceph/osd`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`
@ -429,14 +429,14 @@ Return a JSON document containing information about all Ceph OSDs in the storage
If `limit` is specified, return a JSON document listing all Ceph OSDs with names matching `limit` as fuzzy regex.
#### /api/v1/ceph/osd/<osd>
#### `/api/v1/ceph/osd/<osd>`
* Methods: `GET`
* Mandatory 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.
#### /api/v1/ceph/osd/set
#### `/api/v1/ceph/osd/set`
* Methods: `POST`
* Mandatory values: `option`
* Optional values: N/A
@ -445,7 +445,7 @@ 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/ceph/osd/unset
#### `/api/v1/ceph/osd/unset`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
@ -454,7 +454,7 @@ 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/ceph/osd/<node>/add
#### `/api/v1/ceph/osd/<node>/add`
* Methods: `POST`
* Mandatory values: `device`, `weight`
* Optional values: N/A
@ -465,7 +465,7 @@ Add a new Ceph OSD to PVC node with name `<node>`.
`weight` must be a valid Ceph OSD weight, usually `1.0` if all OSD disks are the same size.
#### /api/v1/ceph/osd/<osd>/remove
#### `/api/v1/ceph/osd/<osd>/remove`
* Methods: `POST`
* Mandatory values: `flag_yes_i_really_mean_it`
* Optional values: N/A
@ -476,21 +476,21 @@ Remove a Ceph OSD device with ID `<osd>` from the storage cluster.
**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.
#### /api/v1/ceph/osd/<osd>/in
#### `/api/v1/ceph/osd/<osd>/in`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Set in (active) a Ceph OSD device with ID `<osd>` in the storage cluster.
#### /api/v1/ceph/osd/<osd>/out
#### `/api/v1/ceph/osd/<osd>/out`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Set out (inactive) a Ceph OSD device with ID `<osd>` in the storage cluster.
#### /api/v1/ceph/pool
#### `/api/v1/ceph/pool`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `limit`
@ -499,14 +499,14 @@ Return a JSON document containing information about all Ceph RBD pools in the st
If `limit` is specified, return a JSON document listing all Ceph RBD pools with names matching `limit` as fuzzy regex.
#### /api/v1/ceph/pool/<pool>
#### `/api/v1/ceph/pool/<pool>`
* Methods: `GET`
* Mandatory 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/ceph/pool?limit=<pool>` without fuzzy regex.
#### /api/v1/ceph/pool/<pool>/add
#### `/api/v1/ceph/pool/<pool>/add`
* Methods: `POST`
* Mandatory values: `pgs`
* Optional values: N/A
@ -515,7 +515,7 @@ Add a new Ceph RBD pool with name `<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 number for 3 nodes and 2 disks per node. This value can be grown later via `ceph` commands as required.
#### /api/v1/ceph/pool/<pool>/remove
#### `/api/v1/ceph/pool/<pool>/remove`
* Methods: `POST`
* Mandatory values: `flag_yes_i_really_mean_it`
* Optional values: N/A
@ -526,7 +526,7 @@ Remove a Ceph RBD pool with name `<pool>` from the storage cluster.
**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/ceph/volume
#### `/api/v1/ceph/volume`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `pool`, `limit`
@ -537,14 +537,14 @@ If `pool` is specified, return a JSON document listing all Ceph RBD volumes in C
If `limit` is specified, return a JSON document listing all Ceph RBD volumes with names matching `limit` as fuzzy regex.
#### /api/v1/ceph/volume/<pool>/<volume>
#### `/api/v1/ceph/volume/<pool>/<volume>`
* Methods: `GET`
* Mandatory 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/ceph/volume?pool=<pool>&limit=<volume>` without fuzzy regex.
#### /api/v1/ceph/volume/<pool>/<volume>/add
#### `/api/v1/ceph/volume/<pool>/<volume>/add`
* Methods: `POST`
* Mandatory values: `size`
* Optional values: N/A
@ -553,14 +553,14 @@ Add a new Ceph RBD volume with name `<volume>` to Ceph RBD pool with name `<pool
`size` must be a valid size, in bytes or a single-character metric prefix of bytes, e.g. `1073741824` (1GB), `4096M`, or `2G`.
#### /api/v1/ceph/volume/<pool>/<volume>/remove
#### `/api/v1/ceph/volume/<pool>/<volume>/remove`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A
Remove a Ceph RBD volume with name `<volume>` from Ceph RBD pool `<pool>`.
#### /api/v1/ceph/volume/snapshot
#### `/api/v1/ceph/volume/snapshot`
* Methods: `GET`
* Mandatory values: N/A
* Optional values: `pool`, `volume`, `limit`
@ -575,21 +575,21 @@ If `limit` is specified, return a JSON document listing all Ceph RBD volume snap
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`.
#### /api/v1/ceph/volume/snapshot/<pool>/<volume>/<snapshot>
#### `/api/v1/ceph/volume/snapshot/<pool>/<volume>/<snapshot>`
* Methods: `GET`
* Mandatory 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/ceph/volume?pool=<pool>&volume=<volume>&limit=<snapshot>` without fuzzy regex.
#### /api/v1/ceph/volume/snapshot/<pool>/<volume>/<snapshot>/add
#### `/api/v1/ceph/volume/snapshot/<pool>/<volume>/<snapshot>/add`
* Methods: `POST`
* Mandatory 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>`.
#### /api/v1/ceph/volume/snapshot/<pool>/<volume>/<snapshot>/remove
#### `/api/v1/ceph/volume/snapshot/<pool>/<volume>/<snapshot>/remove`
* Methods: `POST`
* Mandatory values: N/A
* Optional values: N/A