modern module development - Ken Barber 2012 Edinburgh Puppet Camp

Modern Module Development 2012-03-23 Puppet Camp Edinburgh Ken Barber Professional Services Engineer ken@puppetlabs.com http://linkedin.com/in/ken_barber IRC & Twitter: @ken_barber

What is a module?• A re-usable way of sharing common components: • Classes • Deﬁned Resources • Ruby Resources • Files • Templates • Functions • Facts

We need more modules!

and they need tobe good quality ...

Whats new(ish) inModule Development? • Puppet Module Face • rspec-puppet • puppet-lint • Kwalify

But lets talkpatterns ﬁrst ...

Why are patterns important?

Class Patterns• Most installation and management problems consist of: • Installing software using files or packages • Modifying configuration files • Starting services

We commonly referto this pattern as: Package, Conﬁg, Service

Package Classclass bind::package { package { $bind::packages: ensure => installed, }}

Config Classclass bind::config { file { $bind::config_file: content => template(“${module_name}/named.conf”), owner => $bind::user, group => $bind::group, mode => ‘0644’, }}

Service Classclass bind::service { service { $bind::services: ensure => running, enable => true, hasstatus => true, hasrestart => true, }}

Main Classclass bind { anchor { ‘bind::start’: }-> class { ‘bind::package’: }~> class { ‘bind::conﬁg’: }~> class { ‘bind::service’: }~> anchor { ‘bind::end’: }}

What are anchors?• Provided in stdlib• Anchors are resource that ‘do nothing’• They ensure the edge of the classes are demarcated properly so the graph executes in the expected order

But what aboutdeﬁned resources?

Defined Resourcesdefine bind::zone ( $value = ‘nil’ ){ file { “/etc/bind/config.d/${name}.conf”: content => “${name} = ${value}n”, require => Class[‘bind::package’], notify => Class[‘bind::service’], }}

Package, Conﬁg, Service Pattern• This pattern is good for ~80% of situations.• Deals with ordering in a non-complex way, working with deﬁned resources as well.

Params Pattern

Default Parameters• Most parameters have OS dependant defaults.• In the past this was done with case statements in the main modules.

Class Parameters• I generally use two types of class parameters: • User-tuneable parameters • Advanced parameters for overriding items such as package name, service name conﬁguration ﬁle paths

Params PatternThe trick is to move your OS based param lookup intomanifests/params.pp: class bind::params { case $::operatingsystem { ubuntu, debian: { $package = bind9 $service = bind9 $conﬁg_dir = /etc/bind } ‘centos’, ‘redhat’: { $package = ‘bind’ $service = ‘bind’ $conﬁg_dir = ‘/etc/named’ } default: { fail(“Unknown OS: $::operatingsystem”) } } }

Params PatternThen inherit this in your base class like so: class bind ( $package = $bind::params::package, $service = $bind::params::service, $conﬁg_dir = $bind::params::conﬁg_dir ) inherits bind::params { ... }

Params PatternThen elsewhere in your code, reference the fullyqualiﬁed parameter from your bind class: class bind::package { package { $bind::packages: ensure => installed, } }

Puppet ModuleTool will now be a Puppet Face!

Puppet Module Tool# puppet help moduleUSAGE: puppet module <action>This subcommand can find, install, and manage modules from the Puppet Forge,a repository of user-contributed Puppet code. It can also generate emptymodules, and prepare locally developed modules for release on the Forge.OPTIONS: --mode MODE - The run mode to use (user, agent, or master). --render-as FORMAT - The rendering format to use. --verbose - Whether to log verbosely. --debug - Whether to log debug information.ACTIONS: build Build a module release package. changes Show modified files of an installed module. clean Clean the module download cache. generate Generate boilerplate for a new module. install Install a module from a repository or release archive. list List installed modules search Search a repository for a module. uninstall Uninstall a puppet module. upgrade Upgrade a puppet module.See puppet man module or man puppet-module for full help.

Puppet Module Face• Obviously still subject to design changes before release ....

ValidatingParameters

Validating Parameters• Your allowed set of class parameters are like an Interface Contract to your users• A lot of bugs in code are to do with bad input• We have three mechanisms for validating input: • parameter deﬁnitions in the class • stdlib validate_* functions • kwalify

Kwalify Validation• Uses the kwalify library - which is a language independent way of validating JSON/YAML style data structures.• Kwalify has binding in many languages - so its a nice universal choice for structured data validation.

Kwalify• Provides a single declarative way of deﬁning what parameters are valid.• When validation fails, it shows all cases of failure.• Doesn’t handle logical validation across components - you’ll have to do this yourself.

A Kwalify Schema in Puppet DSL $schema = { type => map, mapping => { name => { type => str, pattern => /^w+s*w+$/, }, age => { type => str, pattern => /^d+$/, }, }}

