vmpooler/vmpooler.yaml.example

---
:providers:
# :providers:
#
# This section contains the VM providers for VMs and Pools
# The currently supported backing services are:
# - vsphere
# - dummy
#
#   - provider_class
#     For multiple providers, specify one of the supported backing services (vsphere or dummy)
#     (optional: will default to it's parent :key: name eg. 'vsphere')
#
#   - purge_unconfigured_folders
#     Enable purging of VMs and folders detected within the base folder path that are not configured for the provider
#     Only a single layer of folders and their child VMs are evaluated from detected base folder paths
#     Nested child folders will not be destroyed. An optional whitelist can be provided to exclude folders
#     A base folder path for 'vmpooler/redhat-7' would be 'vmpooler'
#     Setting this on the provider will enable folder purging for the provider
#     Expects a boolean value
#     (optional; default: false)
#
#   - folder_whitelist
#     Specify folders that are within the base folder path, not in the configuration, and should not be destroyed
#     To exclude 'vmpooler/myfolder' from being destroyed when the base path is 'vmpooler' you would specify 'myfolder' in the whitelist
#     This option is only evaluated when 'purge_unconfigured_folders' is enabled
#     Expects an array of strings specifying the whitelisted folders by name
#     (optional; default: nil)
#
# If you want to support more than one provider with different parameters (server, username or passwords) you have to specify the
# backing service in the provider_class configuration parameter for example 'vsphere' or 'dummy'. Each pool can specify
# the provider to use.
#
# Multiple providers example:

  :vsphere-pdx:
    server: 'vsphere.pdx.example.com'
    username: 'vmpooler-pdx'
    password: 'swimsw1msw!m'
    provider_class: 'vsphere'
  :vsphere-bfs:
    server: 'vsphere.bfs.example.com'
    username: 'vmpooler-bfs'
    password: 'swimsw1msw!m'
    provider_class: 'vsphere'

# :vsphere:
#
# This section contains the server hostname and authentication credentials
# needed for vmpooler to connect to VMware vSphere.
#
# NOTE - To support older configuration files, a :vsphere: configuration section
# will be copied into :providers:/:vsphere: if one does not already exist.
#
# Available configuration parameters:
#
#   - server
#     The FQDN hostname of the VMware vSphere server.
#     (required)
#
#   - username
#     The username used to authenticate VMware vSphere.
#     (required)
#
#   - password
#     The password used to authenticate VMware vSphere.
#     (required)
#
#   - insecure
#     Whether to ignore any HTTPS negotiation errors (e.g. untrusted self-signed certificates)
#     (optional: default false)
#
#   - datacenter
#     The datacenter within vCenter to manage VMs.  This can be overridden in the pool configuration
#     (optional: default is the first datacenter in vSphere)
#
# Example:

  :vsphere:
    server: 'vsphere.example.com'
    username: 'vmpooler'
    password: 'swimsw1msw!m'

# :dummy:
#
# The dummy backing service is a simple text file service that can be used
# to test vmpooler operations in a development or test environment
#
# Available configuration parameters:
#
#   - filename (Optional)
#     The filename used to store the backing text file.  If this is not specified the VM state is only
#     kept in memory, and is lost when the Provider is shutdown
#
#   - connection_pool_size (Optional)
#     The size of the dummy connection pool.  This can be used to simulate constrained provider resources e.g. 200 pools sharing on connection
#     (optional; default 1)
#
#   - connection_pool_timeout (Optional)
#     The number of seconds to wait for a connection object from the pool.  If the timeout is exceeded an error is raised
#     (optional; default 10 seconds)
#
#   - migratevm_couldmove_percent
#     Percent chance that a VM could be moved to another host
#     (optional; default 0%)
#
#   - migratevm_max_time
#     Maximum amount of random time a VM migration action will take in seconds
#     (optional; default 0 seconds)
#
#   - migratevm_fail_percent
#     Percent chance that a VM migration action will fail
#     (optional; default 0%)
#
#   - getvm_poweroff_percent
#     Percent chance that when the VM information is gathered that the VM will be powered off
#     (optional; default 0%)
#
#   - getvm_rename_percent
#     Percent chance that when the VM information is gathered that the VM will be renamed
#     (optional; default 0%)
#
#   - createvm_max_time
#     Maximum amount of random time a VM creation action will take, in seconds
#     (optional; default 0 seconds)
#
#   - createvm_fail_percent
#     Percent chance that a VM creation action will fail
#     (optional; default 0%)
#
#   - createdisk_max_time
#     Maximum amount of random time a VM create disk action will take, in seconds
#     (optional; default 0 seconds)
#
#   - createdisk_fail_percent
#     Percent chance that a VM create disk action will fail
#     (optional; default 0%)
#
#   - createsnapshot_max_time
#     Maximum amount of random time a VM create snapshot action will take, in seconds
#     (optional; default 0 seconds)
#
#   - createsnapshot_fail_percent
#     Percent chance that a VM create snapshot action will fail
#     (optional; default 0%)
#
#   - revertsnapshot_max_time
#     Maximum amount of random time a VM revert snapshot action will take, in seconds
#     (optional; default 0 seconds)
#
#   - revertsnapshot_fail_percent
#     Percent chance that a VM revert snapshot action will fail
#     (optional; default 0%)
#
#   - destroyvm_max_shutdown_time
#     Maximum amount of random time a VM shutdown action will take during destroy, in seconds
#     (optional; default 0 seconds)
#
#   - destroyvm_max_time
#     Maximum amount of random time a VM destroy action will take, in seconds
#     (optional; default 0 seconds)
#
#   - destroyvm_fail_percent
#     Percent chance that a VM destroy action will fail
#     (optional; default 0%)
#
#   - vmready_fail_percent
#     Percent chance that an error is raised when vm_ready? is called
#     (optional; default 0%)

