dev/provisioning/modules/puppi/README.md
changeset 28 b0b56e0f8c7f
equal deleted inserted replaced
27:a2342f26c9de 28:b0b56e0f8c7f
       
     1 # Puppi: Puppet Knowledge to the CLI
       
     2 
       
     3 Puppi One and Puppi module written by Alessandro Franceschi / al @ lab42.it
       
     4 
       
     5 Puppi Gem by Celso Fernandez / Zertico
       
     6 
       
     7 Source: http://www.example42.com
       
     8 
       
     9 Licence: Apache 2
       
    10 
       
    11 Puppi is a unique tool that serves both as a Puppet module and a CLI command tool.
       
    12 It's data is entirely driven by Puppet code.
       
    13 Example use cases for Puppi may include:
       
    14 - creating a standardize method to automate the deployment of web applications
       
    15 - or to provide a set of standard commands to query and check system resources based on "user definded actions".
       
    16 
       
    17 Its structure provides FULL flexibility on the type of "actions" that may be required for virtually any kind of application deployment and/or system information gathering.
       
    18 
       
    19 The module provides:
       
    20 
       
    21 * Old-Gen and Next-Gen Puppi implementation.
       
    22 
       
    23 * A set of scripts that can be chained togehter to automate any kind of deployment.
       
    24 
       
    25 * Puppet defines that make it easy to prepare a puppi set of commands for a project deployment.
       
    26 
       
    27 * Puppet defines to populate the output of the different actions.
       
    28 
       
    29 
       
    30 ## HOW TO INSTALL
       
    31 
       
    32 Download Puppi from GitHub and place it in your modules directory:
       
    33 
       
    34 ```bash
       
    35 git clone https://github.com/example42/puppi.git /etc/puppet/modules/puppi
       
    36 ```
       
    37 
       
    38 To use the Puppi "Original, old and widely tested" version, just declare or include the puppi class
       
    39 
       
    40 ```ruby
       
    41 class { 'puppi': }
       
    42 ```
       
    43 
       
    44 To test the Next-Gen version you can perform the following command. Please note that this module is
       
    45 not stable yet:
       
    46 
       
    47 ```ruby
       
    48 class { 'puppi':
       
    49   version => '2',
       
    50 }
       
    51 ```
       
    52 
       
    53 If you have resources conflicts, do not install automatically the Puppi dependencies (commands and packages)
       
    54 
       
    55 ```ruby
       
    56 class { 'puppi':
       
    57   install_dependencies => false,
       
    58 }
       
    59 ```
       
    60 
       
    61 ## HOW TO USE
       
    62 
       
    63 Once Puppi is installed you can use it to:
       
    64 
       
    65 * Easily define in Puppet manifests Web Applications deploy procedures. For example:
       
    66 
       
    67   ```ruby
       
    68   puppi::project::war { "myapp":
       
    69     source           => "http://repo.example42.com/deploy/prod/myapp.war",
       
    70     deploy_root      => "/opt/tomcat/myapp/webapps",
       
    71   }
       
    72   ```
       
    73 
       
    74 * Integrate with your modules for puppi check, info and log
       
    75 
       
    76 * Enable Example42 modules integration
       
    77 
       
    78 
       
    79 ## HOW TO USE WITH EXAMPLE42 MODULES
       
    80 
       
    81 The Example42 modules provide (optional) Puppi integration.
       
    82 Once enabled for each module you have puppi check, info and log commands.
       
    83 
       
    84 To enable Puppi in OldGen Modules, set in the scope these variables:
       
    85 
       
    86 ```
       
    87 $puppi = yes            # Enables puppi integration
       
    88 $monitor = yes          # Enables automatic monitoring
       
    89 $monitor_tool = "puppi" # Sets puppi as monitoring tool
       
    90 ```
       
    91 
       
    92 For the NextGen modules set the same parameters via Hiera, at Top Scope or as class arguments:
       
    93 
       
    94 ```ruby
       
    95 class { 'openssh':
       
    96   puppi        => yes,
       
    97   monitor      => yes,
       
    98   monitor_tool => 'puppi',
       
    99 }
       
   100 ```
       
   101 
       
   102 ## USAGE OF THE PUPPI COMMAND (OLD GEN)
       
   103 
       
   104 ```bash
       
   105 puppi <action> <project_name> [ -options ]
       
   106 ```
       
   107 
       
   108 The puppi command has these possible actions:
       
   109 
       
   110 First time initialization of the defined project (if available)
       
   111         puppi init <project>
       
   112 
       
   113 Deploy the specified project
       
   114         puppi deploy <project>
       
   115 
       
   116 Rollback to a previous deploy state
       
   117         puppi rollback <project>
       
   118 
       
   119 Run local checks on system and applications
       
   120         puppi check
       
   121 
       
   122 Tail system or application logs
       
   123         puppi log
       
   124 
       
   125 Show system information (for all or only the specified topic)
       
   126         puppi info [topic]
       
   127 
       
   128 Show things to do (or done) manually on the system (not done via Puppet)
       
   129         puppi todo
       
   130 
       
   131 In the deploy/rollback/init actions, puppi runs the commands in /etc/puppi/projects/$project/$action, logs their status and then run the commands in /etc/puppi/projects/$project/report to provide reporting, in whatever, pluggable, way.
       
   132 
       
   133 You can also provide some options:
       
   134 
       
   135 * -f : Force puppi commands execution also on CRITICAL errors
       
   136 
       
   137 * -i : Interactively ask confirmation for every command
       
   138 
       
   139 * -t : Test mode. Just show the commands that should be executed without doing anything
       
   140 
       
   141 * -d <yes|full>: Debug mode. Show debugging info during execution
       
   142 
       
   143 * -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.
       
   144 
       
   145 
       
   146 Some common puppi commnds when you log for an application deployment:
       
   147 
       
   148 ```bash
       
   149 puppi check
       
   150 puppi log &    # (More readable if done on another window)
       
   151 puppi deploy myapp
       
   152 puppi check
       
   153 puppi info myapp
       
   154 ```
       
   155 
       
   156 ## THE PUPPI MODULE
       
   157 
       
   158 The set of commands needed for each of these actions are entirely managed with specific
       
   159 Puppet "basic defines":
       
   160 
       
   161 Create the main project structure. One or more different deployment projects can exist on a node.
       
   162         puppi::project
       
   163 
       
   164 Create a single command to be placed in the init sequence. It's not required for every project.
       
   165         puppi::initialize
       
   166 
       
   167 Create a single command to be placed in the deploy sequence. More than one is generally needed for each project.
       
   168         puppi::deploy
       
   169 
       
   170 Create a single command to be placed in the rollback sequence. More than one is generally needed for each project.
       
   171         puppi::rollback
       
   172 
       
   173 Create 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)
       
   174         puppi::check
       
   175 
       
   176 Create a reporting command to be placed in the report sequence.
       
   177         puppi::report
       
   178 
       
   179 Create a log filename entry for a project or the whole hosts.
       
   180         puppi::log
       
   181 
       
   182 Create an info entry with the commands used to provide info on a topic
       
   183         puppi::info
       
   184 
       
   185 Read details in the relevant READMEs
       
   186 
       
   187 
       
   188 ## FILE PATHS (all of them are provided, and can be configured, in the puppi module):
       
   189 
       
   190 A link to the actual version of puppi enabled
       
   191         /usr/sbin/puppi
       
   192 
       
   193 The original puppi bash command.
       
   194         /usr/sbin/puppi.one
       
   195 
       
   196 Puppi (one) main config file. Various puppi wide paths are defined here.
       
   197         /etc/puppi/puppi.conf
       
   198 
       
   199 Directory where by default 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.
       
   200         /etc/puppi/checks/ ($checksdir)
       
   201 
       
   202 Directory that containts projects subdirs, with the commands to be run for deploy, rollback and check actions. They are completely built (and purged) by the Puppet module.
       
   203         /etc/puppi/projects/ ($projectsdir)
       
   204 
       
   205 The general-use scripts directory, these are used by the above commands and may require one or more arguments.
       
   206         /etc/puppi/scripts/ ($scriptsdir)
       
   207 
       
   208 The general-use directory where files are placed which contain the log paths to be used by puppi log
       
   209         /etc/puppi/logs/ ($logssdir)
       
   210 
       
   211 The general-use directory where files are placed which contain the log paths to be used by puppi log
       
   212         /etc/puppi/info/ ($infodir)
       
   213 
       
   214 Where all data to rollback is placed.
       
   215         /var/lib/puppi/archive/ ($archivedir)
       
   216 
       
   217 Where logs and reports of the different commands are placed.
       
   218         /var/log/puppi/ ($logdir)
       
   219 
       
   220 Temporary, scratchable, directory where Puppi places temporary files.
       
   221         /tmp/puppi/ ($workdir)
       
   222 
       
   223 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).
       
   224         /tmp/puppi/$project/config
       
   225 
       
   226 
       
   227 ## HOW TO CUSTOMIZE
       
   228 It should be clear that with puppi you have full flexibility in the definition of a deployment
       
   229 procedure, since the puppi command is basically a wrapper that executes arbitrary scripts with
       
   230 a given sequence, in pure KISS logic.
       
   231 
       
   232 The advantanges though, are various:
       
   233 * You have a common syntax to manage deploys and rollbacks on an host
       
   234 
       
   235 * In your Puppet manifests, you can set in simple, coherent and still flexible and customizable
       
   236   defines all the elements, you need for your application deployments.
       
   237   Think about it: with just a Puppet define you build the whole deploy logic
       
   238 
       
   239 * Reporting for each deploy/rollback is built-in and extensible
       
   240 
       
   241 * Automatic checks can be built in the deploy procedure
       
   242 
       
   243 * You have a common, growing, set of general-use scripts for typical actions
       
   244 
       
   245 * You have quick and useful command to see what's happening on the system (puppi check, log, info)
       
   246 
       
   247 There are different parts where you can customize the behaviour of puppi:
       
   248 
       
   249 * The set of general-use scripts in /etc/puppi/scripts/ ( this directory is filled with the content
       
   250   of puppi/files/scripts/ ) can/should be enhanced. These can be arbitrary scripts in whatever
       
   251   language. If you want to follow puppi's logic, though, consider that they should import the
       
   252   common and runtime configuration files and have an exit code logic similar to the one of
       
   253   Nagios plugins: 0 is OK, 1 is WARNING, 2 is CRITICAL. Note that by default a script that
       
   254   exits with WARNING doesn't block the deploy procedure, on the other hand, if a script exits
       
   255   with CRITICAL (exit 2) by default it blocks the procedure.
       
   256   Take a second, also, to explore the runtime config file created by the puppi command that
       
   257   contains variables that can be set and used by the scripts invoked by puppi.
       
   258 
       
   259 * The custom project defines that describe deploy templates. These are placed in
       
   260   puppi/manifests/project/ and can request all the arguments you want to feed your scripts with.
       
   261   Generally is a good idea to design a standard enough template that can be used for all the
       
   262   cases where the deployment procedure involves similar steps. Consider also that you can handle
       
   263   exceptions with variables (see the $loadbalancer_ip usage in puppi/manifests/project/maven.pp)
       
   264 
       
   265 
       
   266 ## (NO) DEPENDENCIES AND CONFLICTS
       
   267 Puppi is self contained. It doesn't require other modules.
       
   268 (And is required by all Example42 modules).
       
   269 
       
   270 For correct functionality by default some extra packages are installed.
       
   271 If you have conflicts with your existing modules, set the argument:
       
   272   install_dependencies => false
       
   273