Puppet Puppet

Download Puppet Puppet

Post on 03-Oct-2014




1 download

Embed Size (px)


<p>Puppet Documentation(Generated on May 13, 2011, from git revision c171bed4eddbb6bd55cf764ed487d383a1312999)</p> <p>Puppet Labs DocumentationWelcome to the Puppet Labs documentation site. The documentation posted here is also available as a (very large, and frequently updated) PDF, which can be found here. MCollective For information about MCollective, see the Marionette Collective documentation. Puppet Dashboard For information about Puppet Dashboard, see the Puppet Dashboard documentation.</p> <p>Drive-ThruSmall documents for getting help fast. Core Types Cheat Sheet available in single-page avor (double-sided), extra breathing room avor (six pages), and plain web page avor Frequently Asked Questions</p> <p>Learning PuppetLearn to use Puppet! New users: start here. Introduction and Index Resources and the RAL learn about resources, the molecules of system conguration Manifests start writing and applying Puppet code Ordering learn to join resources that depend on each other Variables, Facts, and Conditionals read system information to make versatile manifests Classes and Modules, Part One start collecting resources into self-contained modules</p> <p>Reference ShelfGet 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 REST Access Control secure API access with auth.conf 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.</p> <p>Puppet Documentation Puppet Labs Documentation</p> <p>2/311</p> <p>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</p> <p>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. An Introduction to Puppet Supported Platforms Installing Puppet from packages, source, or gems Conguring Puppet includes server setup 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 &amp; tricks Scaling With Passenger for Puppet 0.24.6 and later Scaling With Mongrel for older versions of Puppet Basic Features and Use Techniques common design patterns, tips, and tricks Troubleshooting avoid common problems and confusions Puppet Modules modules make it easy to organize and share content 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</p> <p>&amp; testing</p> <p>Puppet Documentation Puppet Labs Documentation</p> <p>3/311</p> <p>Best Practices use Puppet eectively 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, &amp; production Reporting learn what your nodes are up to Getting Started With CloudPack create and bootstrap new nodes with the experimental CloudPack extension Hacking and Extending Build your own tools and workows on top of Puppet.USING APIS AND INTERFACES</p> <p>External Nodes specify what your machines do using external data sources Inventory Service use Puppets inventory of nodes at your site in your own custom applicationsUSING RUBY PLUGINS</p> <p>Plugins In Modules where to put plugins, how to sync to clients Writing Custom Facts Writing Custom Functions Writing Custom Types &amp; Providers Complete Resource Example more information on custom types &amp; providers Provider Development more about providersDEVELOPING PUPPET</p> <p>Running Puppet from Source preview the leading edge Development Life Cycle learn how to contribute code</p> <p>Other ResourcesPuppet Wiki &amp; Bug Tracker Puppet Patterns (Recipes)</p> <p>Help Improve This DocumentThis document belongs to the community and is licensed under the Creative Commons. You can help improve it!</p> <p>This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License. To contribute ideas, problems, or suggestions, simply use the Contribute link. If you would like to submit your own content, the process is easy. You can fork the project on github, make changes,</p> <p>Puppet Documentation Puppet Labs Documentation</p> <p>4/311</p> <p>and send us a pull request. See the README les in the project for more information.</p> <p>Documentation VersionThis release of the documentation was generated from revision c171bed4eddbb6bd55cf764ed487d383a1312999 of the puppet-docs repo on May 13, 2011.</p> <p>Learning PuppetThe web (including this site) is full of guides for how to solve specic problems with Puppet and how to get Puppet running. This is something slightly dierent. Start: Resources and the RAL Latest: Ordering </p> <p>WelcomeThis is Learning Puppet, and its part of the Puppet documentation. Specically, its the rst part. By which I dont mean its about getting Puppet installed, or making sure your SSL certicates got issued correctly; thats the other rst part. To be a little gnomic about it because why not this series is less about how to use Puppet than it is about how to become a Puppet user. If youve heard good things about Puppet but dont know where to start, this, hopefully, is it. Its a work in progress, and Id love to read your feedback at</p> <p>Get EquippedYou cant make a knowledge omelette without breaking stu. Possibly eggs, maybe your systems entire conguration! Such is life. So to learn Puppet eectively, you need a virtual machine you can experiment on fearlessly. And to learn Puppet fast, you want a virtual machine with Puppet already installed, so you dont have to learn to debug SSL problems before you know how to classify a node. In short, you want this virtual machine:</p> <p>Get the Learning Puppet VMCurrently, this has been tested with VMWare Fusion on OS X, but it should be usable with other virtualization software; we hope to test it with VirtualBox soon. The root users password is puppet, and you should be able to SSH into it without a problem; for your convenience, the system is congured to write its current IP address to the login screen about ten seconds after it boots. Beyond that, teaching the use of virtualization software is outside the scope of this introduction, but let me know if you run into trouble and well try to rene our approach over time. If youd rather cook up your own VM than download one from the web, you can imitate it fairly</p> <p>Puppet Documentation Learning Puppet</p> <p>5/311</p> <p>easily: this is a stripped-down CentOS 5.5 system with a hostname of puppet, Puppet Enterprise installed using all default answers, iptables turned o, and the pe-puppet and pe-httpd services stopped and disabled. (It also has some nice language modes installed for vim and emacs, but thats not strictly necessary.) To begin with, you wont need separate agent and master VMs; youll be running Puppet in its serverless mode on a single machine. When we get to agent/master Puppet, well walk through turning on the puppet master and duplicating this system into a new agent node.</p> <p>Hit the GasAnd with that, youre ready to start. Part one: Serverless Puppet Begin with Resources and the RAL, where youll learn about the fundamental building blocks of system conguration. After that, move on to Manifests and start controlling your system by writing actual Puppet code. Next, in Ordering, learn about dependencies and refresh events, manage the relationships between resources, and discover the most useful Puppet design pattern. In Variables, Conditionals, and Facts, make your manifests versatile by reading system information. In Classes and Modules, Part One, take the rst step to a knowable and elegant site design and start turning your manifests into self-contained modules. And come back soon, because there are a lot more chapters on the way.</p> <p>Learning Resources and the RALResources are the building blocks of Puppet, and the division of resources into types and providers is what gives Puppet its power. You are at the beginning. Index Manifests </p> <p>MoleculesImagine a systems conguration as a collection of molecules; call them resources. These pieces vary in size, complexity, and lifespan: a user account can be a resource, as can a specic le, a software package, a running service, or a scheduled cron job. Even a single invocation of a shell command can be a resource. Any resource is very similar to a class of related things: every le has a path and an owner, and every user has a name, a UID, and a group. Which is to say: similar resources can be grouped into types. Furthermore, the most important attributes of a resource type are usually conceptually identical across operating systems, regardless of how the implementations dier. That is, the description of a resource can be abstracted away from its implementation.</p> <p>Puppet Documentation Learning Resources and the RAL</p> <p>6/311</p> <p>These two insights form Puppets resource abstraction layer (RAL). The RAL splits resources into types (high-level models) and providers (platform-specic implementations), and lets you describe resources in a way that can apply to any system.</p> <p>Sync: Read, Check, WritePuppet uses the RAL to both read and modify the state of resources on a system. Since its a declarative system, Puppet starts with an understanding of what state a resource should have. To sync the resource, it uses the RAL to query the current state, compares that against the desired state, then uses the RAL again to make any necessary changes.</p> <p>Anatomy of a ResourceIn Puppet, every resource is an instance of a resource type and is identied by a title; it has a number of attributes (which are dened by its type), and each attribute has a value. The Puppet language represents a resource like this: user{'dave': ensure=&gt;present, uid=&gt;'507', gid=&gt;'admin', shell=&gt;'/bin/zsh', home=&gt;'/home/dave', managehome=&gt;true, }</p> <p>This syntax is the heart of the Puppet language, and youll be seeing it a lot. Hopefully you can already see how it lays out all of the resources parts (type, title, attributes, and values) in a fairly straightforward way.</p> <p>The Resource ShellPuppet ships with a tool called puppet resource, which uses the RAL to let you query and modify your system from the shell. Use it to get some experience with the RAL before learning to write and apply manifests. Puppet resources rst argument is a resource type. If executed with no further arguments $puppetresourceuser</p> <p> it will query the system and return every resource of that type it can recognize in the systems current state. You can retrieve a specic resources state by providing a resource name as a second argument. $puppetresourceuserroot user{'root':</p> <p>Puppet Documentation Learning Resources and the RAL</p> <p>7/311</p> <p>home=&gt;'/var/root', shell=&gt;'/bin/sh', uid=&gt;'0', ensure=&gt;'present', password=&gt;'*', gid=&gt;'0', comment=&gt;'SystemAdministrator' }</p> <p>Note that puppet resource returns Puppet code when it reads a resource from the system! You can use this code later to restore the resource to the state its in now. If any attribute=value pairs are provided as additional arguments to puppet resource, it will modify the resource, which can include creating it or destroying it: $puppetresourceuserdaveensure=presentshell="/bin/zsh"home="/home/dave" managehome=true notice:/User[dave]/ensure:created user{'dave': ensure=&gt;'present', home=&gt;'/home/dave', shell=&gt;'/bin/zsh' }</p> <p>(Note that this command line assignment syntax diers from the Puppet languages normal attribute =&gt; value syntax.) Finally, if you specify a resource and use the --edit ag, you can change that resource in your text editor; after the buer is saved and closed, puppet resource will modify the resource to match your changes.</p> <p>The Core Resource TypesPuppet has a number of built-in types, and new native types can be distributed with modules. Puppets core types, the ones youll get familiar with rst, are notify, le, package, service, exec, cron, user, and group. Dont worry about memorizing them immediately, since well be covering various resources as we use them, but do take a second to print out a copy of the core types cheat sheet, a double-sided page covering these eight types. It is doctor-recommended1 and has been clinically shown to treat reference inammation. Documentation for all of the built-in types can always be found in the reference section of this site, and can be generated on the y with the puppet describe utility.</p> <p>An Aside: puppet describe -sYou can get help for any of the Puppet executables by running them with the --help ag, but its worth pausing for an aside on puppet describes -s ag.</p> <p>$puppetdescribe-suser</p> <p>Puppet Documentation Learning Resources and the RAL</p> <p>8/311</p> <p>user ==== Manageusers.Thistypeismostlybuilttomanagesystem users,soitislackingsomefeaturesusefulformanagingnormal users. Thisresourcetypeusestheprescribednativetoolsforcreating groupsandgenerallyusesPOSIXAPIsforretrievinginformation aboutthem.Itdoesnotdirectlymodify`/etc/passwd`oranything.</p> <p>Parameters ---------allowdupe,auth_membership,auths,comment,ensure,expiry,gid,groups, home,key_membership,keys,managehome,membership,name,password, password_max_age,password_min_age,profile_membership,profiles, project,role_membership,roles,shell,uid Providers --------directoryservice,hpuxuseradd,ldap,pw,user_role_add,useradd</p> <p>-s makes puppet describe dump a compact list of the given resource types attributes and providers. This isnt useful when learning about a type for the rst time or looking up allowed values, but its fantastic when you have the name of an attribute on the tip of your tongue or you cant remember which two out of group, groups, and gid are applicable for the user type.</p> <p>NextPuppet resource can be useful for one-o jobs, but Puppet was born for greater things. Time to write some manifests.1. The core types cheat sheet is not actually doctor-recommended. If youre a sysadmin with an M.D., please email me so I can change this footnote.</p> <p>Learning ManifestsYou understand the RAL; now learn about...</p>