"Writing & Sharing Great Modules on the Puppet Forge" by Adrien Thebo of Puppet Labs at Puppet Camp Austin 2013.

1. WRITING & SHARING
GREAT MODULES
Adrien Thebo, Puppet Labs
Twitter: @nullfinch | Freenode: finch

2. WHO IS THIS GUY?
On/Off Ops/Dev, ~8 years
Operations Engineer @puppetlabs, 2 years
Community Developer @puppetlabs, 3 months

3. THINGS I DO
puppet-network: cross-platform network configuration
puppet-portage: Puppet ♥ Gentoo
r10k: smarter Puppet deployment, powered by robots
vagrant-hosts: it’s always a DNS problem
vagrant-pe_build: From zero to PE in vagrant up

4. OTHER THINGS I DO
Talk too fast
If I become completely unintelligible
slow me down

5. LET’S TALK ABOUT
MODULES

6. BEST PRACTICES‽
Traditional development: 40+ years to mature
Modern config. mgmt: 15 years, max
Best practices haven’t yet been established

7. SO WHERE DO WE START?
Separate your logic and configuration
Know your interface
Use semantic versioning
Reuse everything
Use the community

8. DATA/LOGIC
SEPARATION

9. SEPARATE LOGIC FROM DATA
Logic != Data
Example: configure a service on different platforms
Shouldn’t have to update every file in a module

10. PACKAGE/FILE/SERVICE
Humble beginnings for many modules
class mysql::server {
package { 'mysql-server':
ensure => present,
}
file { '/etc/mysql/my.cnf':
ensure => present,
content => template('mysql/server/my.cnf.erb'),
require => Package['mysql-server'],
}
service { 'mysqld':
ensure => running,
enable => true,
subscribe => File['/etc/mysql/my.conf'],
}
}

11. PROBLEMS WITH PACKAGE/FILE/SERVICE
Nothing inherently wrong
Overly simple
Very static
Generally requires overhaul for different platforms

12. RUDIMENTARY DATA/LOGIC SEPARATION
class mysql::server {
include mysql::params
package { 'mysql-server':
name => $mysql::params::server_package,
ensure => present,
}
file { 'my.cnf':
path => $mysql::params::server_config,
ensure => present,
source => 'puppet:///modules/nrpe/nrpe.cfg',
require => Package['nagios-nrpe-server'],
}
service { 'mysql-server':
name => $mysql::params::server_service,
ensure => running,
enable => true,
subscribe => File['my.cnf'],
}
}

13. HARDCODING TUNABLE VALUES
Want to prevent people from reusing your modules?
Hardcode everything!

14. USING PARAMS, BAD:
Params class = good
Why is this bad?
Site specific defaults?
INSECURE DEFAULTS‽
class mysql::params {
$allow_hosts = '0.0.0.0/0'
$root_user = 'root'
# ¯_(ツ)_/¯
$root_password = 'changeme'
}

15. USING PARAMS, GOOD:
Force user to supply data
Fail fast
class mysql::params(
$allow_hosts, # Force the module user to fill this out
$root_password, # Fail fast rather than potentially use bad data
$root_user = 'root' # Sane default
) {
}

16. DATA BINDING

17. DATA BINDING
New in Puppet 3: data binding
Provides a method for configuring modules

18. USING DATA BINDING
Define data in a data store
file
database
Foreman
Automatically load data in the relevant manifests

19. USING DATA BINDING
class mysql::params(
$allow_hosts,
$database_password,
$database_user = 'root'
) {
}
# $datadir/common.yaml
---
mysql::params::allow_hosts: '10.126.8.0/24'
# $datadir/qa.mysite.local.yaml
---
mysql::params::allow_hosts: '10.134.8.0/24'

20. USING MODULES AS
INTERFACES

21. MODULES AS INTERFACES
Puppet simplifies management of services
Defines how people interact with that service
Puppet modules define an interface for that service
Creates two challenges
What options are supported?
What options should users configure?

22. BE OPINIONATED
Cannot make every option tunable
You’ll go insane
Require mandatory data
Add parameters for frequently changed data
Offer an ‘override’ option

23. BUT OTHER OPINIONS ARE NICE TOO
You can’t always support every option
Allow people to directly insert their own configuration

24. OVERRIDE EXAMPLE: PARTIAL TEMPLATES
Module provides template fragments
User assembles these into a full config

