Puppi One and Puppi module written by Alessandro Franceschi / al @ lab42.it
Puppi Gem by Celso Fernandez / Zertico
Source: www.example42.com
Licence: Apache 2
Puppi is a Puppet module and a CLI command. It’s data is entirely driven by Puppet code. It can be used to standardize and automate the deployment of web applications or to provides quick and standard commands to query and check your system’s resources
Its structure provides FULL flexibility on the actions required for virtually any kind of application deployment and information gathering.
The module provides:
-
Old-Gen and Next-Gen Puppi implementation
-
A set of scripts that can be used in chain to automate any kind of deployment
-
Puppet defines that make it easy to prepare a puppi set of commands for a project deployment
-
Puppet defines to populate the output of the different actions
Download Puppi from GitHub and place it in your modules directory:
git clone https://github.com/example42/puppi.git /etc/puppet/modules/puppi
To use the Puppi “Original, old and widely tested” version, just declare or include the puppi class
class { 'puppi': }
To test the Next-Gen version:
class { 'puppi':
version => '2',
}
If you have resources conflicts, do not install automatically the Puppi dependencies (commands and packages)
class { 'puppi':
install_dependencies => false,
}
Once Puppi is installed you can use it to:
-
Easily define in Puppet manifests Web Applications deploy procedures. For example:
puppi::project::war { "myapp": source => "http://repo.example42.com/deploy/prod/myapp.war", deploy_root => "/opt/tomcat/myapp/webapps", } -
Integrate with your modules for puppi check, info and log
-
Enable Example42 modules integration
The Example42 modules provide (optional) Puppi integration. Once enabled for each module you have puppi check, info and log commands.
To eanble Puppi in OldGen Modules, set in the scope these variables:
$puppi = yes # Enables puppi integration. $monitor = yes # Enables automatic monitoring $monitor_tool = "puppi" # Sets puppi as monitoring tool
For the NextGen modules set the same parameters via Hiera, at Top Scope or as class arguments:
class { 'openssh':
puppi => yes,
monitor => yes,
monitor_tool => 'puppi',
}
puppi <action> <project_name> [ -options ]
The puppi command has these possibile actions:
- puppi init project_name
-
: First time initialization of the defined project
- puppi deploy project_name
-
: Deploys the defined project
- puppi rollback project_name
-
: Rollback to a previous deploy state
- puppi check
-
: Runs project specific and host wide checks
- puppi log
-
: Tails system wide or project specific logs
- puppi info topic_name
-
: Show system information (for all or only the specified topic)
- puppi todo
-
: Show things to do (or done) manually on the system
The deploy/rollback/init actions, puppi run the commands in /etc/puppi/projects/$project_name/$action, log their status and then run the commands in /etc/puppi/projects/$project_name/report to provide reporting, in whatever, pluggable, way.
You can also provide some options:
-
-f : Force puppi commands execution also on CRITICAL errors
-
-i : Interactively ask confirmation for every command
-
-t : Test mode. Just show the commands that should be executed without doing anything
-
-d <yes|full>: Debug mode. Show debugging info during execution
-
-o “parameter=value parameter2=value2” : Set manual options to override defaults. The options must be in parameter=value syntax, separated by spaces and inside double quotes.
Some usage examples:
puppi check : Run host-wide checks. puppi log : Show system logs puppi info : Show general system infos (outputs all the topics available) puppi deploy myapp : Deploys myapp according to the logic defined in Puppet manifests
The set of commands needed for each of these actions are entirely managed with specific Puppet “basic defines”:
- puppi::project
-
Creates the main project structure. One or more different deployment projects can exist on a node.
-
- puppi::initialize
-
Creates a single command to be placed in the init sequence. It’s not required for every project.
-
- puppi::deploy
-
Creates a single command to be placed in the deploy sequence. More than one is generally needed for each project.
-
- puppi::rollback
-
Creates a single command to be placed in the rollback sequence. More than one is generally needed for each project.
-
- puppi::check
-
Creates a single check (based on Nagios plugins) for a project or for the whole host (host wide checks are auto generated by Example42 monitor module)
-
- puppi::report
-
Creates a reporting command to be placed in the report sequence.
-
- puppi::log
-
Creates a log filename entry for a project or the whole hosts.
-
- puppi::info
-
Creates an info entry with the commands used to provide info on a topic
-
Read details in the relevant READMEs
/usr/sbin/puppi - A link to the actual version of puppi enabled
/usr/sbin/puppi.one - The original puppi bash command.
/etc/puppi/puppi.conf - Puppi (one) main config file. Various puppi wide paths are defined here.
/etc/puppi/checks/ - $checksdir - Here all the host wide checks can be placed. If you use the Example42 monitor module and have “puppi” as $monitor_tool, this directory is automatically filled with Nagios plugins based checks.
/etc/puppi/projects/ - $projectsdir - In this directory you can have one or more projects subdirs, with the commands to be run for deploy, rollback and check actions. They are completely built (and purged) by the Puppet module.
/etc/puppi/scripts/ - $scriptsdir - The general-use scripts directory, these are used by the above commands and may require one or more arguments.
/etc/puppi/logs/ - $logssdir - The general-use directory where files are placed which contain the log paths to be used by puppi log
/etc/puppi/info/ - $infodir - The directory where files are placed which contain the commands used by puppi info
/var/lib/puppi/archive/ - $archivedir - Where all data to rollback is placed.
/var/log/puppi/ - $logdir - Where logs and reports of the different commands are placed.
/tmp/puppi/ - $workdir - Temporary, scratchable, directory where Puppi places temporary files.
/tmp/puppi/$project/config - A runtime configuration file, which is used by all all the the scripts invoked by puppi to read and write dynamic variables at runtime. This is necessary to mantain “state” information that changes on every puppi run (such as the deploy datetime, used for backups).
It should be clear that with puppi you have full flexibility in the definition of a deployment procedure, since the puppi command is basically a wrapper that executes arbitrary scripts with a given sequence, in pure KISS logic.
The advantanges though, are various:
-
You have a common syntax to manage deploys and rollbacks on an host
-
In your Puppet manifests, you can set in simple, coherent and still flexible and customizable defines all the elements, you need for your application deployments. Think about it: with just a Puppet define you build the whole deploy logic
-
Reporting for each deploy/rollback is built-in and extensible
-
Automatic checks can be built in the deploy procedure
-
You have a common, growing, set of general-use scripts for typical actions
-
You have quick and useful command to see what’s happening on the system (puppi check, log, info)
There are different parts where you can customize the behaviour of puppi:
-
The set of general-use scripts in /etc/puppi/scripts/ ( this directory is filled with the content of puppi/files/scripts/ ) can/should be enhanced. These can be arbitrary scripts in whatever language. If you want to follow puppi’s logic, though, consider that they should import the common and runtime configuration files and have an exit code logic similar to the one of Nagios plugins: 0 is OK, 1 is WARNING, 2 is CRITICAL. Note that by default a script that exits with WARNING doesn’t block the deploy procedure, on the other hand, if a script exits with CRITICAL (exit 2) by default it blocks the procedure. Take a second, also, to explore the runtime config file created by the puppi command that contains variables that can be set and used by the scripts invoked by puppi.
-
The custom project defines that describe deploy templates. These are placed in puppi/manifests/project/ and can request all the arguments you want to feed your scripts with. Generally is a good idea to design a standard enough template that can be used for all the cases where the deployment procedure involves similar steps. Consider also that you can handle exceptions with variables (see the $loadbalancer_ip usage in puppi/manifests/project/maven.pp)
Puppi is self contained. It doesn’t require other modules. (And is required by all Example42 modules).
For correct functionality by default some extra packages are installed. If you have conflicts with your existing modules, set the argument:
install_dependencies => false