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
docs/API.md
Normal file
542
docs/API.md
Normal file
|
|
@ -0,0 +1,542 @@
|
|||
### 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": { }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
5
docs/README.md
Normal file
5
docs/README.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Documentation for vmpooler
|
||||
|
||||
|
||||
* [Setting up a Development Environment](dev-setup.md)
|
||||
* [API Documentation](API.md)
|
||||
227
docs/dev-setup.md
Normal file
227
docs/dev-setup.md
Normal file
|
|
@ -0,0 +1,227 @@
|
|||
# Setting up a vmpooler development environment
|
||||
|
||||
## Requirements
|
||||
|
||||
* Supported on OSX, Windows and Linux
|
||||
|
||||
* Ruby or JRuby
|
||||
|
||||
Note - Ruby 1.x support will be removed so it is best to use more modern ruby versions
|
||||
|
||||
Note - It is recommended to user Bundler instead of installing gems into the system repository
|
||||
|
||||
* A local Redis server
|
||||
|
||||
Either a containerized instance of Redis or a local version is fine.
|
||||
|
||||
## Setup source and ruby
|
||||
|
||||
* Clone repository, either from your own fork or the original source
|
||||
|
||||
* Perform a bundle install
|
||||
|
||||
```
|
||||
~/ > git clone https://github.com/puppetlabs/vmpooler.git
|
||||
Cloning into 'vmpooler'...
|
||||
remote: Counting objects: 3411, done.
|
||||
...
|
||||
|
||||
~/ > cd vmpooler
|
||||
|
||||
~/vmpooler/ > bundle install
|
||||
Fetching gem metadata from https://rubygems.org/.........
|
||||
Fetching version metadata from https://rubygems.org/..
|
||||
Resolving dependencies...
|
||||
Installing rake 12.0.0
|
||||
...
|
||||
Bundle complete! 16 Gemfile dependencies, 37 gems now installed.
|
||||
```
|
||||
|
||||
## Setup environment variables
|
||||
|
||||
### `VMPOOLER_DEBUG`
|
||||
|
||||
Setting the `VMPOOLER_DEBUG` environment variable will instruct vmpooler to:
|
||||
|
||||
* Output log messages to STDOUT
|
||||
|
||||
* Allow the use of the dummy authentication method
|
||||
|
||||
* Add interrupt traps so you can stop vmpooler when run interactively
|
||||
|
||||
Linux, OSX
|
||||
```bash
|
||||
~/vmpooler/ > export VMPOOLER_DEBUG=true
|
||||
```
|
||||
|
||||
Windows (PowerShell)
|
||||
```powershell
|
||||
C:\vmpooler > $ENV:VMPOOLER_DEBUG = 'true'
|
||||
```
|
||||
|
||||
|
||||
### `VMPOOLER_CONFIG`
|
||||
|
||||
When `VMPOOLER_CONFIG` is set, vmpooler will read its configuration from the content of the environment variable instead of from the `vmpooler.yaml` configuration file.
|
||||
|
||||
Note that this variable does not point a different configuration file, but stores the contents of a configuration file.
|
||||
|
||||
|
||||
## Setup vmpooler Configuration
|
||||
|
||||
You can either create a `vmpooler.yaml` file or set the `VMPOOLER_CONFIG` environment variable with the equivalent content.
|
||||
|
||||
Example minimal configuration file:
|
||||
```yaml
|
||||
---
|
||||
:providers:
|
||||
:dummy:
|
||||
|
||||
:redis:
|
||||
server: 'localhost'
|
||||
|
||||
:auth:
|
||||
provider: dummy
|
||||
|
||||
:tagfilter:
|
||||
url: '(.*)\/'
|
||||
|
||||
:config:
|
||||
site_name: 'vmpooler'
|
||||
# Need to change this on Windows
|
||||
logfile: '/var/log/vmpooler.log'
|
||||
task_limit: 10
|
||||
timeout: 15
|
||||
vm_checktime: 15
|
||||
vm_lifetime: 12
|
||||
vm_lifetime_auth: 24
|
||||
allowed_tags:
|
||||
- 'created_by'
|
||||
- 'project'
|
||||
domain: 'company.com'
|
||||
prefix: 'poolvm-'
|
||||
|
||||
# Uncomment the lines below to suppress metrics to STDOUT
|
||||
# :statsd:
|
||||
# server: 'localhost'
|
||||
# prefix: 'vmpooler'
|
||||
# port: 8125
|
||||
|
||||
:pools:
|
||||
- name: 'pool01'
|
||||
size: 5
|
||||
provider: dummy
|
||||
- name: 'pool02'
|
||||
size: 5
|
||||
provider: dummy
|
||||
```
|
||||
|
||||
## Running vmpooler locally
|
||||
|
||||
* Run `bundle exec ruby vmpooler`
|
||||
|
||||
If using JRuby, you may need to use `bundle exec jruby vmpooler`
|
||||
|
||||
You should see output similar to:
|
||||
```
|
||||
~/vmpooler/ > bundle exec ruby vmpooler
|
||||
[2017-06-16 14:50:31] starting vmpooler
|
||||
[2017-06-16 14:50:31] [!] Creating provider 'dummy'
|
||||
[2017-06-16 14:50:31] [dummy] ConnPool - Creating a connection pool of size 1 with timeout 10
|
||||
[2017-06-16 14:50:31] [*] [disk_manager] starting worker thread
|
||||
[2017-06-16 14:50:31] [*] [snapshot_manager] starting worker thread
|
||||
[2017-06-16 14:50:31] [*] [pool01] starting worker thread
|
||||
[2017-06-16 14:50:31] [*] [pool02] starting worker thread
|
||||
[2017-06-16 14:50:31] [dummy] ConnPool - Creating a connection object ID 1784
|
||||
== Sinatra (v1.4.8) has taken the stage on 4567 for production with backup from Puma
|
||||
*** SIGUSR2 not implemented, signal based restart unavailable!
|
||||
*** SIGUSR1 not implemented, signal based restart unavailable!
|
||||
*** SIGHUP not implemented, signal based logs reopening unavailable!
|
||||
Puma starting in single mode...
|
||||
* Version 3.9.1 (ruby 2.3.1-p112), codename: Private Caller
|
||||
* Min threads: 0, max threads: 16
|
||||
* Environment: development
|
||||
* Listening on tcp://0.0.0.0:4567
|
||||
Use Ctrl-C to stop
|
||||
[2017-06-16 14:50:31] [!] [pool02] is empty
|
||||
[2017-06-16 14:50:31] [!] [pool01] is empty
|
||||
[2017-06-16 14:50:31] [ ] [pool02] Starting to clone 'poolvm-nexs1w50m4djap5'
|
||||
[2017-06-16 14:50:31] [ ] [pool01] Starting to clone 'poolvm-r543eibo4b6tjer'
|
||||
[2017-06-16 14:50:31] [ ] [pool01] Starting to clone 'poolvm-neqmu7wj7aukyjy'
|
||||
[2017-06-16 14:50:31] [ ] [pool02] Starting to clone 'poolvm-nsdnrhhy22lnemo'
|
||||
[2017-06-16 14:50:31] [ ] [pool01] 'poolvm-r543eibo4b6tjer' is being cloned from ''
|
||||
[2017-06-16 14:50:31] [ ] [pool01] 'poolvm-neqmu7wj7aukyjy' is being cloned from ''
|
||||
[2017-06-16 14:50:31] [ ] [pool02] 'poolvm-nexs1w50m4djap5' is being cloned from ''
|
||||
[2017-06-16 14:50:31] [ ] [pool01] Starting to clone 'poolvm-edzlp954lyiozli'
|
||||
[2017-06-16 14:50:31] [ ] [pool01] Starting to clone 'poolvm-nb0uci0yrwbxr6x'
|
||||
[2017-06-16 14:50:31] [ ] [pool02] Starting to clone 'poolvm-y2yxgnovaneymvy'
|
||||
[2017-06-16 14:50:31] [ ] [pool01] Starting to clone 'poolvm-nur59d25s1y8jko'
|
||||
...
|
||||
```
|
||||
|
||||
### Common Errors
|
||||
|
||||
* Forget to set VMPOOLER_DEBUG environment variable
|
||||
|
||||
vmpooler will fail to start with an error similar to below
|
||||
```
|
||||
~/vmpooler/ > bundle exec ruby vmpooler
|
||||
|
||||
~/vmpooler/lib/vmpooler.rb:44:in `config': Dummy authentication should not be used outside of debug mode; please set environment variable VMPOOLER_DEBUG to 'true' if you want to use dummy authentication (RuntimeError)
|
||||
from vmpooler:8:in `<main>'
|
||||
...
|
||||
```
|
||||
|
||||
* Error in vmpooler configuration
|
||||
|
||||
If there is an error in the vmpooler configuration file, or any other fatal error in the Pool Manager, vmpooler will appear to be running but no log information is displayed. This is due to the error not being displayed until you press `Ctrl-C` and then suddenly you can see the cause of the issue.
|
||||
|
||||
For example, when running vmpooler on Windows, but with a unix style filename for the vmpooler log
|
||||
|
||||
```powershell
|
||||
C:\vmpooler > bundle exec ruby vmpooler
|
||||
[2017-06-16 14:49:57] starting vmpooler
|
||||
== Sinatra (v1.4.8) has taken the stage on 4567 for production with backup from Puma
|
||||
*** SIGUSR2 not implemented, signal based restart unavailable!
|
||||
*** SIGUSR1 not implemented, signal based restart unavailable!
|
||||
*** SIGHUP not implemented, signal based logs reopening unavailable!
|
||||
Puma starting in single mode...
|
||||
* Version 3.9.1 (ruby 2.3.1-p112), codename: Private Caller
|
||||
* Min threads: 0, max threads: 16
|
||||
* Environment: development
|
||||
* Listening on tcp://0.0.0.0:4567
|
||||
Use Ctrl-C to stop
|
||||
|
||||
# [ NOTHING ELSE IS LOGGED ]
|
||||
```
|
||||
|
||||
Once `Ctrl-C` is pressed the error is shown
|
||||
|
||||
```powershell
|
||||
...
|
||||
== Sinatra has ended his set (crowd applauds)
|
||||
Shutting down.
|
||||
C:/tools/ruby2.3.1x64/lib/ruby/2.3.0/open-uri.rb:37:in `initialize': No such file or directory @ rb_sysopen - /var/log/vmpooler.log (Errno::ENOENT)
|
||||
from C:/tools/ruby2.3.1x64/lib/ruby/2.3.0/open-uri.rb:37:in `open'
|
||||
from C:/tools/ruby2.3.1x64/lib/ruby/2.3.0/open-uri.rb:37:in `open'
|
||||
from C:/vmpooler/lib/vmpooler/logger.rb:17:in `log'
|
||||
from C:/vmpooler/lib/vmpooler/pool_manager.rb:709:in `execute!'
|
||||
from vmpooler:26:in `block in <main>'
|
||||
```
|
||||
|
||||
## Default vmpooler URLs
|
||||
|
||||
| Endpoint | URL |
|
||||
|-----------|----------------------------------------------------------------------|
|
||||
| Dashboard | [http://localhost:4567/dashboard/](http://localhost:4567/dashboard/) |
|
||||
| API | [http://localhost:4567/api/v1]([http://localhost:4567/api/v1) |
|
||||
|
||||
## Use the vmpooler API locally
|
||||
|
||||
Once a local vmpooler instance is running you can use any tool you need to interact with the API. The dummy authentication provider will allow a user to connect if the username and password are not the same:
|
||||
|
||||
* Authentication is successful for username `Alice` with password `foo`
|
||||
|
||||
* Authentication will fail for username `Alice` with password `Alice`
|
||||
|
||||
Like normal vmpooler, tokens will be created for the user and can be used for regular vmpooler operations.
|
||||
Loading…
Add table
Add a link
Reference in a new issue