Documentation Start
Version 1 (Anonymous, 03/13/2010 08:01 pm)
| 1 | 1 | # Puppet Documentation |
|
|---|---|---|---|
| 2 | 1 | ||
| 3 | 1 | ||
| 4 | 1 | ||
| 5 | 1 | ## TracNav |
|
| 6 | 1 | ||
| 7 | 1 | #### New To Puppet? |
|
| 8 | 1 | ||
| 9 | 1 | - [[About Puppet]] |
|
| 10 | 1 | - [[Puppet Compatibility]] |
|
| 11 | 1 | - [[Whos Using Puppet]] |
|
| 12 | 1 | - [[Getting Started]] |
|
| 13 | 1 | - [[Puppet Best Practice]] |
|
| 14 | 1 | - [[Downloading Puppet]] |
|
| 15 | 1 | - [[Language Tutorial]] |
|
| 16 | 1 | - [[Frequently Asked Questions]] |
|
| 17 | 1 | - [[Documentation Start]] |
|
| 18 | 1 | - [[Getting Help]] |
|
| 19 | 1 | - [[Whos Using Puppet]] |
|
| 20 | 1 | ||
| 21 | 1 | #### Release Notes |
|
| 22 | 1 | ||
| 23 | 1 | - [[Glossary Of Terms]] |
|
| 24 | 1 | - [[Style Guide]] |
|
| 25 | 1 | - [[Puppet Recipes]] |
|
| 26 | 1 | - [[Facter Recipes]] |
|
| 27 | 1 | - [[Recipe Requests]] |
|
| 28 | 1 | - [[Module Organisation]] |
|
| 29 | 1 | - [[Puppet Modules]] |
|
| 30 | 1 | - [[Puppet Executables]] |
|
| 31 | 1 | - [[Puppet Internals]] |
|
| 32 | 1 | ||
| 33 | 1 | #### References and Advanced Topics |
|
| 34 | 1 | ||
| 35 | 1 | - [[Type Reference]] |
|
| 36 | 1 | - [[Nagios Reference]] |
|
| 37 | 1 | - [[Function Reference]] |
|
| 38 | 1 | - [[Metaparameter Reference]] |
|
| 39 | 1 | - [[Configuration Reference]] |
|
| 40 | 1 | - [[Network Reference]] |
|
| 41 | 1 | - [[Report Reference]] |
|
| 42 | 1 | - [[Writing Your Own Functions]] |
|
| 43 | 1 | - [[Parsing Architecture]] |
|
| 44 | 1 | ||
| 45 | 1 | ||
| 46 | 1 | ||
| 47 | 1 | ||
| 48 | 1 | ||
| 49 | 1 | #### Table of Contents |
|
| 50 | 1 | ||
| 51 | 1 | 1. [[Documentation\_Start#IntroductiontoPuppet|Documentation |
|
| 52 | 1 | Start]] |
|
| 53 | 1 | 2. [[Documentation\_Start#CommandLineExecutables|Documentation |
|
| 54 | 1 | Start]] |
|
| 55 | 1 | 3. [[Documentation\_Start#TypeandLanguageReference|Documentation |
|
| 56 | 1 | Start]] |
|
| 57 | 1 | 4. [[Documentation\_Start#Configuration|Documentation Start]] |
|
| 58 | 1 | 5. [[Documentation\_Start#Cookbook|Documentation Start]] |
|
| 59 | 1 | 6. [[Documentation\_Start#ExtendingPuppet|Documentation Start]] |
|
| 60 | 1 | 7. [[Documentation\_Start#RelatedApplications|Documentation |
|
| 61 | 1 | Start]] |
|
| 62 | 1 | 8. [[Documentation\_Start#AdditionalDocumentation|Documentation |
|
| 63 | 1 | Start]] |
|
| 64 | 1 | ||
| 65 | 1 | ## Introduction to Puppet |
|
| 66 | 1 | ||
| 67 | 1 | Puppet is a declarative **language** for expressing system |
|
| 68 | 1 | configuration, a **client** and **server** for distributing it, and |
|
| 69 | 1 | a **library** for realizing the configuration. |
|
| 70 | 1 | ||
| 71 | 1 | The [[Puppet Introduction]] covers the basic architecture and |
|
| 72 | 1 | design goals, including whether and why you should be using Puppet |
|
| 73 | 1 | on your network. |
|
| 74 | 1 | ||
| 75 | 1 | There is an [[Installation Guide]] meant for installation of Puppet |
|
| 76 | 1 | across a network and a [[Puppet Best Practice]] that covers |
|
| 77 | 1 | conventions used among the Puppet community. There is also an |
|
| 78 | 1 | [[Release Notes]] page which details major feature and language |
|
| 79 | 1 | changes between versions. |
|
| 80 | 1 | ||
| 81 | 1 | There is also a guide for [[Puppet Source]] to get an idea of what |
|
| 82 | 1 | you can do without making a full deployment. |
|
| 83 | 1 | ||
| 84 | 1 | ## Command Line Executables |
|
| 85 | 1 | ||
| 86 | 1 | This section will eventually have links to full man-pages for each |
|
| 87 | 1 | executable, but for now the man pages can be found by running the |
|
| 88 | 1 | respective executable with the --help flag (this requires the |
|
| 89 | 1 | Rdoc::usage module, which is often missing). |
|
| 90 | 1 | ||
| 91 | 1 | However, most arguments for the executables are in the form of |
|
| 92 | 1 | configuration parameters used internally in the library. All of the |
|
| 93 | 1 | executables are written to accept any of these configuration |
|
| 94 | 1 | parameters, and they are all defined in the [[Configuration |
|
| 95 | 1 | Reference]] . |
|
| 96 | 1 | ||
| 97 | 1 | - **puppet**. Stand alone Puppet Site Manifest Script evaluator. |
|
| 98 | 1 | Parses, evaluates, and implements a Site Manifest locally. |
|
| 99 | 1 | - **puppetmasterd**. Puppet Site Manifest Server Daemon. Runs on |
|
| 100 | 1 | each host serving/providing configurations to Puppet client hosts. |
|
| 101 | 1 | - **puppetd**. Puppet Client Host Configuration Daemon. Runs on |
|
| 102 | 1 | each host whose configuration is managed by Puppet. Requests a Host |
|
| 103 | 1 | Specific Manifest from a Puppet Manifest Server and implements it |
|
| 104 | 1 | locally. |
|
| 105 | 1 | - **puppetca**. SSL Certificate Authority Server used for |
|
| 106 | 1 | receiving cerification requests from puppet clients. Puppet Client |
|
| 107 | 1 | Hosts are required to have their SSL certs signed by their Puppet |
|
| 108 | 1 | Manifest Server's Authority before they can be authenticated and |
|
| 109 | 1 | authorized to receive configurations. |
|
| 110 | 1 | - **puppetdoc**. Command line tool for printing Puppet Default |
|
| 111 | 1 | and Local Type Library reference documentation. This is really only |
|
| 112 | 1 | used internally. |
|
| 113 | 1 | - **puppetrun**. Command line tool for manually triggering Puppet |
|
| 114 | 1 | configuration runs. |
|
| 115 | 1 | ||
| 116 | 1 | ## Type and Language Reference |
|
| 117 | 1 | ||
| 118 | 1 | The Puppet reference is split into the following pieces: |
|
| 119 | 1 | ||
| 120 | 1 | - [[Language Tutorial]] . A tutorial regarding all available |
|
| 121 | 1 | language structures within Puppet. This reference presents the |
|
| 122 | 1 | limits of and options for expressibility within Puppet. |
|
| 123 | 1 | - [[Function Reference]] |
|
| 124 | 1 | - [[Metaparameter Reference]] |
|
| 125 | 1 | - [[Type Reference]] . A reference of all available Puppet Types. |
|
| 126 | 1 | The types defined in this reference represent the total ability of |
|
| 127 | 1 | Puppet to manage your system -- if an object is not in this |
|
| 128 | 1 | reference, then Puppet cannot currently manage it. |
|
| 129 | 1 | - [[Report Reference]] . A reference to all in-built report |
|
| 130 | 1 | types. |
|
| 131 | 1 | - [[Glossary Of Terms]] |
|
| 132 | 1 | ||
| 133 | 1 | ## Configuration |
|
| 134 | 1 | ||
| 135 | 1 | Puppet configuration can be done through per-process configuration |
|
| 136 | 1 | files (e.g., puppetd.conf) or on the command-line via switches. |
|
| 137 | 1 | Much of the documentation is available via --help switches on each |
|
| 138 | 1 | executable, but most of the useful switches are common to all |
|
| 139 | 1 | executables and are thus documented in the [[Configuration |
|
| 140 | 1 | Reference]] . |
|
| 141 | 1 | ||
| 142 | 1 | There are some guides already, though: |
|
| 143 | 1 | ||
| 144 | 1 | - [[Language Tutorial]] explores the Puppet language functions, |
|
| 145 | 1 | with multiple examples |
|
| 146 | 1 | - [[File Serving Configuration]] |
|
| 147 | 1 | - [[Puppet Best Practice]] describes the best practice for |
|
| 148 | 1 | configuration layouts, syntax, naming conventions, etc |
|
| 149 | 1 | - [[Puppet Modules]] are a way to organise manifests for reuse |
|
| 150 | 1 | - [[Puppet Templating]] with ERB |
|
| 151 | 1 | - [[Using Tags]] |
|
| 152 | 1 | - [[Using Multiple Environments]] describes how to be able to |
|
| 153 | 1 | develop and test changed manifests without disturbing nodes running |
|
| 154 | 1 | in production |
|
| 155 | 1 | - [[Virtual Resources]] |
|
| 156 | 1 | - [[Using Stored Configuration]] explains how to store |
|
| 157 | 1 | configuration information in a database |
|
| 158 | 1 | - [[Exported Resources]] |
|
| 159 | 1 | - [[Certificates And Security]] |
|
| 160 | 1 | - [[Reports And Reporting]] |
|
| 161 | 1 | - [[LDAPNodes]] explains how to store node information in LDAP |
|
| 162 | 1 | - [[Puppet Scalability]] describes common issues and solutions |
|
| 163 | 1 | related to scaling a puppet deployment. |
|
| 164 | 1 | - [[Using Mongrel]] -- Using Mongrel or Passenger to scale Puppet |
|
| 165 | 1 | instead of the internal Webrick server |
|
| 166 | 1 | - [[Using Mongrel Pound]] -- Using Mongrel with the Pound web |
|
| 167 | 1 | server |
|
| 168 | 1 | - [[Using Mongrel Nginx]] -- Using Mongrel with the Nginx web |
|
| 169 | 1 | server |
|
| 170 | 1 | ||
| 171 | 1 | - [[Using Passenger]] -- Using Passenger and Apache to scale |
|
| 172 | 1 | Puppet |
|
| 173 | 1 | - [[Using Unicorn]] -- Using Unicorn to scale Puppet |
|
| 174 | 1 | ||
| 175 | 1 | ||
| 176 | 1 | ||
| 177 | 1 | ## Cookbook |
|
| 178 | 1 | ||
| 179 | 1 | The Cookbook is a repository of modules, 'recipes' as well as |
|
| 180 | 1 | Puppet and Facter configuration snippets for achieving common |
|
| 181 | 1 | tasks. |
|
| 182 | 1 | ||
| 183 | 1 | ### Module documentation |
|
| 184 | 1 | ||
| 185 | 1 | - [[Puppet Manifest Documentation]] - From Puppet 0.24.7 you can |
|
| 186 | 1 | create automatic documentation for manifests and modules |
|
| 187 | 1 | ||
| 188 | 1 | ### Module sets |
|
| 189 | 1 | ||
| 190 | 1 | You can find a number of collections of Puppet modules for a |
|
| 191 | 1 | variety of applications and operating systems on the [[Puppet |
|
| 192 | 1 | Modules]] page. |
|
| 193 | 1 | ||
| 194 | 1 | ### Recipes |
|
| 195 | 1 | ||
| 196 | 1 | - [[Recipe Requests]] - a wishlist |
|
| 197 | 1 | - [[Puppet Recipes]] |
|
| 198 | 1 | - [[Facter Recipes]] |
|
| 199 | 1 | ||
| 200 | 1 | ## Extending Puppet |
|
| 201 | 1 | ||
| 202 | 1 | Puppet is also highly extensible. This section lists additional |
|
| 203 | 1 | information that can help you create new types, providers and |
|
| 204 | 1 | functions for Puppet. Also documented is the process for adding |
|
| 205 | 1 | custom facts for Facter. |
|
| 206 | 1 | ||
| 207 | 1 | - [[Development\_Creating\_Custom\_Types|Development/Creating |
|
| 208 | 1 | Custom Types]] -- Creating your own custom types |
|
| 209 | 1 | - [[Development\_Provider\_Development|Development/Provider |
|
| 210 | 1 | Development]] -- Documentation for developing providers |
|
| 211 | 1 | - [[Development\_Practical\_Types|Development/Practical Types]] |
|
| 212 | 1 | -- A practical example of type development |
|
| 213 | 1 | - [[Development\_Complete\_Resource\_Example|Development/Complete |
|
| 214 | 1 | Resource Example]] -- A complete example of a type and provider |
|
| 215 | 1 | - [API Documentation](http://reductivelabs.com/downloads/puppet/apidocs/) |
|
| 216 | 1 | -- API documentation |
|
| 217 | 1 | - [[Adding Facts]] -- Adding custom facts to Facter |
|
| 218 | 1 | - [[Writing Your Own Functions]] -- Extending the Puppet language |
|
| 219 | 1 | with your own server-side functions |
|
| 220 | 1 | - [[Plugins In Modules]] -- Method for distributing custom |
|
| 221 | 1 | plug-ins via modules |
|
| 222 | 1 | - [[Dsl\_Hints\_And\_Tips\_Patterns|Recipes/Dsl Hints And Tips]] |
|
| 223 | 1 | -- Initial page on how to use Puppet types from plain old Ruby. |
|
| 224 | 1 | - [[Development\_Writing\_Tests|Development/Writing Tests]] -- |
|
| 225 | 1 | Writing RSpec tests for your Puppet contributions. |
|
| 226 | 1 | - Puppet's |
|
| 227 | 1 | [[Development\_Development\_Lifecycle|Development/Development |
|
| 228 | 1 | Lifecycle]] process |
|
| 229 | 1 | ||
| 230 | 1 | ## Related Applications |
|
| 231 | 1 | ||
| 232 | 1 | A number of applications that extend, support or supplement Puppet |
|
| 233 | 1 | have been developed. These include: |
|
| 234 | 1 | ||
| 235 | 1 | - [PuppetShow](http://github.com/shadoi/puppetshow/) -- A |
|
| 236 | 1 | Rails-application for viewing information about Puppet and |
|
| 237 | 1 | configured hosts. |
|
| 238 | 1 | - [The Foreman](http://theforeman.org) -- A Rails-application for |
|
| 239 | 1 | managing server lifecycle. |
|
| 240 | 1 | integrates with Puppet (external nodes, PuppetCA, inventory and |
|
| 241 | 1 | reporting) and provides dynamicly generated with Kickstart / |
|
| 242 | 1 | jumpstart and preseed handsfree. |
|
| 243 | 1 | - [Viper](http://www.spinlocksolutions.com/viper/) -- A |
|
| 244 | 1 | LDAP-based system for automated hosts installation, configuration |
|
| 245 | 1 | and monitoring |
|
| 246 | 1 | - [iClassify](https://wiki.hjksolutions.com/display/IC/Home) -- A |
|
| 247 | 1 | node management tool for Puppet. |
|
| 248 | 1 | - [PuppetView](http://www.devco.net/pubwiki/Puppet/PuppetView) -- |
|
| 249 | 1 | A light weight web-based Puppet log viewer written in PHP. |
|
| 250 | 1 | - [Cft](http://cft.et.redhat.com/) -- A configuration file |
|
| 251 | 1 | tracker that uses Puppet at its base. |
|
| 252 | 1 | - [Augeas](http://augeas.net/) -- Augeas is a configuration |
|
| 253 | 1 | editing tool. |
|
| 254 | 1 | - [Carpet](http://www.agileweboperations.com/configuration-management-remixed-introducing-carpet/) |
|
| 255 | 1 | -- Carpet is a combination of Puppet and Capistrano. |
|
| 256 | 1 | ||
| 257 | 1 | ## Additional Documentation |
|
| 258 | 1 | ||
| 259 | 1 | While the above links represent the standard, recommended |
|
| 260 | 1 | documentation, there is additional information available for those |
|
| 261 | 1 | who are interested. |
|
| 262 | 1 | ||
| 263 | 1 | Also available is |
|
| 264 | 1 | [Pulling Strings with Puppet](http://www.amazon.com/gp/product/1590599780?ie=UTF8&tag=puppet0e-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=1590599780) |
|
| 265 | 1 | - the first book on Puppet written by James Turnbull. Puppet is |
|
| 266 | 1 | also mentioned in Chapter 19 (together with provisioning and |
|
| 267 | 1 | bootstrapping) of |
|
| 268 | 1 | [Pro Linux System Administration](http://www.amazon.com/gp/product/1430219122?ie=UTF8&tag=puppet0e-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=1430219122) |
|
| 269 | 1 | by James Turnbull, Peter Lieverdink and Dennis Matotek. |
|
| 270 | 1 | ||
| 271 | 1 | - [[Frequently Asked Questions]] |
|
| 272 | 1 | - [[Branch Testing]] describes how to manage and test your |
|
| 273 | 1 | configuration across multiple Puppet masters |
|
| 274 | 1 | - [[Puppet Internals]] describes how manifests are processed and |
|
| 275 | 1 | used |
|
| 276 | 1 | - PuppetVsCfengine? -- How Cfengine compares to Puppet |
|
| 277 | 1 | - [[Transitioning From Cfengine]] -- Using the Cfengine module |
|
| 278 | 1 | - [[Puppet With Launchd]] -- A tutorial for starting puppet with |
|
| 279 | 1 | Apple's new launchd. |
|
| 280 | 1 | - If you're considering contributing documentation, please take a |
|
| 281 | 1 | look at the [[Documentation Standards]] . |
|
| 282 | 1 | - [[Puppet MacOSX]] -- Describes recommendations when running |
|
| 283 | 1 | Puppet on Mac OS X. |
|
| 284 | 1 | - [[Puppet Solaris]] -- Describes installing and running Puppet |
|
| 285 | 1 | on Solaris. |
|
| 286 | 1 | - [[Puppet FreeBSD]] -- Tips for running Puppet on FreeBSD. |
|
| 287 | 1 | - [[Puppet Gentoo]] -- Tips for running Puppet on Gentoo |
|
| 288 | 1 | - [[Puppet Debian]] -- Tips for running Puppet on Debian |
|
| 289 | 1 | - [[Puppet Presentations]] -- Presentations about Puppet |
|
| 290 | 1 | - [[Puppet Best Practice]] -- How Puppet is used to manage a |
|
| 291 | 1 | large network at Stanford |
|
| 292 | 1 | - [[Infrastructure Design Guidelines]] -- Another suggested best |
|
| 293 | 1 | practice guide to managing infrastructure with Puppet |
|
| 294 | 1 | - [[Multiple Certificate Authorities]] -- How to setup multiple |
|
| 295 | 1 | puppetmaster daemons with mutual trust. |
|
| 296 | 1 | - [Puppet on Ubuntu Installation](http://www.howtoforge.com/installing_puppet_on_ubuntu) |
|
| 297 | 1 | -- Walk through of how to get Puppet running on Ubuntu. |
|
| 298 | 1 | - A |
|
| 299 | 1 | [detailed example](http://people.redhat.com/dlutter/puppet-app.html) |
|
| 300 | 1 | of using Puppet and how the way it modularizes configurations can |
|
| 301 | 1 | be used for sharing 'system recipes' |
|
| 302 | 1 | - [Puppet Tutorial](http://bitfieldconsulting.com/puppet-tutorial) |
|
| 303 | 1 | - [Puppet Workshop](http://www.kanarip.com/courses/Configuration_Management_Using_Puppet/) |
|
| 304 | 1 | -- A Puppet workshop designed to introduce new users to Puppet |
|
| 305 | 1 | - [Scaling Puppet with distributed version control](http://bitfieldconsulting.com/scaling-puppet-with-distributed-version-control) |
|
| 306 | 1 | -- Using Git (or another DVCS) to distribute manifests, removing |
|
| 307 | 1 | the need for a Puppet server |