|
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 |