# Example:

  :dummy:
    filename: '/tmp/dummy-backing.yaml'


# :redis:
#
# This section contains the server hostname and authentication credentials
# needed for vmpooler to connect to Redis.
#
# Available configuration parameters:
#
#   - server
#     The FQDN hostname of the Redis server.
#     (optional; default: 'localhost')
#
#   - username
#     The username used to authenticate Redis.
#     (optional)
#
#   - password
#     The password used to authenticate Redis.
#     (optional)
#
#   - data_ttl
#     How long (in hours) to retain metadata in Redis after VM destruction.
#     (default: 168)
#
#   - redis_connection_pool_size
#     Maximum number of connections to utilize for the redis connection pool.
#     (default: 10)
#
#   - redis_connection_pool_timeout
#     How long a task should wait (in seconds) for a redis connection when all connections are in use.
#     (default: 5)
#
#   - reconnect_attempts
#     How many times to retry one redis connection, for example if the host:port is not available
#     The time between attempts starts at 1.5s and increases up to 10s, in such a way that 10 attempts
#     takes about 80s, at which point an error is returned.
#     (default: 10)

# Example:

:redis:
  server: 'redis.example.com'

# :graphs:
#
# This section contains the server and prefix information for a graphite-
# compatible web front-end where graphs may be viewed. This is used by the
# vmpooler dashboard to retrieve statistics and graphs for a given instance.
#
# NOTE: This is not the endpoint for publishing metrics data. See `graphite:`
#       and `statsd:` below.
#
# NOTE: If `graphs:` is not set, for legacy compatibility, `graphite:` will be
#       consulted for `server`/`prefix` information to use in locating a
#       graph server for our dashboard.  `graphs:` is recommended over
#       `graphite:`
#
#
# Available configuration parameters:
#
#
#   - server
#     The FQDN hostname of the statsd daemon.
#     (required)
#
#   - prefix
#     The prefix to use while storing statsd data.
#     (optional; default: 'vmpooler')

# :statsd:
#
# This section contains the connection information required to store
# historical data via statsd.  This is mutually exclusive with graphite
# and prometheus and takes precedence.
#
# Available configuration parameters:
#
#   - server
#     The FQDN hostname of the statsd daemon.
#     (required)
#
#   - prefix
#     The prefix to use while storing statsd data.
#     (optional; default: 'vmpooler')
#
#   - port
#     The UDP port to communicate with the statsd daemon.
#     (optional; default: 8125)

# Example:

:statsd:
  server: 'statsd.example.com'
  prefix: 'vmpooler'
  port: 8125

# :graphite:
#
# This section contains the connection information required to store
# historical data in an external Graphite database.  This is mutually exclusive
# with statsd and prometheus - i.e. only one can be selected.
#
# Available configuration parameters:
#
#   - server
#     The FQDN hostname of the Graphite server.
#     (required)
#
#   - prefix
#     The prefix to use while storing Graphite data.
#     (optional; default: 'vmpooler')
#
#   - port
#     The TCP port to communicate with the graphite server.
#     (optional; default: 2003)

# Example:

:graphite:
  server: 'graphite.example.com'

# :prometheus
#
# This section contains the connection information required to store
# historical data in an external Graphite database.  This is mutually exclusive
# with statsd and graphite - i.e. only one can be selected.
#
# Available configuration parameters:
#
#   - prefix
#     The prefix for this vmpooler instance.
#     (optional; default: 'vmpooler')
#
#   - prometheus_prefix
#     The prefix to use while storing prometheus data.
#     (optional; default: 'vmpooler')
#
#   - prometheus_endpoint
#     The metrics endpoint on the vmpooler server
#     (optional; default: '/prometheus')

