Puppet Best Practices

Preface

This book will do more than help solve problems that you are experiencing today; it is intended to help you prepare for the future. We discuss how to build and deploy highly maintainable Puppet code, with a focus on avoiding problems that you’d only need to fix later (technical debt).

This book does not attempt to explain the basics of using Puppet; instead, we look at how to use Puppet most effectively. This includes the following:

• A review of the design decisions behind Puppet features

• An exploration of patterns for organizing code and data

• A look at the powerful features of Puppet that you might not be using today

• Discussions of common pitfalls and traps when deploying Puppet infrastructure

What Is a Best Practice?

A best practice is the best-known way to use something for positive value while minimizing unnecessary risk. This isn’t defined by the manufacturer, rather by practical experience of users in the field.

Do Best Practices Apply to Us?

This question was posed by a manager not certain that Puppet best practices were something in which his team should invest:

“We don’t make Puppet. We use Puppet to provide our business’ services. We have our own best practices in our field. Do Puppet’s best practices apply to us?”

Best practices don’t tell you how to operate your business or provide your product. That function is provided by the regulatory, legal, and competitive environment in which the business operates.

Best practices inform you how to safely use the tool in your hand. Best practices on power tools aren’t just for carpenters: they’re for everyone who uses a power saw. In fact, they are essential guidance for people who aren’t using it every day and need to avoid costly mistakes.

A best practice does not tell you why to use a tool, it informs you how to use the tool safely and effectively.

There isn’t always an objectively correct best practice for every conceivable tool or use case. Worse yet, there can be conflicting best practices that apply to a given usage. This book provides criteria to judge what makes a solution effective, and how to apply that understanding for the best possible results.

Tip

Best practices don’t come in a manual—they come from years of burned hands and deep scars from using the tools in anger...uh, sorry! We mean practical, hands-on experience using the tools. Of course we did!

Who Should Read This Book

This book explores concepts, designs, and practices useful for Puppet novices and experts alike. It specifically aims to provide the following benefits for Puppet users:

• Identify alternate design approaches and their benefits for experienced DevOps or SRE engineers developing infrastructure as code today.

• Emphasize best-practice code patterns for system administrators and developers. Enumerate useful structures for organization of code and data.

• Review solution evaluation criteria and iterative improvement suggestions for architects and infrastructure engineers.

• Demonstrate declarative coding practices for Puppet novices of any type. Provide warnings about pitalls to avoid during the learning process.

We do intend for this book to be valuable for all professionals working with Puppet. if you’re interested in improving your understanding of configuration management (CM), continuous integration (CI), continuous delivery (CD), automation tools, and infrastructure as code, you should find the concepts and designs in this book useful and practical. Even if you are only peripherally related to the usage of Puppet in your organization, you will find the following here:

• The design principles and major components of a working Puppet ecosystem

• Best-practice implementations of Puppet architecture that you should consider

• Guidelines to implement or upgrade Puppet effectively in your organization

• Strategies to get the most value out of Puppet with the least effort

Whether you are an expert responsible for designing large-scale Puppet infrastructure, or a novice learning to deploy a single application, we intend for this book to be valuable to you. The content should be immediately useful if you work with Puppet today, but it also can provide a conceptual foundation if you’re just learning about Puppet, taking Puppet training courses, or migrating from other configuration management tools.

Tip

This book is not intended to train you in how to use Puppet; rather, it complements existing Puppet books, documentation, and training courses. Learning Puppet 4 (O’Reilly, 2016) provides an in-depth training guide to using and deploying Puppet, making it a useful introduction to the concepts discussed in this book.

The concepts and strategies presented are applicable to both green field (new build) and brown field (update in place) deployments of Puppet. We present concepts key to a stable foundation design that provides flexibility to grow and change. We explore strategies to eliminate pain points in existing environments, and make improvements that accelerate change velocity while reducing risk and minimizing impact.

Why We Wrote This Book

Our objective for this book is to share our professional experience to help IT, operations, security, and developer professionals solve problems and improve the overall quality of code and infrastructure deployed in the real world.

This book draws heavily from our experiences as Puppet consultants. Any site deploying Puppet can do more with less, and thus many grow both quickly and organically. The consequences of design decisions that were made early in development often had repercussions that were not obvious when originally made. As code became established and moved to production, it became more and more difficult to correct those problems without risking the stability of the site that code manages.

Many folks who have deployed Puppet on their own are bright and talented individuals, quick to learn and make use of the many features of Puppet. As they take on more demanding needs with Puppet, they often find very innovative, even superlative, ways of using Puppet features to solve problems. Unfortunately, some of those innovative designs produce code that is difficult to understand and nearly impossible to refactor or reuse in a general manner.

