The Puppet language style guide

Spacing, indentation, and whitespace

Module manifests should follow best practices for spacing, indentation, and whitespace.

Manifests:

• Must use two-space soft tabs.
• Must not use literal tab characters.
• Must not contain trailing whitespace.
• Must include trailing commas after all resource attributes and parameter definitions.
• Must end the last line with a new line.
• Must use one space between the resource type and opening brace, one space between the opening brace and the title, and no spaces between the title and colon.
  Good:

  file { '/tmp/sample':

  Bad: Space between title and colon:

  file { '/tmp/sample' :

  Bad: No spaces:

  file{'/tmp/sample':

  Bad: Too many spaces:

  file     { '/tmp/sample':

Arrays and hashes

To increase readability of arrays and hashes, it is almost always beneficial to break up the elements on separate lines.

service { 'sshd':
  require => [
    Package['openssh-server'],
    File['/etc/ssh/sshd_config'],
  ],
}

$myhash = {
  key       => 'some value',
  other_key => 'some other value',
}

service { 'sshd':
  require => [ Package['openssh-server'], File['/etc/ssh/sshd_config'], ],
}

$myhash = { key => 'some value', other_key => 'some other value', }

service { 'sshd':
  require => [ Package['openssh-server'],
    File['/etc/ssh/sshd_config'],
  ],
}

$myhash = { key => 'some value',
  other_key     => 'some other value',
}

service { 'sshd':
  require => [
              Package['openssh-server'],
              File['/etc/ssh/sshd_config'],
  ],
}

Quoting

As long you are consistent, strings may be enclosed in single or double quotes, depending on your preference.

Enclose all variables in braces when interpolated in a string.

For example:

"/etc/${file}.conf"
"${facts['operatingsystem']} is not supported by ${module_name}"

"/etc/$file.conf"
"$facts['operatingsystem'] is not supported by $module_name"

warning("Class['apache'] parameter purge_vdir is deprecated in favor of purge_configs")

warning('Class[\'apache\'] parameter purge_vdir is deprecated in favor of purge_configs')

Escape characters

Use backslash (\) as an escape character.

For both single- and double-quoted strings, escape the backslash to remove this special meaning: \\ This means that for every backslash you want to include in the resulting string, use two backslashes. As an example, to include two literal backslashes in the string, you would use four backslashes in total.

Do not rely on unrecognized escaped characters as a method for including the backslash and the character following it.

Unicode character escapes using fewer than 4 hex digits, as in \u040, results in a backslash followed by the string u040. (This also causes a warning for the unrecognized escape.) To use a number of hex digits not equal to 4, use the longer u{digits} format.

Comments

Comments must be hash comments (# This is a comment). Comments should explain the why, not the how, of your code.

Do not use /* */ comments in Puppet code.

# Configures NTP
file { '/etc/ntp.conf': ... }

/* Creates file /etc/ntp.conf */
file { '/etc/ntp.conf': ... }

Functions

Avoid the inline_template() and inline_epp() functions for templates of more than one line, because these functions don’t permit template validation. Instead, use the template() and epp() functions to read a template from the module. This method allows for syntax validation.

You should avoid using calls to Hiera functions in modules meant for public consumption, because not all users have implemented Hiera. Instead, we recommend using parameters that can be overridden with Hiera.

Resource names

All resource names or titles must be quoted. If you are using an array of titles you must quote each title in the array, but cannot quote the array itself.

Good:

package { 'openssh': ensure => present }

Bad:

package { openssh: ensure => present }

These quoting requirements do not apply to expressions that evaluate to strings.

Arrow alignment

To align hash rockets (=>) in a resource's attribute/value list or in a nested block, place the hash rocket one space ahead of the longest attribute name. Indent the nested block by two spaces, and place each attribute on a separate line. Declare very short or single purpose resource declarations on a single line.

Good:

exec { 'hambone':
  path => '/usr/bin',
  cwd  => '/tmp',
}

exec { 'test':
  subscribe   => File['/etc/test'],
  refreshonly => true,
}

myresource { 'test':
  ensure => present,
  myhash => {
    'myhash_key1' => 'value1',
    'key2'        => 'value2',
  },
}

notify { 'warning': message => 'This is an example warning' }

Bad:

exec { 'hambone':
path  => '/usr/bin',
cwd => '/tmp',
}

file { "/path/to/my-filename.txt":
  ensure => file, mode => $mode, owner => $owner, group => $group,
  source => 'puppet:///modules/my-module/productions/my-filename.txt'
}

Attribute ordering

If a resource declaration includes an ensure attribute, it should be the first attribute specified so that a user can quickly see if the resource is being created or deleted.

Good:

file { '/tmp/readme.txt':
  ensure => file,
  owner  => '0',
  group  => '0',
  mode   => '0644',
}

When using the special attribute * (asterisk or splat character) in addition to other attributes, splat should be ordered last so that it is easy to see. You may not include multiple splats in the same body.

Good:

$file_ownership = {
  'owner' => 'root',
  'group' => 'wheel',
  'mode'  => '0644',
}

file { '/etc/passwd':
  ensure => file,
  *      => $file_ownership,
}

Resource arrangement

Within a manifest, resources should be grouped by logical relationship to each other, rather than by resource type.

Good:

file { '/tmp/dir':
  ensure => directory,
}

file { '/tmp/dir/a':
  content => 'a',
}

file { '/tmp/dir2':
  ensure => directory,
}

file { '/tmp/dir2/b':
  content => 'b',
}

Bad:

file { '/tmp/dir':
  ensure => directory,
}

file { '/tmp/dir2':
  ensure => directory,
}

file { '/tmp/dir/a':
  content => 'a',
}

file { '/tmp/dir2/b':
  content => 'b',
}

Use semicolon-separated multiple resource bodies only in conjunction with a local default body.

Good:

$defaults = { < hash of defaults > }

file {
  default: 
    * => $defaults,;

  '/tmp/foo':
    content => 'foos content',
}

Good: Repeated pattern with defaults:

$defaults = { < hash of defaults > }

file {
  default: 
    * => $defaults,;

  '/tmp/motd':
    content => 'message of the day',;

  '/tmp/motd_tomorrow':
    content => 'tomorrows message of the day',;
}

Bad: Unrelated resources grouped:

file {
  '/tmp/foo':
    owner    => 'admin',
    mode     => '0644',
    contents => 'this is the content',;

  '/opt/myapp':
    owner  => 'myapp-admin',
    mode   => '0644',
    source => 'puppet://<someurl>',;

  # etc
}

You cannot set any attribute more than once for a given resource; if you try, Puppet raises a compilation error. This means:

• If you use a hash to set attributes for a resource, you cannot set a different, explicit value for any of those attributes. For example, if mode is present in the hash, you can’t also set mode => "0644" in that resource body.
• You can’t use the * attribute multiple times in one resource body, because * itself acts like an attribute.
• To use some attributes from a hash and override others, either use a hash to set per-expression defaults, or use the + (merging) operator to combine attributes from two hashes (with the right-hand hash overriding the left-hand one).

Symbolic links

Declare symbolic links with an ensure value of ensure => link. To inform the user that you are creating a link, specify a value for the target attribute.

Good:

file { '/var/log/syslog':
  ensure => link,
  target => '/var/log/messages',
}

Bad:

file { '/var/log/syslog':
  ensure => '/var/log/messages',
}

File modes

Good:

file { '/var/log/syslog':
  ensure => file,
  mode   => '0644',
}

Bad:

file { '/var/log/syslog':
  ensure => present,
  mode   => 644,
}

Multiple resources

Multiple resources declared in a single block should be used only when there is also a default set of options for the resource type.

file {
  default:
    ensure => 'file',
    mode   => '0666',;

  '/foo':
    user => 'owner',;

  '/bar':
    user => 'staff',;
}

$our_default_file_attributes = { 
  'ensure' => 'file', 
  'mode'   => '0666', 
}
 
file {
  default:
    * => $our_default_file_attributes,;

  '/foo':
    user => 'owner',;

  '/bar':
    user => 'staff',;
}

['/foo', '/bar'].each |$path| {
  file { $path:
    ensure => 'file',
  }
}

$array_of_paths.each |$path| {
  file { $path:
    ensure => 'file',
  }
}

file {
  '/foo':
    ensure => 'file',
    user   => owner,
    mode   => '0666',;

  '/bar':
    ensure => 'file',
    user   => staff,
    mode   => '0774',;
}

file { ['/foo', '/bar']:
  ensure => 'file',
}
 
file { $array_of_paths:
  ensure => 'file',
}

Legacy style defaults

Avoid legacy style defaults. If you do use them, they should occur only at top scope in your site manifest. This is because resource defaults propagate through dynamic scope, which can have unpredictable effects far away from where the default was declared.

Package {
  provider => 'zypper',
}

File {
  owner => 'nobody',
  group => 'nogroup',
  mode  => '0600',
}

concat { $config_file_path:
  notify  => Class['Apache::Service'],
  require => Package['httpd'],
}

Attribute alignment

Resource attributes must be uniformly indented in two spaces from the title.

file { '/foo':
  ensure => 'file',
  owner  => 'root',
}

file { '/foo':
    ensure => 'file',
    owner  => 'root',
}

file { '/foo':
ensure => 'file',
owner  => 'root',
}

file { '/foo':
  ensure => 'file',
   owner => 'root',
}

  file { '/foo':
ensure => 'file',
owner  => 'root',
  }

file {
  default:
    * => $local_defaults,;
 
  '/foo':
    ensure => 'file',
    owner  => 'root',
}

Defined resource types

Since defined resource types can have multiple instances, resource names must have a unique variable to avoid duplicate declarations.

define apache::listen {
  $listen_addr_port = $name

  concat::fragment { "Listen ${listen_addr_port}":
    ensure  => present,
    target  => $::apache::ports_file,
    content => template('apache/listen.erb'),
  }
}

define apache::listen {

  concat::fragment { 'Listen port':
    ensure  => present,
    target  => $::apache::ports_file,
    content => template('apache/listen.erb'),
  }
}

Separate files

Put all classes and resource type definitions (defined types) as separate files in the manifests directory of the module. Each file in the manifest directory should contain nothing other than the class or resource type definition.

class apache { }

class apache::ssl { }

define apache::virtual_host () { }

Separating classes and defined types into separate files is functionally identical to declaring them in init.pp, but has the benefit of highlighting the structure of the module and making the function and structure more legible.

When a resource or include statement is placed outside of a class, node definition, or defined type, it is included in all catalogs. This can have undesired effects and is not always easy to detect.

# class foo
class foo {
  include bar
}
# end of file

class foo {
  #...
}
include bar

Internal organization of classes and defined types

Structure classes and defined types to accomplish one task.

Documentation comments for Puppet Strings should be included for each class or defined type. If used, documentation comments must precede the name of the element. For complete documentation recommendations, see the Modules section.

Put the lines of code in the following order:

The following example follows the recommended style.

---
version: 5
defaults:
  data_hash: yaml_data
 
hierarchy:
- name: 'Per Operating System'
  path: "os/%{os.name}.yaml"
- name: 'Common'
  path: 'common.yaml'

myservice::service_ensure: running

myservice::package_list:
- 'myservice-centos-package'

myservice::package_list:
- 'myservice-solaris-package1'
- 'myservice-solaris-package2'

Public and private

Split your module into public and private classes and defined types where possible. Public classes or defined types should contain the parts of the module meant to be configured or customized by the user, while private classes should contain things you do not expect the user to change via parameters. Separating into public and private classes or defined types helps build reusable and readable code.

You should help indicate to the user which classes are which by making sure all public classes have complete comments and denoting public and private classes in your documentation. Use the documentation tags “@api private” and “@api public” to make this clear. For complete documentation recommendations, see the Modules section.

Chaining arrow syntax

Most of the time, use relationship metaparameters rather than chaining arrows. When you have many interdependent or order-specific items, chaining syntax may be used. A chain operator should appear on the same line as its right-hand operand. Chaining arrows must be used left to right.

Package['httpd'] -> Service['httpd']

Package['httpd']
-> Service['httpd']

Service['httpd'] <- Package['httpd']

Package['httpd'] ->
Service['httpd']

Nested classes or defined types

Don't define classes and defined resource types within other classes or defined types. Declare them as close to node scope as possible. If you have a class or defined type which requires another class or defined type, put graceful failures in place if those required classes or defined types are not declared elsewhere.

class apache {
  class ssl { ... }
}

class apache {
  define config() { ... }
}

Display order of parameters

In parameterized class and defined type declarations, list required parameters before optional parameters (that is, parameters with defaults). Required parameters are parameters that are not set to anything, including undef. For example, parameters such as passwords or IP addresses might not have reasonable default values.

Note that treating a parameter like a namevar and defaulting it to $title or $name does not make it a required parameter. It should still be listed following the order recommended here.

class dhcp (
  $dnsdomain,
  $nameservers,
  $default_lease_time = 3600,
  $max_lease_time     = 86400,
) {}

class ntp (
  $options   = "iburst",
  $servers,
  $multicast = false,
) {}

Parameter defaults

Adding default values to the parameters in classes and defined types makes your module easier to use. As of Puppet 4.9.0, use Hiera data in the module and rely on automatic parameter lookup for class parameters. See the documentation about automatic parameter lookup for detailed information.

For versions earlier than Puppet 4.9.0, use the “params.pp” pattern. In simple cases, you can also specify the default values directly in the class or defined type.

Take care to declare the data type of parameters, as this provides automatic type assertions.

class my_module (
  String $source,
  String $config,
) {
  # body of class
}

---
version: 5
default_hierarchy: 
- name: 'defaults'
  path: 'defaults.yaml'
  data_hash: yaml_data

my_module::source: 'default source value'
my_module::config: 'default config value'

This places the values in the defaults hierarchy, which means that the defaults are not merged into overriding values. If you want to merge the defaults into those values, change the default_hierarchy to hierarchy.

class my_module ( 
  String $source = $my_module::params::source,
  String $config = $my_module::params::config,
) inherits my_module::params {
  # body of class
}

Exported resources

Exported resources should be opt-in rather than opt-out. Your module should not be written to use exported resources to function by default unless it is expressly required.

When using exported resources, you should name the property collect_exported.

Exported resources should be exported and collected selectively using a search expression, ideally allowing user-defined tags as parameters so tags can be used to selectively collect by environment or custom fact.

define haproxy::frontend (
  $ports            = undef,
  $ipaddress        = [$::ipaddress],
  $bind             = undef,
  $mode             = undef,
  $collect_exported = false,
  $options          = {
    'option' => [
      'tcplog',
    ],
  },
) {
  # body of define
}

Parameter indentation and alignment

Parameters to classes or defined types must be uniformly indented in two spaces from the title. The equals sign should be aligned.

class profile::myclass (
  $var1    = 'default',
  $var2    = 'something else',
  $another = 'another default value',
) {

}

class profile::myclass (
      $var1    = 'default',
      $var2    = 'something else',
      $another = 'another default value',
) {

}

class profile::myclass (
$var1    = 'default',
$var2    = 'something else',
$another = 'another default value',
) {

}

class profile::myclass (
  $var1 = 'default',
  $var2  = 'something else',
  $another = 'another default value',
) {

}

Class inheritance

In addition to scope and organization, there are some additional guidelines for handling classes in your module.

Don't use class inheritance; use data binding instead of params.pp pattern. Inheritance is used only for params.pp, which is not recommended in Puppet 4.

If you use inheritance for maintaining older modules, do not use it across module namespaces. To satisfy cross-module dependencies in a more portable way, include statements or relationship declarations. Only use class inheritance for myclass::params parameter defaults. Accomplish other use cases by adding parameters or conditional logic.

class ssh { ... }

class ssh::client inherits ssh { ... }

class ssh::server inherits ssh { ... }

class ssh inherits server { ... }

class ssh::client inherits workstation { ... }

class wordpress inherits apache { ... }

Public modules

When declaring classes in publicly available modules, use include, contain, or require rather than class resource declaration. This avoids duplicate class declarations and vendor lock-in.

Referencing facts

When referencing facts, prefer the $facts hash to plain top-scope variables (such as $::operatingsystem).

Although plain top-scope variables are easier to write, the $facts hash is clearer, easier to read, and distinguishes facts from other top-scope variables.

Namespacing variables

When referencing top-scope variables other than facts, explicitly specify absolute namespaces for clarity and improved readability. This includes top-scope variables set by the node classifier and in the main manifest.

These special variable names are protected; because you cannot create local variables with these names, they always refer to top-scope variables.

$facts['operatingsystem']

$::operatingsystem

$operatingsystem

Variable format

When defining variables you must only use numbers, lowercase letters, and underscores. Do not use uppercased letters within a word, such as “CamelCase”, as it introduces inconsistency in style. You must not use dashes, as they are not syntactically valid.

$foo_bar
$some_long_variable
$foo_bar123

$fooBar
$someLongVariable
$foo-bar123

Simple resource declarations

Avoid mixing conditionals with resource declarations. When you use conditionals for data assignment, separate conditional code from the resource declarations.

Good:

$file_mode = $facts['operatingsystem'] ? {
  'debian' => '0007',
  'redhat' => '0776',
   default => '0700',
}

file { '/tmp/readme.txt':
  ensure  => file,
  content => "Hello World\n",
  mode    => $file_mode,
}

Bad:

file { '/tmp/readme.txt':
  ensure  => file,
  content => "Hello World\n",
  mode    => $facts['operatingsystem'] ? {
    'debian' => '0777',
    'redhat' => '0776',
    default  => '0700',
  }
}

Defaults for case statements and selectors

Case statements must have default cases. If you want the default case to be "do nothing," you must include it as an explicit default: {} for clarity's sake.

Case and selector values must be enclosed in quotation marks.

Selectors should omit default selections only if you explicitly want catalog compilation to fail when no value matches.

Good:

case $facts['operatingsystem'] {
  'centos': {
    $version = '1.2.3'
  }
  'solaris': {
    $version = '3.2.1'
  }
  default: {
    fail("Module ${module_name} is not supported on ${::operatingsystem}")
  }
}

When setting the default case, keep in mind that the default case should cause the catalog compilation to fail if the resulting behavior cannot be predicted on the platforms the module was built to be used on.

Versioning

Your module must be versioned, and have metadata defined in the metadata.json file.

We recommend semantic versioning.

Module metadata

Every module must have metadata defined in the metadata.json file.

{
  "name": "examplecorp-mymodule",
  "version": "0.1.0",
  "author": "Pat",
  "license": "Apache-2.0",
  "summary": "A module for a thing",
  "source": "https://github.com/examplecorp/examplecorp-mymodule",
  "project_page": "https://github.com/examplecorp/examplecorp-mymodule",
  "issues_url": "https://github.com/examplecorp/examplecorp-mymodules/issues",
  "tags": ["things", "stuff"],
  "operatingsystem_support": [
    {
      "operatingsystem":"RedHat",
      "operatingsystemrelease": [
        "5.0",
        "6.0"
      ]
    },
    {
      "operatingsystem": "Ubuntu",
      "operatingsystemrelease": [ 
        "12.04",
        "10.04"
     ]
    }
  ],
  "dependencies": [
    { "name": "puppetlabs/stdlib", "version_requirement": ">= 3.2.0 <5.0.0" },
    { "name": "puppetlabs/firewall", "version_requirement": ">= 0.4.0 <5.0.0" },
  ]
}

Dependencies

Hard dependencies must be declared explicitly in your module’s metadata.json file.

Soft dependencies should be called out in the README.md, and must not be enforced as a hard requirement in your metadata.json. A soft dependency is a dependency that is only required in a specific set of use cases. For an example, see the rabbitmq module.

Your hard dependency declarations should not be unbounded.

README

Your module should have a README in .md (or .markdown) format. READMEs help users of your module get the full benefit of your work.

The Puppet README template offers a basic format you can use. If you create modules with Puppet Development Kit or the puppet module generate command, the generated README includes the template. Using the .md/.markdown format allows your README to be parsed and displayed by Puppet Strings, GitHub, and the Puppet Forge.

There’s a thorough, detailed guide to writing a great README, but in general your README should:

Documenting Puppet code

Use Puppet Strings code comments to document your Puppet classes, defined types, functions, and resource types and providers. Strings processes the README and comments from your code into HTML or JSON format documentation. This allows you and your users to generate detailed documentation for your module.

# @param config_epp Specifies a file to act as a EPP template for the config file.
#  Valid options: a path (absolute, or relative to the module path). Example value: 
#  'ntp/ntp.conf.epp'. A validation error is thrown if you supply both this param **and**
#  the `config_template` param.

If you use Strings to document your module, include information about Strings in the Reference section of your README so that your users will know how to generate the documentation. See Puppet Strings documentation for details on usage, installation, and correctly writing documentation comments.

If you do not include Strings code comments, you should include a Reference section in your README with a complete list of all classes, types, providers, defined types, and parameters that the user can configure. Include a brief description, the valid options, and the default values (if any).

Data type: String.

Whether to install the NTP package, and what version to install. Values: 'present', 'latest', or a specific version number.

Default value: 'present'.

CHANGELOG

Examples

modulepath/apache/examples/{usecase}.pp

Testing