# Example:

:prometheus:
  prefix: 'staging'
  prometheus_prefix: 'vmpooler'
  prometheus_endpoint: '/prometheus'


# :auth:
#
# This section contains information related to authenticating users
# for token operations.
#
# Supported Auth Providers:
#   - Dummy
#   - LDAP
#
# - Dummy Auth Provider
# The Dummy Authentication provider should only be used during development or testing
# If the Username and Password are different then validation succeeds
# If the Username and Password are the same then validation fails
#
# Example:
# :auth:
#   provider: 'dummy'
#
# - LDAP Auth Provider
# The LDAP Authentication provider will validate usernames and passwords against an
# existing LDAP service
#
# Available configuration parameters:
#
#   - host
#     The FQDN hostname of the LDAP server.
#
#   - port
#     The port used to connect to the LDAP service.
#     (optional; default: '389')
#
#   - base
#     The base DN used for LDAP searches.
#     This can be a string providing a single DN, or an array of DNs to search.
#
#   - user_object
#     The LDAP object-type used to designate a user object.
#
# Example:
# :auth:
#   provider: 'ldap'
#   :ldap:
#     host: 'localhost'
#     port: 389
#     base: 'ou=users,dc=company,dc=com'
#     user_object: 'uid'

:auth:
  provider: 'ldap'
  :ldap:
    host: 'ldap.example.com'
    port: 389
    base: 'ou=users,dc=company,dc=com'
    user_object: 'uid'

# :tagfilter:
#
# Filter tags by regular expression.

# Example:
#
# This example demonstrates discarding everything after a '/' character for
# the 'url' tag, transforming 'foo.com/something.html' to 'foo.com'.

:tagfilter:
  url: '(.*)\/'

