mirror of
https://github.com/puppetlabs/vmpooler.git
synced 2026-01-26 01:58:41 -05:00
(maint) Update development documentation
This commit adds documentation for how to setup a development environment for VM Pooler. This commit also moves the API under the new docs directory and modifies the README appropriately.
This commit is contained in:
Glenn Sarti
parent
ee3f5e2215
commit
11dd15c7a8
4 changed files with 237 additions and 1 deletions
542
API.md
542
API.md
|
|
@ -1,542 +0,0 @@
|
|||
### API
|
||||
|
||||
vmpooler provides a REST API for VM management. The following examples use `curl` for communication.
|
||||
|
||||
#### Token operations
|
||||
|
||||
Token-based authentication can be used when requesting or modifying VMs. The `/token` route can be used to create, query, or delete tokens. See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), for information on configuring an authentication store to use when performing token operations.
|
||||
|
||||
##### GET /token
|
||||
|
||||
Get a list of issued tokens.
|
||||
|
||||
```
|
||||
$ curl -u jdoe --url vmpooler.company.com/api/v1/token
|
||||
Enter host password for user 'jdoe':
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"utpg2i2xswor6h8ttjhu3d47z53yy47y": {
|
||||
"created": "2015-04-28 19:17:47 -0700"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### POST /token
|
||||
|
||||
Generate a new authentication token.
|
||||
|
||||
```
|
||||
$ curl -X POST -u jdoe --url vmpooler.company.com/api/v1/token
|
||||
Enter host password for user 'jdoe':
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"token": "utpg2i2xswor6h8ttjhu3d47z53yy47y"
|
||||
}
|
||||
```
|
||||
|
||||
##### GET /token/<token>
|
||||
|
||||
Get information about an existing token (including associated VMs).
|
||||
|
||||
```
|
||||
$ curl --url vmpooler.company.com/api/v1/token/utpg2i2xswor6h8ttjhu3d47z53yy47y
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"utpg2i2xswor6h8ttjhu3d47z53yy47y": {
|
||||
"user": "jdoe",
|
||||
"created": "2015-04-28 19:17:47 -0700",
|
||||
"last": "2015-11-04 12:28:37 -0700",
|
||||
"vms": {
|
||||
"running": [
|
||||
"dqs4914g2wjyy5w",
|
||||
"hul7ib0ssr0f4o0"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### DELETE /token/<token>
|
||||
|
||||
Delete an authentication token.
|
||||
|
||||
```
|
||||
$ curl -X DELETE -u jdoe --url vmpooler.company.com/api/v1/token/utpg2i2xswor6h8ttjhu3d47z53yy47y
|
||||
Enter host password for user 'jdoe':
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
#### VM operations
|
||||
|
||||
##### GET /vm
|
||||
|
||||
Retrieve a list of available VM pools.
|
||||
|
||||
```
|
||||
$ curl --url vmpooler.company.com/api/v1/vm
|
||||
```
|
||||
```json
|
||||
[
|
||||
"debian-7-i386",
|
||||
"debian-7-x86_64"
|
||||
]
|
||||
```
|
||||
|
||||
##### POST /vm
|
||||
|
||||
Useful for batch operations; post JSON (see format below), get back VMs.
|
||||
|
||||
If an authentication store is configured, an authentication token supplied via the `X-AUTH-TOKEN` HTTP header will modify a VM's default lifetime. See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), and the 'token operations' section above for more information.
|
||||
|
||||
```
|
||||
$ curl -d '{"debian-7-i386":"2","debian-7-x86_64":"1"}' --url vmpooler.company.com/api/v1/vm
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"debian-7-i386": {
|
||||
"hostname": [
|
||||
"o41xtodlvnvu5cw",
|
||||
"khirruvwfjlmx3y"
|
||||
]
|
||||
},
|
||||
"debian-7-x86_64": {
|
||||
"hostname": "y91qbrpbfj6d13q"
|
||||
},
|
||||
"domain": "company.com"
|
||||
}
|
||||
```
|
||||
|
||||
**NOTE: Returns either all requested VMs or no VMs.**
|
||||
|
||||
##### POST /vm/<pool>
|
||||
|
||||
Check-out a VM or VMs.
|
||||
|
||||
```
|
||||
$ curl -d --url vmpooler.company.com/api/v1/vm/debian-7-i386
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"debian-7-i386": {
|
||||
"hostname": "fq6qlpjlsskycq6"
|
||||
},
|
||||
"domain": "company.com"
|
||||
}
|
||||
```
|
||||
|
||||
Multiple VMs can be requested by using multiple query parameters in the URL:
|
||||
|
||||
```
|
||||
$ curl -d --url vmpooler.company.com/api/v1/vm/debian-7-i386+debian-7-i386+debian-7-x86_64
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"debian-7-i386": {
|
||||
"hostname": [
|
||||
"sc0o4xqtodlul5w",
|
||||
"4m4dkhqiufnjmxy"
|
||||
]
|
||||
},
|
||||
"debian-7-x86_64": {
|
||||
"hostname": "zb91y9qbrbf6d3q"
|
||||
},
|
||||
"domain": "company.com"
|
||||
}
|
||||
```
|
||||
|
||||
**NOTE: Returns either all requested VMs or no VMs.**
|
||||
|
||||
##### GET /vm/<hostname>
|
||||
|
||||
Query a checked-out VM.
|
||||
|
||||
```
|
||||
$ curl --url vmpooler.company.com/api/v1/vm/pxpmtoonx7fiqg6
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"pxpmtoonx7fiqg6": {
|
||||
"template": "centos-6-x86_64",
|
||||
"lifetime": 12,
|
||||
"running": 3.1,
|
||||
"state": "running",
|
||||
"tags": {
|
||||
"department": "engineering",
|
||||
"user": "jdoe"
|
||||
},
|
||||
"domain": "company.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### PUT /vm/<hostname>
|
||||
|
||||
Modify a checked-out VM.
|
||||
|
||||
The following are valid PUT parameters and their required data structures:
|
||||
|
||||
parameter | description | required structure
|
||||
--------- | ----------- | ------------------
|
||||
*lifetime* | VM TTL (in hours) | integer
|
||||
*tags* | free-form VM tagging | hash
|
||||
|
||||
Any modifications can be verified using the [GET /vm/<hostname>](#get-vmhostname) endpoint.
|
||||
|
||||
If an authentication store is configured, an authentication token is required (via the `X-AUTH-TOKEN` HTTP header) to access this route. See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), and the 'token operations' section above for more information.
|
||||
|
||||
```
|
||||
$ curl -X PUT -d '{"lifetime":"2"}' --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
$ curl -X PUT -d '{"tags":{"department":"engineering","user":"jdoe"}}' --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
##### DELETE /vm/<hostname>
|
||||
|
||||
Schedule a checked-out VM for deletion.
|
||||
|
||||
```
|
||||
$ curl -X DELETE --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6
|
||||
```
|
||||
```json
|
||||
{
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
#### Adding additional disk(s)
|
||||
|
||||
##### POST /vm/<hostname>/disk/<size>
|
||||
|
||||
Add an additional disk to a running VM.
|
||||
|
||||
````
|
||||
$ curl -X POST -H X-AUTH-TOKEN:a9znth9dn01t416hrguu56ze37t790bl --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6/disk/8
|
||||
````
|
||||
````json
|
||||
{
|
||||
"ok": true,
|
||||
"fq6qlpjlsskycq6": {
|
||||
"disk": "+8gb"
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
Provisioning and attaching disks can take a moment, but once the task completes it will be reflected in a `GET /vm/<hostname>` query:
|
||||
|
||||
````
|
||||
$ curl --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6
|
||||
````
|
||||
````json
|
||||
{
|
||||
"ok": true,
|
||||
"fq6qlpjlsskycq6": {
|
||||
"template": "debian-7-x86_64",
|
||||
"lifetime": 2,
|
||||
"running": 0.08,
|
||||
"state": "running",
|
||||
"disk": [
|
||||
"+8gb"
|
||||
],
|
||||
"domain": "delivery.puppetlabs.net"
|
||||
}
|
||||
}
|
||||
|
||||
````
|
||||
|
||||
#### VM snapshots
|
||||
|
||||
##### POST /vm/<hostname>/snapshot
|
||||
|
||||
Create a snapshot of a running VM.
|
||||
|
||||
````
|
||||
$ curl -X POST -H X-AUTH-TOKEN:a9znth9dn01t416hrguu56ze37t790bl --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6/snapshot
|
||||
````
|
||||
````json
|
||||
{
|
||||
"ok": true,
|
||||
"fq6qlpjlsskycq6": {
|
||||
"snapshot": "n4eb4kdtp7rwv4x158366vd9jhac8btq"
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
Snapshotting a live VM can take a moment, but once the snapshot task completes it will be reflected in a `GET /vm/<hostname>` query:
|
||||
|
||||
````
|
||||
$ curl --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6
|
||||
````
|
||||
````json
|
||||
{
|
||||
"ok": true,
|
||||
"fq6qlpjlsskycq6": {
|
||||
"template": "debian-7-x86_64",
|
||||
"lifetime": 2,
|
||||
"running": 0.08,
|
||||
"state": "running",
|
||||
"snapshots": [
|
||||
"n4eb4kdtp7rwv4x158366vd9jhac8btq"
|
||||
],
|
||||
"domain": "delivery.puppetlabs.net"
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
##### POST /vm/<hostname>/snapshot/<snapshot>
|
||||
|
||||
Revert a VM back to a snapshot.
|
||||
|
||||
````
|
||||
$ curl X POST -H X-AUTH-TOKEN:a9znth9dn01t416hrguu56ze37t790bl --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6/snapshot/n4eb4kdtp7rwv4x158366vd9jhac8btq
|
||||
````
|
||||
````json
|
||||
{
|
||||
"ok": true
|
||||
}
|
||||
````
|
||||
|
||||
#### Status and metrics
|
||||
|
||||
##### GET /status
|
||||
|
||||
A "live" status endpoint, representing the current state of the service.
|
||||
|
||||
```
|
||||
$ curl --url vmpooler.company.com/api/v1/status
|
||||
```
|
||||
```json
|
||||
{
|
||||
"capacity": {
|
||||
"current": 716,
|
||||
"total": 717,
|
||||
"percent": 99.9
|
||||
},
|
||||
"clone": {
|
||||
"duration": {
|
||||
"average": 8.8,
|
||||
"min": 2.79,
|
||||
"max": 69.76
|
||||
},
|
||||
"count": {
|
||||
"total": 1779
|
||||
}
|
||||
},
|
||||
"queue": {
|
||||
"pending": 1,
|
||||
"cloning": 0,
|
||||
"booting": 1,
|
||||
"ready": 716,
|
||||
"running": 142,
|
||||
"completed": 0,
|
||||
"total": 859
|
||||
},
|
||||
"status": {
|
||||
"ok": true,
|
||||
"message": "Battle station fully armed and operational."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If there are empty pools, the "status" section will convey this:
|
||||
|
||||
```json
|
||||
"status": {
|
||||
"ok": false,
|
||||
"message": "Found 2 empty pools.",
|
||||
"empty": [
|
||||
"centos-6-x86_64",
|
||||
"debian-7-x86_64"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### GET /summary[?from=YYYY-MM-DD[&to=YYYY-MM-DD]]
|
||||
|
||||
Returns a summary, or report, for the timespan between `from` and `to` (inclusive)
|
||||
parameters. The response includes both an overall and daily view of tracked
|
||||
metrics, such as boot and cloning durations.
|
||||
|
||||
Any omitted query parameter will default to now/today. A request without any
|
||||
parameters will result in the current day's summary.
|
||||
|
||||
```
|
||||
$ curl --url vmpooler.company.com/api/v1/summary
|
||||
```
|
||||
```json
|
||||
{
|
||||
"boot": {
|
||||
"duration": {
|
||||
"average": 106.6,
|
||||
"min": 83.09,
|
||||
"max": 121.06,
|
||||
"total": 639.36,
|
||||
},
|
||||
"count": {
|
||||
"average": 6,
|
||||
"min": 6,
|
||||
"max": 6,
|
||||
"total": 6,
|
||||
}
|
||||
},
|
||||
"clone": {
|
||||
"duration": {
|
||||
"average": 4.6,
|
||||
"min": 2.78,
|
||||
"max": 8.1,
|
||||
"total": 63.94,
|
||||
},
|
||||
"count": {
|
||||
"average": 14,
|
||||
"min": 14,
|
||||
"max": 14,
|
||||
"total": 14,
|
||||
}
|
||||
},
|
||||
"tag": {
|
||||
"department": {
|
||||
"engineering": 14,
|
||||
"help desk": 10,
|
||||
"IT": 44,
|
||||
"total": 68
|
||||
},
|
||||
"user": {
|
||||
"arodgers": 54,
|
||||
"cmatthews": 10,
|
||||
"jnelson": 4,
|
||||
"total": 68
|
||||
}
|
||||
},
|
||||
"daily": [
|
||||
{
|
||||
"date": "2015-03-11",
|
||||
"boot": {
|
||||
"duration": {
|
||||
"average": 106.6,
|
||||
"min": 83.09,
|
||||
"max": 121.06,
|
||||
"total": 639.36
|
||||
},
|
||||
"count": {
|
||||
"total": 6
|
||||
}
|
||||
},
|
||||
"clone": {
|
||||
"duration": {
|
||||
"average": 4.6,
|
||||
"min": 2.78,
|
||||
"max": 8.1,
|
||||
"total": 63.94
|
||||
},
|
||||
"count": {
|
||||
"total": 14
|
||||
}
|
||||
},
|
||||
"tag": {
|
||||
"department": {
|
||||
"engineering": 14,
|
||||
"help desk": 10,
|
||||
"IT": 44,
|
||||
"total": 68
|
||||
},
|
||||
"user": {
|
||||
"arodgers": 54,
|
||||
"cmatthews": 10,
|
||||
"jnelson": 4,
|
||||
"total": 68
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
$ curl -G -d 'from=2015-03-10' -d 'to=2015-03-11' --url vmpooler.company.com/api/v1/summary
|
||||
```
|
||||
```json
|
||||
{
|
||||
"boot": {...},
|
||||
"clone": {...},
|
||||
"daily": [
|
||||
{
|
||||
"date": "2015-03-10",
|
||||
"boot": {
|
||||
"duration": {
|
||||
"average": 0,
|
||||
"min": 0,
|
||||
"max": 0,
|
||||
"total": 0
|
||||
},
|
||||
"count": {
|
||||
"total": 0
|
||||
}
|
||||
},
|
||||
"clone": {
|
||||
"duration": {
|
||||
"average": 0,
|
||||
"min": 0,
|
||||
"max": 0,
|
||||
"total": 0
|
||||
},
|
||||
"count": {
|
||||
"total": 0
|
||||
}
|
||||
},
|
||||
"tag": { }
|
||||
},
|
||||
{
|
||||
"date": "2015-03-11",
|
||||
"boot": {
|
||||
"duration": {
|
||||
"average": 106.6,
|
||||
"min": 83.09,
|
||||
"max": 121.06,
|
||||
"total": 639.36
|
||||
},
|
||||
"count": {
|
||||
"total": 6
|
||||
}
|
||||
},
|
||||
"clone": {
|
||||
"duration": {
|
||||
"average": 4.6,
|
||||
"min": 2.78,
|
||||
"max": 8.1,
|
||||
"total": 63.94
|
||||
},
|
||||
"count": {
|
||||
"total": 14
|
||||
}
|
||||
},
|
||||
"tag": { }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue