puppet manual

Download Puppet Manual

Post on 11-Nov-2014




1 download

Embed Size (px)


Puppet Manual


Puppet Documentation(Generated on July 18, 2012, from git revision cbae724238b675a49acc9024632376db3d15621e)

This is the documentation for Puppet, the industry-leading conguration management toolkit. Most of the content here applies equally to Puppet Enterprise and open source releases of Puppet.

Drive-ThruSmall documents for getting help fast.

Core Types Cheat Sheet A double-sided reference to the most common resource types. (HTML version) Module Cheat Sheet A one-page reference to Puppet module layout, covering classes and dened types, les, templates, and plugins. (HTML version) Frequently Asked Questions Glossary

Learning PuppetLearn to use Puppet! New users: start here. Introduction and Index Part one: Serverless Puppet Resources and the RAL Learn about the fundamental building blocks of system conguration. Manifests Start controlling your system by writing actual Puppet code. Ordering Learn about dependencies and refresh events, manage the relationships between resources, and discover the fundamental Puppet design pattern. Variables, Conditionals, and Facts Make your manifests versatile by reading system information. Modules and Classes (Part One) Start building your manifests into self-contained modules. Templates Use ERB to make your cong les as exible as your Puppet manifests. Parameterized Classes (Modules, Part Two) Learn how to pass parameters to classes and make your modules more adaptable. Dened Types Model repeatable chunks of conguration by grouping basic resources into super-resources. Part two: Master/Agent PuppetPuppet Documentation Drive-Thru 2/391

Preparing an Agent VM Prepare your tools for the next few chapters with our step-by-step walkthrough. Basic Agent/Master Puppet Tour the agent/master workow: sign an agent nodes certicate, pick which classes a node will get, and pull and apply a catalog. More coming soon!

Reference ShelfCurated Guides Get detailed information about cong les, APIs, and the Puppet language. REST API reference of api accessible resources Puppet Language Guide all the language details Puppet Manpages detailed help for each Puppet application Generated References Complete and up-to-date references for Puppets resource types, functions, metaparameters, conguration options, indirection termini, and reports, served piping hot directly from the source code. Resource Types all default types Functions all built in functions Metaparameters all type-independent resource attributes Conguration all conguration le settings Report all available report handlers These references are automatically generated from the inline documentation in Puppets source code. References generated from each version of Puppet are archived here: Versioned References inline reference docs from Puppets past and present

Puppet GuidesLearn about dierent areas of Puppet, x problems, and design solutions. Components Learn more about major working parts of the Puppet system. Puppet commands: master, agent, apply, resource, and more components of the system Installing and Conguring Get Puppet up and running at your site.Puppet Documentation Reference Shelf 3/391

An Introduction to Puppet Supported Platforms Installing Puppet from packages, source, or gems Conguring Puppet use puppet.conf to congure Puppets behavior Setting Up Puppet includes server setup Basic Features and Use Puppet Language Guide all the language details Module Fundamentals nearly all Puppet code should be in modules. Installing Modules from the Puppet Forge save time by using pre-existing modules Techniques common design patterns, tips, and tricks Troubleshooting avoid common problems and confusions Parameterized Classes use parameterized classes to write more eective, versatile, and encapsulated code Module Smoke Testing write and run basic smoke tests for your modules Scope and Puppet understand and banish dynamic lookup warnings with Puppet 2.7 Puppet File Serving serving les with Puppet Style Guide Puppet community conventions Best Practices use Puppet eectively Puppet on Windows Manage Windows nodes side by side with your *nix infrastructure, with Puppet Enterprise 2.5 and Puppet 2.7. Overview Installing Puppet on Windows Running Puppet on Windows Writing Manifests for Windows Troubleshooting Puppet on Windows Developers Only: Running Puppet from Source on Windows Tuning and Scaling Puppets default conguration is meant for prototyping and designing a site. Once youre ready for production deployment, learn how to adjust Puppet for peak performance. Scaling Puppet general tips & tricks Using Multiple Puppet Masters a guide to adding new puppet masters to a single-master site Scaling With Passenger for Puppet 0.24.6 and later Scaling With Mongrel for older versions of Puppet

& testing