25. CREATING A PARTIAL TEMPLATE
<%# nginx/templates/vhost/_listen.conf.erb %>
<%# Configuration fragment for listening on IPv4 and IPv6 with SSL %>
<% unless @sslonly -%>
listen <%= port %>;
<% if scope.lookupvar('::ipaddress6') -%>
listen [::]:<%= port %>;
<% end -%>
<% end -%>
<% if ssl -%>
listen <%= ssl_port %> ssl;
<% if scope.lookupvar('::ipaddress6') -%>
listen [::]:<%= ssl_port %> ssl;
<% end -%>
<% end -%>

26. USING PARTIAL TEMPLATES
Example: my_nginx_app/templates/nginx-
vhost.conf.erb
server {
<%= scope.function_template(['nginx/vhost/_listen.conf.erb']) %>
root /usr/share/empty;
location / {
proxy_pass <%= @proto %>://workers;
proxy_redirect off;
proxy_next_upstream error timeout invalid_header http_500 http_503;
proxy_connect_timeout 5;
}
}

27. SEMVER

28. WITHOUT SEMANTIC VERSIONING
A cautionary tale of versioning gone bad
1.0.0 Initial release for managing cacti
1.1.1 Change serverparam to servername
1.1.2 Move params from cacti::data to cacti::params
1.2.0 Updated README
1.2.1 Drops support for CentOS 5
1.3.0 This module now manages munin
2.0.0 I can update versions whenever I want?
10.51.100 THIS IS AWESOME!
-4.number.999999999999 I’VE CREATED A MONSTER

29. UPGRADING SHOULD BE BORING
API breaks mean upgrading is dangerous
Nobody wants to upgrade if it means explosions
Semantic versioning helps mitigate this

30. WHAT IS SEMVER?
Version strings should have meaning
Releases match the format x.y.z
Values indicate what’s changed in that version

31. MAJOR RELEASES
Example: x.0.0
Backwards incompatible changes
Changing class names
Changing parameter names
Dropping platform support

32. MINOR RELEASES
Example: x.y.0
Backwards compatible features
Adding support for new platforms
Adding parameters
Adding features

33. PATCH RELEASES
Example: x.y.z
Bugfixes
Documentation
Tests
Anything that can’t be called a feature

34. SEMVER AS A CONTRACT
If you use SemVer, you’re making an agreement to avoid
making breaking changes
What is a breaking change?
What’s public?
What’s private?

35. WHAT IS PUBLIC?
Publicly exposed classes
Class parameters
The final behavior of your class

36. WHAT IS PRIVATE?
The actual resources used in your classes and defines
Resources themselves are implementation, not
Classes that are documented as private
If you document that a class is private, people shouldn’t
use it

37. SAFETY IN SEMVER
SemVer takes the risk out of upgrading
You can understand the implications of upgrading right
away
How Puppet does it
3.1.0: Better support for Ruby code loading
3.1.1: Security fixes
3.2.0: External CA support, types & providers for
OpenWRT
4.0.0: Tachyon based transport layer
Not really.

38. MAKE OTHER PEOPLE DO
YOUR WORK

39. AKA

40. REUSE MODULES

41. REUSE MODULES
Writing good code is hard.
Make other people do your work.

42. DISCOVERY VIA THE FORGE
Puppet Forge has 1000+ modules
Provides a single point to discover and install modules
Easy access to documentation
README
CHANGELOG
Type & provider documentation

43. GET DEPENDENCIES FROM THE FORGE
grey% puppet module search postgres
Notice: Searching https://forge.puppetlabs.com ...
NAME DESCRIPTION
knowshan-phppgadmin Install and configure phpPgAdmin
DropPod-postgres A basic type for managing Postgres
camptocamp-pgconf Manage postgresql.conf entries
inkling-postgresql PostgreSQL defined resource types
akumria-postgresql Install and configure the Postgresql
puppetlabs-postgresql PostgreSQL defined resource types

44. COLLABORATE ON EXISTING MODULES
Lots of good modules are out there
Encourage people to publish on the Forge
Help improve existing modules
Onl you can prevent ecosystem fragmentation

45. SMALL CONTRIBUTIONS HELP
Documentation
Bug fixes
Issue reports

46. ESTABLISH A
COMMUNITY

47. SURVIVING SUCCESS
Your module is a hit!
Prepare for a deluge of bug reports and feature requests

48. POPULARITY = MORE WORK
Things users are good at:
Finding bugs
Filing feature requests
Requesting things like “documentation”
Finding more bugs
Funny how these match how you can help other
contributors

49. HARNESS YOUR USERS
Bug reports = people care
Show people how to help
Ask for pull requests
Guide people through the contribution process

50. END
QUESTIONS?
COMMENTS?
SNARKYREMARKS?
AWKWARD SILENCE?

51. CREDITS
PRESENTATION DONE WITH REVEAL.JS