Writing and Publishing Puppet Modules
Colleen Murphy, Portland State University
HelloThis is a beginner’s approach.
HelloPSU’s College of Engineering’s IT department, aka The Computer Action Team (TheCAT),uses puppet to manage a diverse infrastructure.
github.com/pdxcat
What is a puppet module?● An encapsulation of configuration for a
service● A structure containing an organized set of
puppet code and data● Analogous to a package, gem, python library● The place where your code goes
What should a module do?● Set up a service, such as:
○ ssh○ mysql○ apache○ sudo
● Extend puppet functionality. Examples:○ puppetlabs/stdlib○ puppetlabs/concat
The strategySet up the service… without puppet.
Then iterate.
Layout of a moduleyourmodule/
➔ manifests/ # where your puppet code goes➔ files/ # flat configuration files➔ templates/ # dynamic configuration files➔ lib/ # plugins: types and providers, functions,
| facts, etc➔ tests/ # smoke tests/example usage➔ spec/ # automated tests
Layout of a moduleyourmodule/
➔ manifests/ # where your puppet code goes➔ files/ # flat configuration files➔ templates/ # dynamic configuration files➔ lib/ # plugins: types and providers, functions,
| facts, etc➔ tests/ # smoke tests/example usage➔ spec/ # automated tests
Layout of a moduleyourmodule/
➔ manifests/ # where your puppet code goes➔ files/ # flat configuration files➔ templates/ # dynamic configuration files➔ lib/ # plugins: types and providers, functions,
| facts, etc➔ tests/ # smoke tests/example usage➔ spec/ # automated tests
Starting out$ puppet module generate cmurphy-ssh && mv cmurphy-ssh sshGenerating module at /etc/puppet/modules/cmurphy-sshcmurphy-sshcmurphy-ssh/manifestscmurphy-ssh/manifests/init.ppcmurphy-ssh/speccmurphy-ssh/spec/spec_helper.rbcmurphy-ssh/testscmurphy-ssh/tests/init.ppcmurphy-ssh/READMEcmurphy-ssh/Modulefile
$ mkdir ssh/{files,templates}
Writing your first module# manifests/init.pp
class ssh {
package { 'openssh-server': ensure => installed, } file { '/etc/ssh/sshd_config': source =>
"puppet:///modules/ssh/sshd_config", require => Package['openssh-server'], } service { 'ssh': ensure => running, enable => true, subscribe =>
File['/etc/ssh/sshd_config'], }
}
# tests/init.ppinclude ssh
# or
# /etc/puppet/manifests/site.ppnode default { include ssh}
Drop in a configuration file# files/sshd_config
# Managed by Puppet
# What ports, IPs and protocols we listen for
Port 22
Protocol 2
# Logging
SyslogFacility AUTH
LogLevel INFO
# Authentication:
LoginGraceTime 120
PermitRootLogin no
StrictModes yes
# ...
Needs more portability!
No one should have to change your code or your files in order to use your module.
Template your module# templates/sshd_config.erb
# Managed by Puppet
# What ports, IPs and protocols we listen for
Port <%= @port %>
Protocol 2
# Logging
SyslogFacility <%= @syslog_facility %>
LogLevel <%= @log_level %>
# Authentication:
LoginGraceTime 120
PermitRootLogin <%= @permit_root_login %>
StrictModes yes
# ...
Template your module# manifests/init.pp
class ssh (
$port = 22,
$syslog_facility = 'AUTH',
$log_level = 'INFO',
$permit_root_login = 'no',
) {
# ... file { '/etc/ssh/sshd_config': content =>
template('ssh/sshd_config.erb'), require => Package['openssh-server'], }
# ...
# Applying the classclass { 'ssh': permit_root_login => 'without-password',}
Templating strategies# manifests/init.pp
class ssh (
$ports = [ 22 ],
$options = {}
) {
# ... file { '/etc/ssh/sshd_config': content =>
template('ssh/sshd_config.erb'), require => Package['openssh-server'], }
# ...
# Applying the classclass { 'ssh': ports => [ 22, 2222 ], options => { 'PermitRootLogin' => 'no', }}
Templating strategies# templates/sshd_config.erb
# Managed by Puppet
<% @ports.each do |port| %>
Port <%= port %>
<% end %>
<% @options.each do |k,v| %>
<%= k %> <%= v %>
<% end %>
Templating strategiesWorking with tricky configuration files● Take advantage of Include conf/* directives
file { '/etc/collectd.conf': ensure => present, content => 'Include "conf.d/*.conf"\n',}# …define collectd::plugins::exec { file { "${name}.load": path => "${conf_dir}/${name}.conf", content => template('collectd/exec.conf.erb'), }}
Beyond templates● puppetlabs/concat
concat { '/etc/motd': }
concat::fragment { 'welcome':
target => '/etc/motd',
content => 'Welcome to Redhat',
order => '01',
}
concat::fragment { 'legal':
# … }
Beyond templates● puppetlabs/inifile
ini_setting { 'puppetdbserver':
ensure => present,
section => 'main',
path => "${puppet_confdir}/puppetdb.conf",
setting => 'server', value => $server,}
ini_setting { 'puppetdbport':
# …}
Beyond Templates● augeas
● domcleal/augeasproviders
augeas { 'sshd_config_permit_root_login': context => '/files/etc/ssh/sshd_config', changes => "set PermitRootLogin $permit_root_login", require => File['/etc/ssh/sshd_config'],}
sshd_config { "PermitRootLogin":
ensure => present,
value => $permit_root_login,
}
Smart Parameter Defaults# manifests/params.pp
class ssh::params {
case $::osfamily {
'Debian': {
$ssh_svc = 'ssh'
}
'Redhat': {
$ssh_svc = 'sshd'
}
default: {
fail("${::osfamily} is not supported.")
}
}
}
# manifests/init.ppclass ssh (
# ...) { include ssh::params
service { $ssh::params::ssh_svc: ensure => running, enable => true, }
# ...
The Forge
Publishing your moduleModulefilename 'cmurphy-ssh'version '0.0.1'source 'https://github.com/cmurphy/puppet-module-ssh.git'author 'Colleen Murphy'license 'Apache License, Version 2.0'summary 'Puppet module for ssh'description 'Demonstration of parameterized ssh module'project_page 'https://github.com/cmurphy/puppet-module-ssh'
## Add dependencies, if any:# dependency 'username/name', '>= 1.2.0'
Publishing your moduleREADME● docs.puppetlabs.com/puppet/3/reference/READMEtemplate.markdown
license● choosealicense.com
Publishing your moduleChangelog## 2013-12-05 Release 0.10.0### Summary:
This release adds FreeBSD osfamily support and various other improvements to some mods.
### Features:
- Add suPHP_UserGroup directive to directory context- Add support for ScriptAliasMatch directives...
## 2013-09-06 Release 0.9.0### Summary:
...
Publishing your moduleUse semantic versioning! semver.org
Major.Minor.Patch
Publishing your module$ cd ssh/
$ puppet module build .
$ ls pkg/
cmurphy-ssh-0.0.1 cmurphy-ssh-0.0.1.tar.gz
TestingWhy we test:● Testing gives us (some) assurance that our
code won’t break production systems● Contributors can run tests without having
the same infrastructure as you
Testing your module● Smoke testing
# puppet apply --noop tests/init.pp
Testing your module● Unit testing: rspec-puppet
○ rspec-puppet.com
$ bundle exec rake spec
Testing your module# spec/classes/init_spec.rb
require 'spec_helper'
describe 'collectd' do
let :facts do
{:osfamily => 'RedHat'}
end
it { should contain_package('collectd').with(
:ensure => 'installed'
)}
it { should contain_service('collectd').with(
:ensure => 'running'
)}
# ...
Testing your module● Acceptance testing: beaker-rspec
○ github.com/puppetlabs/beaker○ youtu.be/jEJmUQOlaDg
$ bundle exec rspec spec/acceptance
Testing your module# spec/acceptance/class_spec.rb
require 'spec_helper_acceptance'
case fact('osfamily')
# ...describe 'ssh class' do context 'default parameters' do it 'should work with no errors' do pp = "class { 'ssh': }"
# Run it twice and test for idempotency apply_manifest(pp, :catch_failures => true) apply_manifest(pp, :catch_failures => true)
end
describe service(servicename) do it { should be_running } end
# ...
Testing your module● Linting
$ bundle exec rake lint
Maintaining your moduleUpdate your code● fix bugs● add features● manage pull requests
Installing modulesSearch for modules on forge.puppetlabs.com or puppet module search
Then install with puppet module install
Where now?Learn more at docs.puppetlabs.com/guides/module_guides/bgtm.html
Get help atAsk: ask.puppetlabs.comIRC: #puppet on freenodeMailing list: groups.google.com/group/puppet-users
Thanks!Find me:
Colleen Murphyfreenode: crinklegithub: cmurphy
twitter: @pdx_krinkle