puppetlabs/vmpooler
2
0
Fork 0
mirror of https://github.com/puppetlabs/vmpooler.git synced 2026-01-26 01:58:41 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

(POOLER-107) Add configuration API endpoint

Browse source 
This commit adds a configuration endpoint to the vmpooler API. Pool
size, and pool template, can be adjusted for pools that are configured
at vmpooler application start time. Pool template changes trigger a pool
refresh, and the new template has delta disks created automatically by
vmpooler.

Additionally, the capability to create template delta disks is added to
the vsphere provider, and this is implemented to ensure that templates
have delta disks created at application start time.

The mechanism used to find template VM objects is simplified to make the flow of logic easier to understand. As an additional benefit, performance of this lookup is improved by using FindByInventoryPath.

A table of contents is added to API.md to ease navigation. Without this change API.md has no table of contents and is difficult to navigate.

Add mutex object for managing pool configuration updates

This commit adds a mutex object for ensuring that pool configuration changes are synchronized across multiple running threads, removing the possibility of two threads attempting to update something at once, without relying on redis data. Without this change this is managed crudely by specifying in redis that a configuration update is taking place. This redis data is left so the REPOPULATE section of _check_pool can still identify when a configuration change is in progress, and prevent a pool from repopulating at that time.

Add wake up event for pool template changes

This commit adds a wake up event to detect pool template changes.
Additionally, GET /config has a template_ready section added to the
output for each pool, which makes clear when a pool is ready to populate
itself.
This commit is contained in:
kirby@puppetlabs.com 2018-05-11 13:42:21 -07:00
parent e781ed258b
commit 9bb4df7d8e
11 changed files with 1393 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

115
docs/API.md
View file

@ -1,8 +1,17 @@
### API
# Table of contents
1. [API](#API)
2. [Token operations](#token)
3. [VM operations](#vmops)
4. [Add disks](#adddisks)
5. [VM snapshots](#vmsnapshots)
6. [Status and metrics](#statusmetrics)
7. [Pool configuration](#poolconfig)
### API <a name="API"></a>
vmpooler provides a REST API for VM management. The following examples use `curl` for communication.
#### Token operations
#### Token operations <a name="token"></a>
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.
@ -76,7 +85,7 @@ Enter host password for user 'jdoe':
}
```
#### VM operations
#### VM operations <a name="vmops"></a>
##### GET /vm
@ -230,7 +239,7 @@ $ curl -X DELETE --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6
}
```
#### Adding additional disk(s)
#### Adding additional disk(s) <a name="adddisks"></a>
##### POST /vm/&lt;hostname&gt;/disk/&lt;size&gt;
@ -270,7 +279,7 @@ $ curl --url vmpooler.company.com/api/v1/vm/fq6qlpjlsskycq6
````
#### VM snapshots
#### VM snapshots <a name="vmsnapshots"></a>
##### POST /vm/&lt;hostname&gt;/snapshot
@ -322,7 +331,7 @@ $ curl X POST -H X-AUTH-TOKEN:a9znth9dn01t416hrguu56ze37t790bl --url vmpooler.co
}
````
#### Status and metrics
#### Status and metrics <a name="statusmetrics"></a>
##### GET /status
@ -540,3 +549,97 @@ $ curl -G -d 'from=2015-03-10' -d 'to=2015-03-11' --url vmpooler.company.com/api
]
}
```
#### Managing pool configuration via API <a name="poolconfig"></a>
##### GET /config
Returns the running pool configuration
Responses:
* 200 - OK
* 404 - No configuration found
```
$ curl https://vmpooler.company.com/api/v1/config
```
```json
{
"pool_configuration": [
{
"name": "redhat-7-x86_64",
"template": "templates/redhat-7.2-x86_64-0.0.3",
"folder": "vmpooler/redhat-7-x86_64",
"datastore": "stor1",
"size": 1,
"datacenter": "dc1",
"provider": "vsphere",
"capacity": 1,
"major": "redhat",
"template_ready": true
}
],
"status": {
"ok": true
}
}
```
Note: to enable poolsize and pooltemplate config endpoints it is necessary to set 'experimental_features: true' in your vmpooler configuration. A 405 is returned when you attempt to interact with these endpoints when this configuration option is not set.
##### POST /config/poolsize
Change pool size without having to restart the service.
All pool template changes requested must be for pools that exist in the vmpooler configuration running, or a 404 code will be returned
When a pool size is changed due to the configuration posted a 201 status will be returned. When the pool configuration is valid, but will not result in any changes, 200 is returned.
Pool size configuration changes persist through application restarts, and take precedence over a pool size value configured in the pool configuration provided when the application starts. This persistence is dependent on redis. So, if the redis data is lost then the configuration updates revert to those provided at startup at the next application start.
An authentication token is required in order to change pool configuration when authentication is configured.
Responses:
* 200 - No changes required
* 201 - Changes made on at least one pool with changes requested
* 400 - An invalid configuration was provided causing requested changes to fail
* 404 - An unknown error occurred
* 405 - The endpoint is disabled because experimental features are disabled
```
$ curl -X POST -H "Content-Type: application/json" -d '{"debian-7-i386":"2","debian-7-x86_64":"1"}' --url https://vmpooler.company.com/api/v1/config/poolsize
```
```json
{
"ok": true
}
```
##### POST /config/pooltemplate
Change the template configured for a pool, and replenish the pool with instances built from the new template.
All pool template changes requested must be for pools that exist in the vmpooler configuration running, or a 404 code will be returned
When a pool template is changed due to the configuration posted a 201 status will be returned. When the pool configuration is valid, but will not result in any changes, 200 is returned.
A pool template being updated will cause the following actions, which are logged in vmpooler.log:
* Destroy all instances for the pool template being updated that are in the ready and pending state
* Halt repopulating the pool while creating template deltas for the newly configured template
* Unblock pool population and let the pool replenish with instances based on the newly configured template
Pool template changes persist through application restarts, and take precedence over a pool template configured in the pool configuration provided when the application starts. This persistence is dependent on redis. As a result, if the redis data is lost then the configuration values revert to those provided at startup at the next application start.
An authentication token is required in order to change pool configuration when authentication is configured.
Responses:
* 200 - No changes required
* 201 - Changes made on at least one pool with changes requested
* 400 - An invalid configuration was provided causing requested changes to fail
* 404 - An unknown error occurred
* 405 - The endpoint is disabled because experimental features are disabled
```
$ curl -X POST -H "Content-Type: application/json" -d '{"debian-7-i386":"templates/debian-7-i386"}' --url https://vmpooler.company.com/api/v1/config/pooltemplate
```
```json
{
"ok": true
}
```