# :config:
#
# This section contains global configuration information.
#
# Available configuration parameters:
#
#   - site_name
#     The name of your deployment.
#     (optional; default: 'vmpooler')
#
#   - logfile
#     The path to vmpooler's log file.
#     (optional; default: '/var/log/vmpooler.log')
#
#   - clone_target
#     The target cluster VMs are cloned into (host with least VMs chosen)
#     (optional; default: same cluster/host as origin template)
#
#   - task_limit
#     The number of concurrent VM creation tasks to perform.
#     (default: 10)
#
#   - ondemand_clone_limit
#     The number of concurrent VM creation tasks to perform for ondemand VM requests.
#     (default: 10)
#
#   - timeout
#     How long (in minutes) before marking a clone in 'pending' queues as 'failed' and retrying.
#     (default: 15)
#
#   - vm_checktime
#     How often (in minutes) to check the sanity of VMs in 'ready' queues.
#     (default: 1)
#
#   - vm_lifetime
#     How long (in hours) to keep VMs in 'running' queues before destroying.
#     (optional; default: '24')
#
#   - vm_lifetime_auth
#     Same as vm_lifetime, but applied if a valid authentication token is
#     included during the request.
#
#   - allowed_tags
#     If set, restricts tags to those specified in this array.
#
#   - domain
#     If set, returns a top-level 'domain' JSON key in POST requests
#
#   - prefix
#     If set, prefixes all created VMs with this string.  This should include
#     a separator.
#     (optional; default: '')
#
#   - migration_limit (Only affects vSphere Provider)
#     When set to any value greater than 0 enable VM migration at checkout.
#     When enabled this capability will evaluate a VM for migration to a different host when it is requested
#     in an effort to maintain a more even distribution of load across compute resources.
#     The migration_limit ensures that no more than the specified migrations will take place at any one time.
#
#   - max_tries
#     Set the max number of times a connection should retry in VM providers.
#     This optional setting allows a user to dial in retry limits to
#     suit your environment.
#     (optional; default: 3)
#
#   - retry_factor
#     When retrying, each attempt sleeps for the try count * retry_factor.
#     Increase this number to lengthen the delay between retry attempts.
#     This is particularly useful for instances with a large number of pools
#     to prevent a thundering herd when retrying connections.
#     (optional; default: 10)
#
#   - check_loop_delay_min (optional; default: 5) seconds
#   - check_loop_delay_max (optional; default: 60) seconds
#   - check_loop_delay_decay (optional; default: 2.0) Must be greater than 1.0
#     Each pool is polled on a schedule to check whether there are any tasks to perform, for example, provision
#     new VMs to fill a pool, or destroy VMs which are no longer required. By default this value is every 5 seconds.
#     However, with a large number of pools, this can cause the provider to be issuing many, many requests which
#     can cause performance problems, for example, vSphere recommends no more than 100 active connections per vCenter
#     instance. But if you increase the check interval to a large number, then vmpooler will appear to be slow to
#     perform tasks.  These settings can be used to tune how often the provider is polling for changes to a pool.
#     This is done by increasing the polling period when the pool is stable or when unimportant tasks are being
#     performed.  The polling period is decreased back to the minimum when important tasks happen (newly discovered VMs,
#     creating new VMs and checking for VMs that have completed cloning but not ready).  This means the pools are
#     checked appropriately during important events, but as the pool stabilizes it does not need to be checked as often.
#       - The check_loop_delay_min setting determines the smallest period of time between polls, in seconds.
#       - The check_loop_delay_max setting determines the longest period of time between polls, in seconds.
#         Must be greater than or equal to check_loop_delay_min or it will be set to check_loop_delay_min.
#       - The check_loop_delay_decay setting determines how quickly the delay moves from minimum to maximum. So a value
#         of 2.0 means each time the pool is checked and nothing important happens, the loop delay is multiplied by 2.0,
#         for example, the first time is 2 seconds, then 4, 8, 16 etc. until it reaches check_loop_delay_max.
#         This value must be greater than 1.0.
#
#   - manage_host_selection (Only affects vSphere Provider)
#     Allow host selection to be determined by vmpooler
#     Hosts are selected based on current CPU utilization and cycled between when there are multiple targets
#     The hosts tracking list is refreshed on an interval when a host is requested determined by host_selection_max_age
#     (optional; default: false)
#
#   - create_folders (Only affects vSphere Provider)
#     Create the pool folder specified in the pool configuration
#     Note: this will only create the last folder when it does not exist. It will not create any parent folders
#     (optional; default: false)
#
#   - create_template_delta_disks (Only affects vSphere Provider)
#     Create backing delta disks for the specified templates to support creating linked clones.
#     (optional; default: false)
#
#   - host_selection_max_age (Only affects vSphere Provider)
#     The maximum age of the provider_hosts list in seconds
#     The list is repopulated when the difference between now and the last time
#     checking of host utilization finished is greater than the value set.
#     (optional; default: 60)
#
#   - utilization_limit (Only affects vSphere Provider)
#     The maximum utilization of host resources allowed before the host
#     is excluded from consideration for VM deployment
#     The value represents a percentage and applies to both memory and CPU
#     (optional; default: 90)
#
#   - experimental_features (Only affects API config endpoints)
#     Enable experimental API capabilities such as changing pool template and size without application restart
#     Expects a boolean value
#     (optional; default: false)
#
#   - purge_unconfigured_folders (vSphere Provider only)
#     Enable purging of VMs and folders detected within the base folder path that are not configured for the provider
#     Only a single layer of folders and their child VMs are evaluated from detected base folder paths
#     A base folder path for 'vmpooler/redhat-7' would be 'vmpooler'
#     When enabled in the global configuration then purging is enabled for all providers
#     Expects a boolean value
#     (optional; default: false)
#
#   - backend_weight
#     A hash of clone_target values with weights assigned to allow selecting VMs by alias with selection probability
#     This setting is only used when there is a pool title and matching alias that both have values set in backend weight.
#     When both conditions are met then the next VM is selected by probability using backend weight. When weight is not set
#     in this configuration then distribution of load is random.
#     Expects a hash value
#     (optional)
#
#   - usage_stats
#     Enable shipping of VM usage stats
#     When enabled a metric is emitted when a user requested to allocate and destroy a VM. Tags are inspected and used to organize
#     shipped metrics if there is a jenkins_build_url tag set for the VM.
#     Without the jenkins_build_url tag set the metric will be sent as "usage.$user.$operation.$pool_name".
#     When the jenkins_build_url tag is set the metric will be sent with additional data. Here is an example
#     based off of the following URL, and requested by the user ABS;
#     https://jenkins.example.com/job/platform_puppet-agent-extra_puppet-agent-integration-suite_pr/RMM_COMPONENT_TO_TEST_NAME=puppet,SLAVE_LABEL=beaker,TEST_TARGET=redhat7-64a/824/
#     "usage.$user.$instance.$value_stream.$branch.$project.$job_name.$component_to_test.$operation.$pool_name", which translates to
#     "usage.$user.jenkins_example_com.platform.pr.puppet-agent-extra.puppet-agent-integration-suite.puppet.$pool_name"
#     Expects a boolean value
#     (optional; default: false)
#
#   - request_logger
#     Enable API Request logging to the logger
#     When enabled all requests to the API are written to the standard logger.
#     Expects a boolean value
#     (optional; default: false)
#
#   - max_lifetime_upper_limit
#     Sets a lifetime upper limit (in hours) for how long the vm lifetime can be set via the API. Lifetime can be set and extended
#     so this configuration is used to enforce an upper limit to both the initial lifetime request and/or the extended
#     lifetime (by checking how long it has already been running).
#     (optional; default: unlimited)
#
#   - extra_config
#     Specify additional application configuration files
#     The argument can accept a full path to a file, or multiple files comma separated.
#     Expects a string value
#     (optional)
#
#   - max_ondemand_instances_per_request
#     The maximum number of instances any individual ondemand request may contain per pool.
#     (default: 10)
#
#   - ondemand_request_ttl
#     The amount of time (in minutes) to give for a ondemand request to be fulfilled before considering it to have failed.
#     (default: 5)
#
#   - ready_ttl
#     How long (in minutes) a ready VM should stay in the ready queue.
#     (default: 60)
#
# Example:

