The only good bug is a dead bug.
This project provides a batteries-included Vagrant environment for debugging Puppet powered infrastructures.
Getting the debugging kit ready for use consists of three steps:
-
Ensure the proper Vagrant plugins are installed.
-
Create VM definitions in
config/vms.yaml
. -
Clone Puppet Open Source projects to
src/puppetlabs
(optional). -
Install Bolt to enable bolt provisioning (optional).
Rake tasks and templates are provided to help with all three steps.
Two methods are available depending on whether a global Vagrant installation, such as provided by the official packages from vagrantup.com, is in use:
Debugging Kit virtual machine definitions are stored in the file
config/vms.yaml
and an example is provided as
config/vms.yaml.example
.
The example can simply be copied to config/vms.yaml
, but it contains a large
number of VM definitions which adds some notable lag to Vagrant start-up times.
Start-up lag can be remedied by pruning unwanted definitions after copying the
example file.
The poss-envpuppet
role is designed to run Puppet in guest
machines directly from Git clones located on the host machine at
src/puppetlabs/
. This role is useful for inspecting and debugging changes in
behavior between versions without re-installing packages.
The required Git clones can be created by running the following Rake task:
rake setup:poss
Use of the debugging kit consists of:
-
Creating a new VM definition in
config/vms.yaml
.- The
box:
component determines which Vagrant basebox will be used.
- The
-
Assigning a list of "roles" that customize the VM behavior.
- The role list can be viewed as a stack―the last entry is applied first.
- Most VMs start with the
base
role which auto-assigns an IP address and sets up network connectivity. - The default roles can be found in
data/puppet_debugging_kit/roles.yaml
, and are explained in more detail below.
-
Optionally using "bolt based provisioning"
- Building roles to call Bolt modules.
- Roles can contain triggers or provisioners to initiate plans, tasks, or commands.
- An example set are found in
config/bolt_vms.yaml.example
. - An example Puppetfile is found in
Puppetfile.example
.
-
base
: Auto-assigns an IP address and sets up network -
windows
: Setswinrm
as the communicator and port-forwards SSH and RDP -
el-stop-firewall
: Stopsiptables
(<=EL6) orfirewalld
(>=EL7) -
el-fix-path
: Adds/usr/local/bin
to$PATH
-
el-6-epel
: Adds EPEL repos to EL6 -
1gb-memory
: VM uses 1GB RAM -
2gb-memory
: VM uses 2GB RAM -
4gb-memory
: VM uses 4GB RAM -
small-size
: equivalent to1gb-memory
-
large-size
: equivalent to4gb-memory
Several roles are available to assist with creating PE machines:
-
pe-<version>-master
: Performs an all-in-one master installation of PE<version>
on the guest VM.- When specifying the version number, remove any separators such that
3.2.1
becomes321
. - The PE console is configured with username
[email protected]
and passwordpuppetlabs
.
- When specifying the version number, remove any separators such that
-
- There can only be one replica, and this only works with 2016.5+
There are a few roles that assist with creating VMs that run Puppet Open Source Software (POSS).
-
The required Git clones can be created by running the following Rake task:
rake setup:poss
There are also roles for legacy POSS software:
-
poss-pc1-repos
: Installs the PuppetLabs PC1 repository -
el-6-ruby193
: Provides Ruby 1.9.3 on EL6 -
el-6-ruby200
: Provides Ruby 2.0.0 on EL6 (requires the roleel-6-epel
)
Bolt modules can now be used to do the provisoning and configuration of the machines. An example set of plans have been provided in the Puppetfile.example
which will enable provisioning a PE infrastructure. To use the bolt plans from the Puppetfile
the following steps can be followed.
- Install Bolt as needed.
- Copy the
Puppetfile.example
toPuppetfile
and add any additional modules. - Install the modules with
vagrant bolt puppetfile install
. - Copy the
config/bolt_vms.yaml.example
toconfig/bolt_vms.yaml
. - Update any parameters in the
roles
of theconfig/bolt_vms.yaml
to specify PE versions or download locations.
The example VMs in the config/bolt_vms.yaml
use custom roles at the bottom of the file. There are roles to deploy a PE master, agent, and compiler. See the deploy_pe
module for more parameter information.
- pe_master Installs the PE master on the VM using the specified parameters.
- pe_compiler Installs a PE compiler from the PE master.
- pe_agent Installs a PE agent from the PE master.
The roles define provisioners and triggers. More information on how to use the bolt triggers and provisioners can be found in the vagrant-bolt
documentation.
This is currently only for *nix vagrant hosts. Windows vagrant host compatibility is in progress in the example plans.
The debugging kit can be thought of as a library of configuration and data for Oscar. Data is loaded from two sets of YAML files:
config
└── *.yaml # <-- User-specific customizations
data
└── puppet_debugging_kit
└── *.yaml # <-- The debugging kit library
Everything under data/puppet_debugging_kit
is loaded first.
In order to avoid merge conflicts when the library is updated, these files should never be edited unless you plan to submit your changes as a pull request.
The contents of config/*.yaml
are loaded next and can be used to extend or override anything provided by data/puppet_debugging_kit
.
These files are not tracked by Git and are where user-specific customizations should go.