search

abstractitptyltd / abstractit-puppet

Manage puppet agent, master, modules and hiera with puppet
https://forge.puppetlabs.com/abstractit/puppet
18 stars 44 forks source link

readme

abstractit-puppet

Build Status Puppet Forge Puppet Forge Downloads Puppet Forge Modules

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with puppet
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module
  8. Contributors
  9. Release Notes/Etc

Overview

Manage puppet master, agents, modules using the same principals as you manage your other services.

Module Description

This module is very opinionated. It makes a few assumptions on how to manage a puppet master and it's agents. These opinions are what I consider the best way to do things based on my experiences using puppet. Those opinions have also been heavily influenced by the likes of Gary Larizza, Zack Smith, Craig Dunn and Adrien Thebo.

If you would like this module to behave differently I am happy to accept pull requests. Please maintain backwards compatibility wherever prudent.

Right now that that's out of the way here's how it works. Out of the box it manages the pupetlabs repo, the puppet agent, the versions installed and it's environment. It can also optionally manage some facts using the facter.d structure (I use these in my hiera setup). On a puppet master it manages the puppet master, passenger, a few dependencies, their versions, hiera and some basic config. It can also optionally manage a module environment (or environments) and a hiera repo with r10k and puppetdb.

I believe Puppet needs to be managed just as explicitly as any other service in your environment. It may not be the best way to do it but it's how I do it and it works for me. This module is how I manage puppet for my clients so it gets extensive testing in production and in my vagrant based development environments. If it works for you, awesome! If not, let me know or send me a pull request.

Setup

What puppet affects

Setup Requirements

This module currently only works completely on Ubuntu Precise and Trusty. Support for RedHat and CentOS 5,6 and 7 has been added for the new Collections and Puppet 4.x. The new puppet-agent and puppetserver are supported on Ubuntu, Centos and RedHat but a puppet master running under Passenger is only supported on Ubuntu.

I will be adding support for other operating systems when I get a chance. It also only configures puppet 3.6.x and 4.x If you need support for previous versions let me know.

Forge Module dependencies

Beginning with puppet

The best way to begin is using the example profiles puppet::profile::agent and puppet::profile::master These profiles will setup agent and master nodes. I also have profiles for setting up R10K, puppetdb and puppetboard.

Usage

All interactions with puppet in done via the base classes puppet and puppet::master or the profiles I generally include the agent profile on all nodes and use hiera to setup the data. I have included some basic examples for setting up common settings on the agent or master.

Basic setup of an agent

include '::puppet'

or include '::puppet::profile::agent'

Setup custom facts on an agent

class { '::puppet::profile::agent':
  custom_facts => {
    'data_centre' => 'office',
    'role'        => 'webserver',
  }
}

Set a ca_server for your environment

class { '::puppet::profile::agent':
  ca_server => 'puppetca.domain.com'
}

Enable cfacter

class { '::puppet::profile::agent':
  cfacter => true
}

Use packages for repository management

class { '::puppet::profile::agent':
  manage_repo_method => 'package'
}

Disable repository management

class { '::puppet::profile::agent':
  manage_repos => false
}

Set allinone and puppet collection use on your infrastructure

class { '::puppet::profile::agent':
  allinone   => true,
  collection => 'PS1'
}

Set environment for the agent

class { '::puppet::profile::agent':
  environment => 'testenv'
}

Set use the new msgpack serialization format on an agent

class { '::puppet::profile::agent':
  preferred_serialization_format => 'msgpack'
}

Basic setup of a puppet master

include '::puppet'
include '::puppet::master'

or include '::puppet::profile::agent' include '::puppet::profile::master' include '::puppet::profile::puppetdb' include '::puppet::profile::puppetboard' include '::puppet::profile::r10k'

to setup a master with all the features

Set basemodulepath for the master

class { '::puppet::profile::master':
  basemodulepath => '/opt/puppet_code/modules:/etc/puppet/modules'
}

Set ram for new puppet server on the master

class { '::puppet::profile::master':
  java_ram => '1532'
}