This problem isn’t specific to Puppet. Any powerful tool can be used in ways the designers never intended. As the configuration management codebase grows to handle all applications and services, it can quickly dwarf any other single codebase maintained by your organization.

This book highlights design patterns, both good and bad, that you can use when deploying Puppet environments, and discusses the impact of each decision. The conceptual designs and implementation patterns contained in this book will help you to create solutions that can be extended, maintained, and supported—not only by yourself, but by diverse global teams and the people who might inherit your work down the road.

A Word on Puppet Today

First, we’d like to take a moment to acknowledge all of you who have been waiting for this book. Compiling the best of existing practices on a product and community that are constantly evolving and refining is more difficult than you might expect. Some of these practices were updated just hours before the book went to press.

Puppet Best Practices have evolved continuously since Puppet’s early releases. In every way, Puppet is much easier to work with and support than it was five years ago. For example, puppet lookup and the new multilayered approach to Hiera data that allows data hierarchies in environments and modules have made it much simpler to create and reuse community modules.

On the other hand, change requires adaptation and refactoring. The new parser used by Puppet 4 and higher have introduced new syntax and deprecated some older features. Puppet design patterns have evolved, and the demarcation points between various systems aren’t always clear. Even just picking which versions to support—never mind which practices to highlight—involved many hours of debate between two authors who wanted to help the most people possible.

We feel that this is the very best book we can give you today. Best practices will continue to evolve. Common complaints will be resolved. New issues will be discovered. This process will iterate indefinitely. We look forward to seeing you present a new pattern that we hadn’t imagined when this book was written, either in your blog, at a Puppet camp, or a conference. We are absolutely confident that you will.

We intend to keep updating this book as Puppet and its usage evolves, keeping it current and relevant. As you read this, the next update to this book is already in progress—with an entire new chapter about Puppet Tasks—as the community development starts to find common ground.

Navigating This Book

This book is organized as follows:

• Chapters 1 through 3 discuss design concepts, philosophy, and practices that drive the recommendations made throughout this book.

• Chapters 4 through 8 provide concrete recommendations for major components of Puppet, such as Modules, Hiera, roles and profiles, and external node classifiers.

• Chapter 9 covers development and release management practices for Puppet developers, including r10k, test environments, linting, and editors.

• Chapter 10 covers extending Puppet—the development of new resource types, providers, facts, and features for Puppet.

This book is organized so that you can read it front to back; however, most of the chapters in this book are fairly self-contained and will provide references to other topics where appropriate. After you’ve read through it entirely, it is our sincere hope that you will return to individual sections when needed to address a difficult problem, to refresh your knowledge, or to pick up strategies that you might have overlooked on the first read.

Tip

We encourage you to read linearly through Chapter 3, because key concepts are introduced that we refer to throughout the book. After that, feel free to skip around to topics that interest you.

If you find anything in this book confusing or incomplete, we encourage you to reach out for clarification. Our goal is to produce the best work we possibly can. Your feedback is invaluable to this effort, and very much appreciated.

Online Resources

Following are some resources that you might find useful:

• Official documentation

• Where to find help

• Puppet community chat

• Mailing lists, local user groups, and so forth

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Tip

This icon signifies a tip, suggestion, or general note.

Note

This element signifies a general note.

Warning

This icon indicates a warning or caution.

Using Code Examples

This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Puppet Best Practices by Chris Barbour and Jo Rhett (O’Reilly). Copyright 2018 Chris Barbour and Joe Rhett, 978-1-491-92300-9.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

O’Reilly Safari

Note

Safari (formerly Safari Books Online) is a membership-based training and reference platform for enterprise, government, educators, and individuals.

Members have access to thousands of books, training videos, Learning Paths, interactive tutorials, and curated playlists from over 250 publishers, including O’Reilly Media, Harvard Business Review, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Adobe, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, and Course Technology, among others.

For more information, please visit http://oreilly.com/safari.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

• O’Reilly Media, Inc.
• 1005 Gravenstein Highway North
• Sebastopol, CA 95472
• 800-998-9938 (in the United States or Canada)
• 707-829-0515 (international or local)
• 707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://bit.ly/puppet-best-practices.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

Chris Barbour: This book would not have been possible without the patience and support of my wife and son.

Jo Rhett: The teams at every shop I’ve worked at and the Puppet community, especially including Vox Populi, have contributed tremendously to my own understanding as represented in this book. The patience and support of my fiance has made it possible for me to make this available to you.

Thanks most especially to Brian Anderson and Virginia Wilson, who have expended numerous hours aiming procrastinating writers in the right direction so that this book would be available and hopefully valuable to you. And to our reviewers and technical editors, who gave us feedback, helped us focus the content, and made this more complete than we’d ever thought possible.