:config: site_name: 'vmpooler'
  logfile: '/var/log/vmpooler.log'
  task_limit: 10
  timeout: 15
  vm_checktime: 1
  vm_lifetime: 12
  vm_lifetime_auth: 24
  allowed_tags:
    - 'created_by'
    - 'project'
  domain: 'example.com'
  prefix: 'poolvm-'
  experimental_features: true
  backend_weight:
    'backend1': 60
    'backend2': 40

# :pools:
#
# This section contains a list of virtual machine 'pools' for vmpooler to
# create and maintain.
#
# Available configuration parameters (per-pool):
#
#   - name
#     The name of the pool.
#     (required)
#
#   - alias
#     Other names this pool can be requested as.
#     (optional)
#
#   - template
#     The template or virtual machine target to spawn clones from.
#     (required)
#
#   - size
#     The number of waiting VMs to keep in a pool.
#     (required)
#
#   - provider
#     The name of the VM provider which manage this pool.  This should match
#     a name in the :providers: section above e.g. vsphere
#     (required; will default to vsphere for backwards compatibility)
#     If you have more than one provider, this is where you would choose which
#     one to use for this pool
#
#   - clone_target
#     Per-pool option to override the global 'clone_target' cluster.
#     (optional)
#
#   - timeout
#     How long (in minutes) before marking a clone in 'pending' queues as 'failed' and retrying.
#     This setting overrides any globally-configured timeout setting.
#     (optional; default: '15')
#
#   - ready_ttl
#     How long (in minutes) to keep VMs in 'ready' queues before destroying.
#     (optional; default: no limit)
#
#   - check_loop_delay_min (optional; default: 5) seconds
#   - check_loop_delay_max (optional; default: same as check_loop_delay_min) seconds
#   - check_loop_delay_decay (optional; default: 2.0) Must be greater than 1.0
#     See the :config: section for information about these settings
#
#   Provider specific pool settings
#     vSphere provider
#     - folder
#       The vSphere 'folder' destination for spawned clones.
#       (required)
#
#     - datastore
#       The vSphere 'datastore' destination for spawned clones.
#       (required)
#
#     - datacenter
#       The datacenter within vCenter to manage VMs.
#       (optional: default is the first datacenter in vSphere)
#
#     - snapshot_mainMem_ioBlockPages
#       Provisions VMs with the option "mainMem.ioBlockPages". This setting can be useful
#       (paired with mainMem.iowait below) for tuning the performance of snapshot management actions.
#       See: https://kb.vmware.com/s/article/76687
#
#     - snapshot_mainMem_iowait
#       Provisions VMs with the option "mainMem.iowait". This setting can be useful
#       for tuning the performance of snapshot management actions
#
# Example:

:pools:
  - name: 'debian-7-i386'
    alias: [ 'debian-7-32' ]
    template: 'Templates/debian-7-i386'
    folder: 'Pooled VMs/debian-7-i386'
    datastore: 'vmstorage'
    size: 5
    timeout: 15
    ready_ttl: 1440
    provider: vsphere
    create_linked_clone: true
  - name: 'debian-7-x86_64'
    alias: [ 'debian-7-64', 'debian-7-amd64' ]
    template: 'Templates/debian-7-x86_64'
    folder: 'Pooled VMs/debian-7-x86_64'
    datastore: 'vmstorage'
    size: 5
    timeout: 15
    ready_ttl: 1440
    provider: vsphere
    create_linked_clone: false
    snapshot_mainMem_ioBlockPages: '2048'
    snapshot_mainMem_iowait: '0'