KwalifyValidation in DSLclass bind ( ... ){ $args = get_scope_args() $schema = { ... } kwalify($schema, $args)}

Module Testing

rspec-puppet• Tim Sharpe (@rodjek) from Github created it• Rspec is often used by Puppet for testing, so it made sense for us to use rspec-puppet• The same facility can be used for testing Puppet DSL and Ruby code as well: providers, types, facts etc.

rspec-puppet • Is able to test: • Classes • Deﬁned Resources • Nodes • Functions

rspec-puppet• Paths for tests: • Classes: • spec/classes/<name_of_class>_spec.rb • Defined Resources • spec/defines/<name_of_define>_spec.rb

rspec-puppetFor class testing, the idea is to test your compiledcatalogue. The following just tests if your classcompiles with no parameters: # spec/classes/bind_spec.rb require spec_helper describe bind, :type => :class do let(:facts) do { :operatingsystem => "CentOS" } end describe when only mandatory parameters are provided do let(:params) do {} end it class should get included do subject.should contain_class(bind) end end end

rspec-puppetYou also want to make sure your expectations of howthe catalogue should look after compilation are met: it ‘bind package should be deﬁned’ do subject.should contain_package(‘bind’) end it ‘bind service should be deﬁned’ do subject.should contain_service(‘bind’) end

rspec-puppet For testing templates, we can do something a little different:it changing authnxdomain should modify template do params = { :conﬁg_options = "/tmp/named.conf.options" :options = { "authnxdomain" => "yes", } } content = param_value("ﬁle", "/tmp/named.conf.options", "content") content.should =~ /authnxdomain yes/end

rspec-puppet Requires a spec/spec_helper.rb file with appropriate settings:require rspecrequire rspec-puppetrequire puppetrequire mochafixture_path = File.expand_path(File.join(File.dirname(__FILE__), fixtures))RSpec.configure do |c| c.module_path = File.join(fixture_path, modules) c.manifest_dir = File.join(fixture_path, manifests)end

rspec-puppetAlso the following should be added to your Rakeﬁleto get ‘rake spec’ to work: require rubygems require rspec/core/rake_task RSpec::Core::RakeTask.new do |t| t.pattern = spec/*/*_spec.rb end

Importance ofGood Coding Style

Importance ofGood Coding Style• Code is read much more often then it is written (did Guido van Rossum say this?)• Other people being able to read your code is important to attract contributors• Contributors make your code better and ultimately more successful

Style Guide• Available here: • http://docs.puppetlabs.com/guides/style_guide.html

puppet-lint• Also made by Tim Sharpe from Github• Uses the Puppet Labs style guide• Saves time, as it tells you what is wrong with your content before a code review

Using it in your RakeﬁleDownload the gem: gem install puppet-lintThen just add the following to your modules Rakeﬁle: require puppet-lint/tasks/puppet-lint

Running it:# rake lintEvaluating manifests/init.ppEvaluating manifests/conﬁg.ppEvaluating manifests/package.ppEvaluating manifests/service.pp

Packaging for the Forge

The Moduleﬁle• Provides meta data for your module• Includes dependencies • In the future the module tool can use these dependencies to download extra modules as needed• Is used to generate metadata.json, which is used by the forge

The Moduleﬁlename puppetlabs-bindversion 0.0.1source https://github.com/puppetlabs/puppetlabs-bind.gitauthor Puppet Labs Inc.license ASL 2.0summary ISC Bind Moduledescription Installs and conﬁgures the ISC BIND DNS serverproject_page http://forge.puppetlabs.com/puppetlabs/binddependency puppetlabs/stdlib, >= 2.2.1dependency puppetlabs/kwalify, >= 0.0.1dependency ripienaar/concat, >= 20100507

Packaging using the module tool# puppet-module build===================================================Building /Users/ken/Development/puppetlabs-bind for release-----------------------------------------------------------Done. Built: pkg/puppetlabs-bind-0.0.1.tar.gz

Uploading To the Forge• Create an account - this username will be publicly visible, so if you are a company create a shared one• Create a project - this is the short name of the module• Create a revision - this is the revision you wish to upload. Use semantic versioning if you can ie. 1.2.0, 3.1.2 etc.• Upload your revision, this is the tar.gz ﬁle created in pkg/ with puppet-module build

Using a forge moduleUsing the new module face you can install the forgemodule: # puppet module search bind # puppet module install puppetlabs-bind

Future WorkNeeded for Modules• Acceptance Testing • ‘Real’ build testing, perhaps using monitoring frameworks for acceptance?• Hiera and data lookup methodology • Using Hiera to emulate the params pattern

AnyQuestions?

modern module development - Ken Barber 2012 Edinburgh Puppet Camp

by Puppet Labs

Accessibility

Categories

Upload Details

Usage Rights

1 Embed 21

Statistics

modern module development - Ken Barber 2012 Edinburgh Puppet Camp Presentation Transcript