Puppet Documentation Reference Shelf


Advanced Features Go beyond basic manifests. Templating template out cong les using ERB Virtual Resources Exported Resources share data between hosts Environments separate dev, stage, & production Reporting learn what your nodes are up to Getting Started With Cloud Provisioner create and bootstrap new nodes with the experimental cloud provisioner extension Publishing Modules on the Puppet Forge preparing your best modules to go public Hacking and Extending Build your own tools and workows on top of Puppet.USING THE PUPPET DATA LIBRARY

Puppet Data Library: Overview Puppet automatically gathers reams of data about your infrastructure. Learn where that data is, how to access it, and how to mine it for knowledge. Inventory Service use Puppets inventory of nodes at your site in your own custom applicationsUSING APIS AND INTERFACES

REST Access Control secure API access with auth.conf External Nodes specify what your machines do using external data sourcesUSING RUBY PLUGINS

Plugins In Modules where to put plugins, how to sync to clients Writing Custom Facts Writing Custom Functions Writing Custom Types & Providers Complete Resource Example more information on custom types & providers Provider Development more about providersDEVELOPING PUPPET

Running Puppet from Source preview the leading edge Development Life Cycle learn how to contribute code Puppet Internals understand how Puppet works internally

Other ResourcesPuppet Wiki & Bug Tracker Puppet Patterns (Recipes)Puppet Documentation Other Resources 5/391

ToolsThis guide covers the major tools that comprise Puppet.

Single binaryFrom version 2.6.0 and onwards all the Puppet functions are also available via a single Puppet binary, in the style of git. List of binary changes: puppetmasterd puppet master puppetd puppet agent puppet puppet apply puppetca puppet cert ralsh puppet resource puppetrun puppet kick puppetqd puppet queue lebucket puppet lebucket puppetdoc puppet doc pi puppet describe This also results in a change in the puppet.conf conguration le. The sections, previously things like [puppetd], now should be renamed to match the new binary names. So [puppetd] becomes [agent]. You will be prompted to do this when you start Puppet. A log message will be generated for each section that needs to be renamed. This is merely a warning existing conguration le will work unchanged.

Manpage documentationAdditional information about each tool is provided in the relevant manpage. You can consult the local version of each manpage, or view the web versions of the manuals.

puppet master (or puppetmasterd)Puppet master is a central management daemon. In most installations, youll have one puppet master server and each managed machine will run puppet agent. By default, puppet master operates a certicate authority, which can be managed using puppet cert. Puppet master serves compiled congurations, les, templates, and custom plugins to managed nodes.Puppet Documentation Tools 6/391

The main conguration le for puppet master, puppet agent, and puppet apply is /etc/puppet/puppet.conf , which has sections for each application.

puppet agent (or puppetd)Puppet agent runs on each managed node. By default, it will wake up every 30 minutes (congurable), check in with puppetmasterd, send puppetmasterd new information about the system (facts), and receive a compiled catalog describing the desired system conguration. Puppet agent is then responsible for making the system match the compiled catalog. If pluginsync is enabled in a given nodes conguration, custom plugins stored on the Puppet Master server are transferred to it automatically. The puppet master server determines what information a given managed node should see based on its unique identier (certname); that node will not be able to see congurations intended for other machines.

puppet apply (or puppet)When running Puppet locally (for instance, to test manifests, or in a non-networked disconnected case), puppet apply is run instead of puppet agent. It then uses local les, and does not try to contact the central server. Otherwise, it behaves the same as puppet agent.

puppet cert (or puppetca)The puppet cert command is used to sign, list and examine certicates used by Puppet to secure the connection between the Puppet master and agents. The most common usage is to sign the certicates of Puppet agents awaiting authorisation: >puppetcert--list agent.example.com >puppetcert--signagent.example.com

You can also list all signed and unsigned certicates: >puppetcert--alland--list +agent.example.com agent2.example.com

Certicates with a + next to them are signed. All others are awaiting signature.

puppet doc (or puppetdoc)Puppet doc generates documentation about Puppet and your manifests, which it can output inPuppet Documentation Tools 7/391

HTML, Markdown and RDoc.

puppet resource (or ralsh)Puppet resource (a