Puppet Best Practices

Table of contents

1. Preface
   1. What Is a Best Practice?
   2. Who Should Read This Book
   3. Why We Wrote This Book
   4. A Word on Puppet Today
   5. Navigating This Book
   6. Online Resources
   7. Conventions Used in This Book
   8. Using Code Examples
   9. O’Reilly Safari
   10. How to Contact Us
   11. Acknowledgments
2. 1. The Puppet Design Philosophy
   1. Declarative Code
      1. What Is Declarative Code, Anyway?
      2. Resource Types and Providers
      3. Procedural Example
      4. Nondeclarative Code with Puppet
   2. Idempotency
      1. Side Effects
      2. Resource-Level Idempotence
      3. Run-Level Idempotence
      4. Nondeterministic Code
   3. Stateless
      1. Benefits of Stateless Design
      2. Sources of State Information
   4. Summary
3. 2. High-Level Code and Data Design
   1. Code and Data Organization
      1. Code and Data Categories
      2. Types of Code Logic
      3. Examples of Logic Types
   2. Mapping Data Types to Puppet Use Cases
      1. Application Logic and Puppet Modules
      2. Business Logic Should Not Be Written into Component Modules
      3. Business Logic with Roles and Profiles
      4. Business, Service, Site, Node, and Application Data
      5. Hiera Data Sources
      6. Node Classification
   3. Summary
4. 3. Coding Practices
   1. The Style Guide
   2. Coding Principles
      1. KISS: Keep It Simple
      2. The Single Responsibility Principle
      3. Separation of Concerns
      4. Interface-Driven Design
      5. DRY: Don’t Repeat Yourself
      6. Don’t Reinvent the Wheel
   3. Code Practices
      1. Balance of Resources Versus Logic
      2. Balance of Code Versus Data
      3. Conditional Logic
      4. Iteration
      5. Generating Lists
   4. Variables
      1. Variable Naming
      2. Referencing Variables
      3. Other Variable Use Cases
      4. Trusted Variables
      5. Order of Assignment for Top-Level Variables
      6. Assignment with Selectors
      7. Attribute Values Chosen by Conditional Evaluation
      8. Variable Inheritance
      9. Strict Variables
   5. Function Calls
      1. Always Use Parentheses
      2. Functions for Logging and Debugging
      3. String Manipulation Functions
      4. Path Manipulation
      5. Input Validation Functions
      6. Catalog Tests
   6. Data Transformation
   7. Templates
      1. ERB Templates
      2. EPP Templates
      3. EPP Versus ERB
   8. Other Language Features
   9. Summary
5. 4. Puppet Module Design
   1. The Puppet Development Kit
      1. Installing the Puppet Agent
      2. Using the Ruby that Comes Bundled with Puppet
      3. Installing the Puppet Development Kit
      4. Favor Editors or IDEs with Puppet Plugins
   2. Using Vendor-Provided or Community Modules
      1. Picking Good Modules
      2. Module Checklist
      3. Module Applicability to Your Needs
      4. Contributing Modules
   3. Designing Modules Well
      1. Make Use of Module Structure
      2. Keep the Module Focused
      3. Design Modules for Public Consumption
   4. Planning and Scoping Your Module
      1. Basic Module Layout
      2. The Module’s Main Class
      3. Module Parameters
      4. Input Validation
   5. Data in the Module
      1. The params.pp Pattern
      2. Hiera Data in Modules
   6. Modularizing Classes
      1. Dependencies
      2. Class Relationships
      3. Class Containment
      4. Interfacing with Classes
   7. Reusing Defined Types
      1. Providing Clean Service Interfaces with Defined Types
      2. Simplify Complex Operations with a Defined Type
      3. Interacting with Other Resouces in the Module
   8. Creating Useful Documentation
      1. README, REFERENCE, and Other Markdown
      2. REFERENCE Markdown
   9. Summary
6. 5. Resources
   1. Using Resources to Implement Change
      1. Resource Types Abstract Implementation Details
      2. Use the Most Specific Resource Type
      3. Examining a Naked Resource
      4. Exploring Resources with Tools
   2. Resource Declaration
      1. Ensure states
      2. Use Variables for Data-Driven Declaration
      3. Use Arrays for Similar Resources
      4. Using Automatic Resource Relationships for Clean Code
      5. Resource Declaration by Functions
      6. Resources Metatypes
      7. Resource Metaparameters
      8. Avoid Parse-Order Problems by Using Virtual Resources
      9. Exporting Resources
   3. Overriding and Modifying Declared Resources
      1. Resource Default Statements
      2. Resource Chaining
      3. Resource Collectors
   4. Resource Best Practices
      1. Custom Resource Types
      2. Useful Defined Types
   5. Summary