Set ram for new puppet server on the master

class { '::puppet::profile::master':
  java_ram => '1532M'
}

Setup basic autosigning

class { '::puppet::profile::master':
  autosign_method => 'file',
  autosign_domains => ['*.sub1.domain.com','*.sub2.domain.com'],
}

Reference

Classes and Defined Types

In the near future I will be moving these docs into each class into a format suitable for to puppet-strings.

[Public] Class: puppet

Description

The puppet class is responsible for validating some of our parameters, and instantiating the puppet::facts, puppet::repo, pupppet::install, puppet::config, and puppet::agent manifests.

Parameters

[Private] Class: puppet::agent

Description

The puppet::agent class is responsible for management of the of the agent service, and agent cronjob. depending on the

Parameters

[Private] Class: puppet::config

Description

The puppet::config class is responsible for altering the configuration of $confdir/puppet.conf. This is done via params which call ini_file resources to alter the related settings.

Parameters

[Public] Defined Type: puppet::fact

Description

This defined type provides a mechanism to lay down fact files in /etc/facter/facts.d/ The title of the declared resource will dictate the name of the factname.yaml file laid down, as well as the keyname, and thus, the fact name.

Parameters

[Private] Class: puppet::facts

Description

The puppet::facts class is responsible for ensuring that /etc/facter and /etc/facter/facts.d are present on the local system. It is additionally responsible for populating /etc/facter/facts.d/local.yaml with the Key/Value pairs declared in puppet::facts::custom_facts

Parameters

[Private] Class: puppet::install

Description

the puppet::install class is responsible for the puppet agent, hiera, and facter packages.

Parameters

[Public] Class: puppet::master

Description

The puppet::master class is responsible for performing some input validation, and subsequently configuring a puppetmaster. This is done internally via the puppet::master::config, puppet::master::hiera, pupppet::master::install, and puppet::master::passenger manifests.

Parameters

[Private] Class: puppet::master::config

Description

The puppet::master::config class is responsible for managing the master-specific configuration settings of puppet.conf

Parameters

[Private] Class: puppet::master::hiera

Description

The puppet::master::hiera class is responsible for configuring hiera, optionally deploying eyaml encryption keys, and setting the ownership of the hieradata path.

Parameters

[Private] Class: puppet::master::install

Description

The puppet::master::install class is responsible for installing the packages required to configure a puppetmaster.

Parameters

[Private] Class: puppet::master::passenger

Description

The puppet::master::passenger class is responsible for instantiating the apache class, creating the apache vhost, and configuring passenger.

On Trusty, We need to be able to set SSLCARevocationCheck in apache 2.4+ to enable revocation checks for client certs. According to the Official puppetlabs docs on passenger: Apache 2.4 introduces the SSLCARevocationCheck directive and sets it to none which effectively disables CRL checking. If you are using Apache 2.4+ you must specify 'SSLCARevocationCheck chain' to actually use the CRL.

Parameters

[Private] Class: puppet::repo

Description

This class is responsible for including the proper package repository subclass. This is done based on the osfamily fact.

[Private] Class: puppet::repo::apt

Description

This class is responsible for optionally managing the presence of the puppetlabs apt repositories. It consults the $::puppet::manage_repos param to decide if it should perform any action. If it should, it references $::puppet::enable_repo

Parameters

[Private] Class: puppet::repo::yum

Description

This class is responsible for optionally managing the presence of the puppetlabs yum repositories. It consults the $::puppet::manage_repos param to decide if it should perform any action. If it should, it references $::puppet::enable_repo

Parameters

Limitations

It only supports an agent setup on RedHat and CentOS at this stage. Passenger is only supported on Ubuntu

Development

Development and testing team consists of @rendhalver and @wolfspyre. The module gets extensive testing in Abstract IT and it's clients environments. Pull requests are welcome.

Contributors

https://github.com/abstractitptyltd/abstractit-puppet/graphs/contributors

Release Notes/Etc

Check the CHANGELOG.md for release notes and bug fixes. It's a bit sparse right now and only contains the public releases.