Skip to content
Provide configurable 'pools' of instantly-available (running) virtual machines
Ruby JavaScript Other
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
.dependabot Add Dependabot to keep gems updated Mar 17, 2020
bin Merge pull request #360 from highb/2020-03-05_unsafe_rubocop_fixes Mar 6, 2020
docker Remove providers addition to docker-compose.yml Mar 17, 2020
docs (POOLER-157) Add extra_config option to vmpooler Mar 5, 2020
examples (POOLER-133) Identify when a ready VM has failed Dec 3, 2018
lib (GEM) update vmpooler version to 0.12.0 May 28, 2020
scripts Update to generic launcher Jun 8, 2018
spec Enable support for multiple user objects May 28, 2020
.dockerignore Add a .dockerignore file Mar 12, 2020
.gitignore Adds a gemspec file Jun 12, 2018
.rubocop.yml Rubocop rule updates Mar 6, 2020
.rubocop_todo.yml Rubocop 0.80 updates to rubocop configs Mar 4, 2020
.travis.yml Require rubocop checks in Travis Mar 6, 2020 Update CHANGELOG for 0.11.1 Mar 17, 2020
CODEOWNERS (MAINT) Update CODEOWNERS Apr 16, 2020 (doc) Add changelog and contributing guidlines Jul 16, 2018
Gemfile Update rake requirement from ~> 12.3 to >= 12.3, < 14.0 Mar 17, 2020
LICENSE Adds a new mechanism to load providers from any gem or file path. (#263) Jul 24, 2018 Fix Dockerfile link in readme and add note about http requests for dev ( Mar 4, 2019
Rakefile (maint) Only load rubocop rake tasks if gem is available Feb 22, 2017
vmpooler.gemspec rake gemspec dep in ~> format instead of range Mar 17, 2020
vmpooler.yaml.dummy-example Fix Dockerfile link in readme and add note about http requests for dev ( Mar 4, 2019
vmpooler.yaml.example (POOLER-157) Add extra_config option to vmpooler Mar 5, 2020



vmpooler provides configurable 'pools' of instantly-available (running) virtual machines.


At Puppet, Inc. we run acceptance tests on thousands of disposable VMs every day. Dynamic cloning of VM templates initially worked fine for this, but added several seconds to each test run and was unable to account for failed clone tasks. By pushing these operations to a backend service, we were able to both speed up tests and eliminate test failures due to underlying infrastructure failures.



vmpooler is available as a gem

To use the gem gem install vmpooler


Vmpooler requires a Redis server. This is the datastore used for vmpooler's inventory and queueing services.


Configuration for vmpooler may be provided via environment variables, or a configuration file.

Please see this configuration document for more details about configuring vmpooler via environment variables.

The following YAML configuration sets up two pools, debian-7-i386 and debian-7-x86_64, which contain 5 running VMs each:

    server: ''
    username: 'vmpooler'
    password: 'swimsw1msw!m'

  server: ''

  logfile: '/var/log/vmpooler.log'

  - name: 'debian-7-i386'
    template: 'Templates/debian-7-i386'
    folder: 'Pooled VMs/debian-7-i386'
    pool: 'Pooled VMs/debian-7-i386'
    datastore: 'vmstorage'
    size: 5
    provider: vsphere
  - name: 'debian-7-x86_64'
    template: 'Templates/debian-7-x86_64'
    folder: 'Pooled VMs/debian-7-x86_64'
    pool: 'Pooled VMs/debian-7-x86_64'
    datastore: 'vmstorage'
    size: 5
    provider: vsphere

See the provided YAML configuration example, vmpooler.yaml.example, for additional configuration options and parameters or for supporting multiple providers.

Running via Docker

A Dockerfile is included in this repository to allow running vmpooler inside a Docker container. A configuration file can be used via volume mapping, and specifying the destination as the configuration file via environment variables, or the application can be configured with environment variables alone. The Dockerfile provides an entrypoint so you may choose whether to run API, or manager services. The default behavior will run both. To build and run:

docker build -t vmpooler . && docker run -e VMPOOLER_CONFIG -p 80:4567 -it vmpooler

To run only the API and dashboard

docker run -p 80:4567 -it vmpooler api

To run only the manager component

docker run -it vmpooler manager


A docker-compose file is provided to support running vmpooler easily via docker-compose.

docker-compose -f docker/docker-compose.yml up

Running Docker inside Vagrant

A vagrantfile is included in this repository. Please see vagrant instructions for details.

API and Dashboard

vmpooler provides an API and web front-end (dashboard) on port :4567. See the provided YAML configuration example, vmpooler.yaml.example, to specify an alternative port to listen on.


vmpooler provides a REST API for VM management. See the API documentation for more information.


A dashboard is provided to offer real-time statistics and historical graphs. It looks like this:


Graphite is required for historical data retrieval. See the provided YAML configuration example, vmpooler.yaml.example, for details.

Command-line Utility

  • The CLI utility provides easy access to the vmpooler service. The tool is cross-platform and written in Python.
  • vmfloaty is a ruby based CLI tool and scripting library written in ruby.

Vagrant plugin

Development and further documentation

For more information about setting up a development instance of vmpooler or other subjects, see the docs/ directory.

Build status

Build Status


vmpooler is distributed under the Apache License, Version 2.0. See the LICENSE file for more details.

You can’t perform that action at this time.