Puppet class browser
Version 5 (Paul Kelly, 07/23/2011 02:58 am)
| 1 | 1 | h1. Puppet class browser |
|
|---|---|---|---|
| 2 | 1 | ||
| 3 | 1 | There are links labeled "Documentation" on the *settings/puppet classes* page, which will direct your browser to the html documentation for a particular puppet module. |
|
| 4 | 1 | ||
| 5 | 1 | The documentation is generated by a rake task that uses the puppetdoc utility and may need some customization to work at a particular site. |
|
| 6 | 1 | ||
| 7 | 1 | h2. Configuration |
|
| 8 | 1 | ||
| 9 | 1 | h3. Document root |
|
| 10 | 1 | ||
| 11 | 3 | Paul Kelly | There is an optional entry in the config/settings.yaml which overrides the location of the generated HTML pages. The default value is *RAILS_ROOT/public* which relies upon the rails built-in web server. |
| 12 | 1 | <pre> |
|
| 13 | 1 | :document_root: /var/www |
|
| 14 | 1 | </pre> |
|
| 15 | 1 | ||
| 16 | 3 | Paul Kelly | The documentation will be written into *document_root*/puppet/rdoc and this location must be in an area that is served by a web server. Any location that is served by apache or webrick/mongrel will do, and foreman's *public* directory is the default. |
| 17 | 1 | ||
| 18 | 1 | h3. manifest cleanup |
|
| 19 | 1 | ||
| 20 | 5 | Paul Kelly | The puppetdoc utility is sensitive to the layout of the manifests and modules directories. In particular, it cannot handle circular or broken symlinks. If you have problems running puppetdoc then move *extras/rdoc/rdoc_prepare_script.rb* to *scripts/rdoc_prepare_script.rb* and then edit it to suit your site. Most sites will not require a *scripts/rdoc_prepare_script.rb* file. If you do not need a *scripts/rdoc_prepare_script.rb* file please ensure that it does not exist; an empty file will cause an error and lots of extra processing. |
| 21 | 1 | ||
| 22 | 1 | h2. Generating the documentation. |
|
| 23 | 1 | ||
| 24 | 1 | h3. Simple case |
|
| 25 | 1 | ||
| 26 | 1 | This is performed by running |
|
| 27 | 1 | ||
| 28 | 1 | rake puppet:rdoc:generate |
|
| 29 | 1 | ||
| 30 | 1 | h3. Complex case |
|
| 31 | 1 | ||
| 32 | 2 | Paul Kelly | If the puppetdoc utility fails to process your manifests then you will have to sanitize your puppet modules directory. The rake puppet:rdoc:generate task will check for the existence of *scripts/rdoc_prepare_script.rb*, and runs this before the the puppetdoc command is executed. This script is expected to copy the source files for your modules to another location, fix any issues and then terminate, passing back the location of the copied directory tree. |
| 33 | 1 | ||
| 34 | 1 | A fairly complex example is provided in *extras/rdoc/rdoc_prepare_script.rb*. |
|
| 35 | 1 | ||
| 36 | 1 | The final command to generate the documentation is then the same as for the simple case |
|
| 37 | 1 | ||
| 38 | 1 | rake puppet:rdoc:generate |
|
| 39 | 4 | Paul Kelly | |
| 40 | 4 | Paul Kelly | h3. Automation |
| 41 | 4 | Paul Kelly | |
| 42 | 4 | Paul Kelly | This rake task is suitable for placing in a cron job and can be added with |
| 43 | 4 | Paul Kelly | |
| 44 | 4 | Paul Kelly | sudo cron -e -u root |
| 45 | 4 | Paul Kelly | |
| 46 | 4 | Paul Kelly | and a line added like this |
| 47 | 4 | Paul Kelly | |
| 48 | 4 | Paul Kelly | 22 2 * * * (cd /var/rails/foreman; rake puppet:rdoc:generate) |
| 49 | 4 | Paul Kelly | |
| 50 | 4 | Paul Kelly | Note that this command assumes that root has write permissions to */var/rails/foreman/public/puppet/rdoc* or wherever you have set *document_root* to in config/settings.yml |
| 51 | 4 | Paul Kelly | |
| 52 | 4 | Paul Kelly | h3. Running the command as a non root user |
| 53 | 4 | Paul Kelly | |
| 54 | 4 | Paul Kelly | You may experience some problems when running this command, (or other puppet commands,) as a non root user as puppet will change its default values for several key parameters to a location in the user's home directory. |
| 55 | 4 | Paul Kelly | |
| 56 | 4 | Paul Kelly | If you run |
| 57 | 4 | Paul Kelly | |
| 58 | 4 | Paul Kelly | puppet --genconfig | egrep $USER |
| 59 | 4 | Paul Kelly | |
| 60 | 4 | Paul Kelly | you will see what I mean. |
| 61 | 4 | Paul Kelly | |
| 62 | 4 | Paul Kelly | Running |
| 63 | 4 | Paul Kelly | |
| 64 | 4 | Paul Kelly | ln -s /etc/puppet/puppet.conf ~/.puppet/puppet.conf |
| 65 | 4 | Paul Kelly | |
| 66 | 4 | Paul Kelly | helps somewhat but beware of this feature |