7. 6. Hiera Data
   1. Separating Code and Data
      1. Global, Environment, and Module Data
      2. Hiera Backends
   2. Designing the Hiera Hierarchy
      1. Variable Interpolation
      2. Design Guidelines
      3. Useful Hierarchy Levels
      4. Eliminating Data
   3. Accessing Hiera
      1. Automatic Parameter Lookups
      2. Hiera Function Calls
      3. Converting Serialized Hiera Data into Resource Declarations
      4. Interpolation in Your Data
   4. The Built-In Backends
      1. YAML
      2. JSON
      3. HOCON
      4. eYAML
   5. Custom Hiera Backends
      1. Database and NoSQL Engines
      2. Service Discovery Backends
      3. Encrypted Key/Value Storage
   6. Summary
8. 7. Roles and Profiles
   1. Roles
      1. Creating Readable Roles
      2. Design Roles for a Singular Use Case
      3. Provide the Role for Use in Data Lookups
   2. Profiles
      1. A Sample Service Profile
      2. Providing Actionable Data in Profile Parameters
      3. Implementing Business Logic in Profiles
      4. Defining Module Relationships in Profiles
      5. Creating Metaprofiles to Group Configurations
      6. Designing an Appropriate Profile Structure
   3. Testing Roles and Profiles
      1. Validating Profiles by Using Unit Tests
      2. Confirming Profile Implementation with Acceptance Tests
   4. Summary
9. 8. Node Classification
   1. What Data Should the Node Classifier Provide?
      1. Roles and Profiles
      2. Node-Specific Data
   2. Node Statements
      1. Node Statement Matching
      2. Replacing Node Inheritance
      3. Node Parameters Within Node Blocks
   3. Fact-Based Classification
      1. Fact-Based Role Assignment
      2. Security and Fact-Selected Roles or Profiles
      3. Fact-Based Hiera Classification
      4. Node Parameters with Hiera Classification
      5. Avoiding Node Data in Manifests
      6. Serverless Classification
   4. ENCs
      1. What Data Can an ENC Provide?
      2. Puppet Management Consoles
      3. Inventory and Infrastructure Management ENCs
   5. Summary
10. 9. Release Engineering and r10k
    1. Puppet Environments in Depth
       1. Puppet Directory Environments
       2. Selectable Blocks for Catalog Building
       3. Environment Configuration
       4. Environment Independence and Isolation
    2. Deploying with r10k
       1. What Does r10k Actually Do?
       2. The Control Repository
       3. Control Repository Branch Contents
       4. r10k Configuration File
       5. Puppetfile
       6. r10k Deployment Walkthrough
    3. Uses for r10k
       1. Build Development Environments
       2. Simplifying Acceptance Testing
       3. Implement Continuous Integration, Delivery, and Deployment
       4. Deploy Production Environments
       5. Build and Package
    4. Release Management Strategies with r10k
       1. Stage/Production Branches
       2. Single Branch (GitHub Flow)
       3. GitFlow
    5. Invoking r10k
       1. Puppet Prerun Command
       2. Deploying on Receipt of a WebHook
       3. Orchestrating Deployments with MCollective/Choria
       4. Invoking r10k in Testing Frameworks
       5. Combining Multiple Invocation Methods
    6. Migrating to r10k
       1. Repository-per-Module Benefits
       2. Configuring an Environment in the Control Repository
       3. Enabling Monolithic and Per-module Hybrid Deployment
       4. Moving Modules to their Own Repositories
       5. Placing Roles and Profiles in the site/ Module Directory
       6. Remove Fully Qualified Paths
       7. Moving Shared Tools to Their Own Repository
       8. Implementing Test Cases
    7. Best Practices for Puppet Deployments
       1. Using Repository Access Control to Enforce Deployment Policy
       2. Enabling Multiteam Coordination
       3. Pinning Module Versions
       4. Isolating Puppet Extensions
       5. Utilizing Standard Environment Configuration Practices
       6. Git Best Practices
       7. Deployment Practices
    8. Summary
11. 10. Extending Puppet
    1. The Cost of Extending Puppet
       1. Minimizing Development Costs
       2. Reducing Upgrade Costs
    2. Testing
       1. Static Code Analysis
       2. Unit Testing
       3. Acceptance Testing
    3. Creating Facts
       1. Distributing Facts in Modules
       2. Facts Puppet Can’t Know
       3. Structured Facts
       4. Abusing Facts
       5. Trusted Certificate Attributes
    4. Custom Types and Providers
       1. Avoiding Creation of Duplicate Types
       2. Creating a New Resource Type
       3. Custom Resource Providers
       4. Reuse Existing Frameworks
    5. Creating Custom Hiera Backends
       1. Choose the Appropriate Backend Type
       2. Creating a High-Performance Backend
    6. Using Puppet’s Public Classes and Method Calls
       1. Puppet Faces
       2. Indirection
    7. Deploying Extensions
       1. pluginsync
       2. Deploying Gem Dependencies
       3. Deploying Ruby Gem Extensions on Puppet Server
    8. Summary
12. Index