puppet describe

The puppet describe command provides documentation for resources. describe is intended to be used as a command-line tool. puppet describe --list will list all installed resource types. puppet describe type will show documentation for a resource type that you specify.

puppet describe shows the inline documentation for both built-in and custom resource types currently installed. It can be invaluable when you have a lot of custom types and providers. It’s also useful at sites running older releases of Puppet for which the latest online documentation might not be correct for the installed release.

puppet-strings

The puppet-strings gem provides automatic creation of formatted documentation from modules. You run the puppet strings command in a module directory to generate HTML documentation in doc/ from the structured comments in your manifests, functions, types, and providers. You can find complete documentation at https://puppet.com/docs/puppet/latest/puppet_strings.html.

sudo puppet resource package puppet-strings ensure=present 
provider=puppet_gem

Of particular use, puppet-strings can autogenerate the module’s REFERENCE.md in Markdown format. It will even inform you when the inline documentation doesn’t match the code, as shown here:

$ puppet strings generate --format markdown
[warn]: Missing @param tag for 'service_name' near manifests/agent.pp:43.
[warn]: The type of the @param tag for 'value' does not match the
  parameter type specification near manifests/inisetting.pp:42

puppet resource

The puppet resource command allows you to interact with the Puppet resource abstraction layer from a command-line shell. It has two purposes:

• To query the current state of resources on the node

• To declare a puppet resource directly from the command line

This can be extremely useful as a learning tool, both for folks who aren’t very familiar with resource syntax and for the investigation and exploration of a complex resource type.

$ puppet resource host localhost
host { 'localhost':
  ensure => 'present',
  ip     => '127.0.0.1',
  target => '/etc/hosts',
}

$ puppet resource host nothere
host { 'nothere':
  ensure => 'absent',
}

$ puppet resource file /etc/hosts
file { '/etc/hosts':
  ensure  => 'file',
  content => '{md5}a3f51a033f988bc3c16d343ac53bb25f',
  ctime   => '2018-01-18 20:56:03 -0800',
  group   => '0',
  mode    => '0644',
  mtime   => '2017-06-29 20:42:42 -0700',
  owner   => '0',
  type    => 'file',
}

C:Program Files (x86)Puppet LabsPuppetbin> puppet resource package
package { '7-Zip 9.38 (x64 edition)':
  ensure => '9.38.00.0',
}
package { 'OpenSSH for Windows 6.7p1-2 (remove only)':
  ensure => 'installed',
}
package { 'Oracle VM VirtualBox Guest Additions 4.3.18':
  ensure => '4.3.18.0',
}

$ puppet resource file
Error: Could not run: Listing all file instances is not supported.
    Please specify a file or directory, e.g. puppet resource file /etc

$ sudo puppet resource package puppet-strings provider=puppet_gem ensure=present
Notice: /Package[puppet-strings]/ensure: created
package { 'puppet-strings':
  ensure => ['2.1.0'],
}

puppet apply

If you’re interested in performing more involved experiments, consider using puppet apply --execute with small snippets, as shown in the code example that follows. As this runs Puppet through the catalog building and application process, it’s the best way to test out short snippets of puppet code.

$ puppet apply --execute "file { '/tmp/testfile': ensure => present }"
Notice: Compiled catalog in environment production in 0.12 seconds
Notice: /Stage[main]/Main/File[/tmp/testfile]/ensure: created
Notice: Applied catalog in 0.03 seconds

Using puppet apply in this manner is useful when you need to experiment with more complex resource types that tend to require a lot of trial and error. This allows experimentation without committing or pushing code until you’re certain of the syntax.

You can use puppet apply with small manifest files for slightly longer examples:

$ puppet resource user jorhett > test.pp
$ puppet apply test.pp
Notice: Compiled catalog in environment production in 0.12 seconds
Notice: Applied catalog in 0.03 seconds

Because the manifest exactly matches the current state, nothing has changed. But you can now edit this manifest to try out changes. This allows you to test resource defaults, overrides, resource relationships, and any other features that are not available when experimenting with the resource command line.

Static declaration

It is very easy to read a static declaration because all values are filled in, as shown here:

host { 'localhost':
  host_aliases => ['localhost.localdomain'],
  ip           => '127.0.0.1',
}

It is, however, rare that the Puppet developer will know the absolute values for a resource. This is more often a hint that you have data in the code, which should be avoided unless that data is absolutely, positively internal to the module and will never change.

Interpolation

The best way to write reusable code is to accept data input that instructs the code how to operate. For example, the package name, the configuration file location, and the user Apache runs under changes on different Linux platforms. You can keep the declaration clean and easy to read by using variables in the resource declaration. You can use variables in the resource title and any properties or parameters. These variables will be interpolated into values when the resource is added to the catalog, as illustrated here:

file { $apache_config:
  ensure  => $apache_file_ensure,
  owner   => $apache_user,
  group   => $apache_group,
  mode    => $apache_file_mode,
  content => template('apache/apache.conf.erb'),
}

This allows the platform-specific values to be acquired from the module Hiera data, which contains values appropriate for each supported platform. In addition, this allows the environment layer of Hiera to override the module data with a site-specific value, without changing a single line of code.

Avoid complex structures in resource declarations

You should avoid embedding conditional logic such as selectors in your resource statements because doing so tends to produce difficult-to-read code. Assign the result to a variable and then use the variable as the attribute value, as discussed in the documentation. Here’s what the code looks like:

# Long/wrapped lines
$motd = @("END")
Welcome to ${::fqdn}

This host is managed by Puppet.
Unauthorized access is strictly prohbited.
END

file { '/etc/motd':
  content => $motd,
}

This example uses Heredoc syntax (available since Puppet 4) for a multiparagraph string (unfortunately also demonstrating the data in code antipattern).

The create_resources() function

create_resources() is by far the most popular resource declaration function call. It declares resources from serialized data structures. The following example shows user resources serialized in a YAML hash:

example::users:
  'alice':
    ensure: 'present'
    comment: 'Alice'
    group: 'example_users'
    managehome: true,
  'jack':
    ensure: 'absent'
    comment: 'Jack'

The example that follows iterates over this hash of users and declares a new user resource from each entry:

# Get serialized user resources from Hiera
$hash_of_users = lookup('example::users', Hash, 'deep', {})

# Set default values
$user_defaults = {
  shell => '/bin/bash',
}

# Declare user resources with values from the hash
create_resources('user', $hash_of_users, $user_defaults)

For each entry in the hash, create_resources declares a user resource with the hash key as the title. The attributes for the resource will be taken from the hash of values behind the key, combined with any missing attribute values from the $user_defaults hash. For example, the first entry in the hash shown will be declared as a resource like this:

user { 'alice':
  ensure     => 'present',
  comment    => 'Alice',
  gid        => 'examplegroup',
  managehome => true,
  shell      => '/bin/bash',
}

The creation of resources from serialized data enables the separation of code from long lists of data. It enables us to create resources from lists supplied by other parts of our infrastructure, reducing duplication.

Whether this is best practice can be very situational. Here are some guidelines to help you discern:

Data in code?

A list of authorized users in Hiera data helps avoid putting changeable data values (the users to declare) in the code.

Code in data?

The code should never depend on essential parts of the code coming from data. The code should always operate with or without valid external data.

The ensure_ functions

ensure_packages() and ensure_resource() are function calls that you can use to add resources to the catalog. Both function calls are included in the puppetlabs/stdlib module and are not available in a base Puppet install.

Unlike create_resources(), these function calls check whether a resource already exists before inserting the resource into the catalog. This would seem to be a good solution to the duplicate resource declaration problem, but you should use it with extreme caution because it’s parse-order dependent. The following statement will compile and run fine:

file { '/tmp/example.txt':
  ensure => 'file',
}

ensure_resource('file', '/tmp/example.txt', { 'ensure' => 'file'})

This statement, however, will throw an error:

ensure_resource('file', '/tmp/example.txt', { 'ensure' => 'file'})

file { '/tmp/example.txt':
  ensure => 'file',
}

This parse-order dependence can create a huge problem; code that works in one situation can unexpectedly fail in another. A small change in the code can cause resource ordering to change, instantly creating problems not previously visible. As a result of the parse-order problem, you can safely use the ensure_resources() functions only where every instance is declaring that resource with the ensure_resource function.

The same problems are visible with resource declarations inside defined_with_params() and defined() conditional statements.

alias

The alias metaparameter allows you to specify alternative titles for a resource to provide a friendly name for a resource with a long and complex title, as shown here:

file { '/etc/httpd/conf/httpd.conf':
  ensure  => 'file',
  content => template('apache/apache.conf.erb')
  alias   => 'apache_config',
}

You cannot use aliases everywhere that resource titles can be. For example, you cannot use them as identifiers for resource chaining. The safer approach is to use a friendly name in the resource title and specify the longer namevar attribute explicitly, as demonstrated in the following:

file { 'apache_config':
  ensure  => 'file',
  content => template('apache/apache.conf.erb')
  path    => '/etc/httpd/conf/httpd.conf',
}

audit

The audit metaparameter accepts a list of attributes whose state should be tracked by Puppet. This has two purposes:

• It allows Puppet to report changes on resources that aren’t managed by Puppet.
• It allows Puppet to generate notification signals when resources have changes outside of Puppet.

Audit works by recording the current state of the resource to an audit log. If the resource changes state after Puppet’s evaluation of the resource, the differences from the current state of the resource will be reported. If a notify or subscribe relationship exists with another resource, a notification will be sent.

It’s safe for some attributes of a resource to be managed while others are audited. Be aware that audited attribute notifications are indistinguishable from managed attribute change notifications.

You can use auditing to create triggers for resources changed by something outside of Puppet, such as when a file is replaced as shown in the following code:

file { '/uploads/myapp.tar.gz':
  audit  => 'contents',
  notify => Exec['extract_myapp']
}

exec { 'extract_myapp':
  command     => "/bin/tar -zxf ${myapp_tarball} -C /opt",
  refreshonly => true,
}

Ordering metaparameters: before and require

before and require allow you to specify dependencies and ordering between resources. They ensure that resources are processed in the correct order and that resources are not processed if their dependencies failed to be applied.

before and require perform the same basic function in opposite directions. Use whichever metaparameter will result in the most maintainable code.

Notification metaparameters: notify and subscribe

Notifications allow a resource to signal other resources that it has changed during a catalog application. The dependent resource receives a refresh event that it can act upon, if relevant for that resource type. notify and subscribe implement the same functionality as before and require with the addition of sending the refresh event from a resource to its dependency.

Like their counterparts, notify and subscribe implement the same basic function in opposite directions. Use whichever metaparameter will result in the most maintainable code. The code example that follows shows each:

file { '/tmp/foo':
  notify => Service['biff'],
}

file { '/tmp/bar':
  notify => Service['biff'],
}

service { 'biff':
  # redundant with the notify metaparameters
  subscribe => File['/tmp/foo','/tmp/bar'],
}

In this example, when either declares file changes, the biff service will receive a refresh event, causing the service to be restarted before the same catalog application is completed.

Avoid tight relationships whenever possible

Relationships are best implemented observing the philosophy of low coupling and high cohension:

• Use relationships between resources only within a class (high cohesion).

• Use relationships between child classes within a module.

• Use relationships with the main class of unrelated modules (low coupling).

Beyond these simple rules, we can improve module reliability by doubling down on the philosophy:

High cohension

Use resource relationships within a class even when manifest ordering is used. Manifest ordering is an unstated, implicit structure that is often broken by accident. Make a habit of testing classes with random ordering to help identify cases where a necessary relationship is missing.

Low coupling

Resource relationships that cross class boundaries violate the principles of modular and interface-driven design. By creating relationships only with the main class, you can refactor each module without impact or risk to the other.

noop

The noop metaparameter allows you to explicitly enable or disable no-operation mode for a single resource, class, or defined type declaration. In noop mode, the resource will be evaluated and compared to the modeled state,; however, changes to the resource will not be applied. This allows you to report that a resource does not conform to your policy without changing the resource’s state.

Setting this to false could cause resource states to change when the user wants to evaluate potential changes. Setting noop => false on a resource declaration might seem useful for partial enforcement of catalogs (e.g., security-related resources), but it removes one of Puppet’s greatest strengths: the ability to safely simulate changes by running with --noop enabled. You run puppet apply --noop to review the changes, but the resource’s hardcoded value wins over the command-line value, and a change to the resource is applied.

The converse problem exists for hardcoding noop => true in the code, which will cause an attempt to cause a change with --no-noop to be ineffective.

Because you cannot override this metaparameter on the command line or in the configuration, it is useless in general practice. Instead, use tagged runs for partial enforcement, as discussed in “tag”. This allows you to use the --noop command-line option or noop = true configuration value to prevent changes in a way that can be overridden when necessary.

Note that although Puppet will log the notifications and refresh events that would be created, it will not actually send those signals if noop is enabled. If you want to generate signals without enforcing state, consider using the audit metaparameter instead.

schedule

The schedule metaparameter allows you to assign a resource to be evaluated within a specific window, as defined by the schedule resource type. This attribute can be very useful for ensuring that a resource is applied only within a certain window. It can also limit the frequency at which a resource is evaluated. For more information, see Resource Type: schedule.

One surprising feature of schedule is that a resource evaluated outside of its schedule always succeeds for dependency purposes. If the resource has not been applied because Puppet has not yet run during the schedule window, the dependent resource won’t have the resource it depends on. For this reason, it is necessary when you’re first building a node or when you’re deploying new features to disable the schedules so that the necessary dependencies are created. Thereafter, they will be updated only during the schedule window.

stage

You can apply stage only to entire classes, and it has a number of complications that make it unsuitable for most purposes.

• You must assign classes to stages using the resource declaration format, which prevents multiple classes from declaring the class and disallows the application of data-driven class assignment from Hiera.

• You cannot send notifications between resources in different stages.

• Class containment behaves strangely if any class resides in another stage.

Early Puppet users attempted to use stage for rough ordering; however, there are so many complications with stages that most sites have abandoned their use entirely. No matter how carefully you segregate resources into different stages, at some point during a minor change you’re going to find that a dependency loop between the stages has been created. Fixing that problem will require a major refactoring, possibly of the entire implementation. There are no simple fixes to ordering resources that cross stage boundaries.

tag

Use tag to identify resources for collection (see “Avoid Parse-Order Problems by Using Virtual Resources” and “Exporting Resources”), to perform partial enforcement of a catalog, and for reporting and review purposes with PuppetDB.

A resource acquires tags from multiple places:

• The tag metaparameter adds the specified values to the list of tags

• Tags automatically created for each resource, including the resource type, and each component of the class or defined type name

• Tags applied to the class containing the resource

• Tags applied to the class that declared the class containing the resource

If you recall the simple resource inspected at the beginning of this chapter, no tags were declared for the resource and yet tags existed on the resource in the catalog as seen in Example 5-3.

  tag 'example_tag'

  file { '/tmp/foo':
    tag => ['foo', 'bar', 'baz'],
  }

In the preceding code, the resource File['/tmp/foo'] would have the tags ["file","foo","bar","baz","example_tag"]. If it was in a module class, it would have the class tag, too.

As you might imagine, it’s easy to match resources you didn’t intend to match due to this behavior. Use distinct tag prefixes to avoid collecting or acting on resources you didn’t intend to.

Dangling relationships to unrealized resources causes breakage

You should also take care when designing resource relationships with virtual resources. If you realize a virtual resource that has a relationship with an unrealized resource, a catalog compilation error will be thrown. You can use the before/require and subscribe/notify symmetry to work around the issue; if the unrealized resource declares the relationship, you’re fine.

Instead, create relationships when realizing the resources with a collector.

Example 5-5 shows the require ordering (the -> chaining arrow) of the yumrepo resource being added as the collector realizes the list of packages.

@package { ['apache2', 'mysql-client']:
  tag => 'Debian',
}

@package { ['httpd', 'mysql']:
  tag => 'RedHat',
}

case $facts['osfamily'] {
  'RedHat': {
     Yumrepo['base'] -> Package <| tag == 'RedHat' |>
  }
  default: {
    Package <| tag == $facts['osfamily'] |>
  }
}

This technique is safe to implement with an empty list because a relationship to an empty collector will not cause an error, as shown here:

package {'filesystem':
  ensure => 'installed',
}

Package['filesystem'] ~> File <| title == 'nonexistent_resource' |>

Resource collectors can realize virtual resources based on any attribute of the resource. The tag metaparameter is commonly employed to realize virtual resources, but you should use it with caution. The compiler automatically assigns a large number of tags to each resource in the catalog based on calling class names, resource types, and many other considerations. If you use nonunique tag names to realize resources, you might find cases in which resources are realized unexpectedly. Tags are applied in a parse-order-dependent way, depending on the first class that declares another class, so the list of automatic tags for a resource is not stable. Use attributes other than tag to realize resources to avoid these issues.

Comparing virtual and exported resources

The similar syntax of virtual and exported resources is due to their very similar nature. In review:

Local resources

Local node @virtual_resource collected by <| search |>

Shared resources

Any node’s @@exported_resource collected by <<| search |>>

Safely using exported resource

An important aspect of exported resources is that they have universal availability. A resource is unlikely to make sense outside the scope of its intended environment. An unexpected resource can cause catalog compilation errors, misconfiguration, or node failure if applied unexpectedly to the wrong environment.

Following are some guidelines for the safe usage of exported resources:

Exported resource titles must be globally unique across all nodes

Because an exported resource could be collected by any node, and a resource title must be unique within a catalog, this requires each exported resource to be absolutely unique. Use a string unique to the node (certname, FQDN, serial, etc.) in the exported resource title to guarantee uniqueness.

A resource can be collected by any node in the infrastructure

As of 2018, there’s not yet any security controls to limit access to exported resources. Only the search parameter of the resource collector will limit the results.

Exported resources are not constrained by their Puppet environment

It’s possible for resources from a development branch to be applied to a production branch. If a Puppet server provides multiple environments that should not collect one another’s resources, tag the resources with the environment and use it in the collector’s search.

Exported resources should not contain resource relationships

It is entirely possible that due to timing, one exported resource would be available and the other not yet processed. This will cause a catalog failure on the collecting node. As demonstrated in “Dangling relationships to unrealized resources causes breakage”, apply the resource relationships when collecting the resources, not when declaring them.

Exported resources could increase the catalog build time and size

If many exported resources are collected, the time to build the catalog and its overall size will both increase. For example, if you have 10,000 nodes exporting their services, the time to build the catalog for a monitoring station collecting those services could be extreme. Use judiciously.

Exported resources provide slow but eventual consistency

If you boot up a thousand new instances, it will take time for each node to run Puppet, build the catalog, and have their exported resources available in PuppetDB to be collected. This works well for eventual consistency, but is not suitable for quickly changing environments in which services might not exist for more than a few minutes.

The number of concerns listed here might concern you. The main benefit of exported resources is that they are tightly integrated and immediately available with Puppet. They solve many problems well, but they are not a solution for every service discovery need. Service registration services like Consul and orchestration services like Kubernetes, DC/OS, and Docker Swarm might be more suitable for highly dynamic services.

Per-expression defaults provide a solution

Thankfully, there’s a better way to provide default attributes that manages to be both safer to use and easier to read. Example 5-6 presents the code.

$my_file_defaults = {
  mode  => '0440',
  owner => 'nobody',
  group => 'nobody',
}

file {
  default:
    * => $my_file_defaults,
    ;;

  '/tmp/foo.txt':
    content => 'Foo',
    ;;
}

include baz

This example works by applying two techniques:

• It uses the splat (*) operator to assign the hash of attribute values.

• By assigning the hash to the per-expression resource default, it allows the resource to explicitly override any defaults.

This stacked resource declaration is a little longer, but it greatly increases readability by explicitly declaring which set of defaults values to use. Nothing happens off the page or through a parse-order-dependent inheritence. And the baz class is completely unaffected by this default, although it could explicitly use the same hash to provide default values if desired.

Per-expression defaults provide a way to avoid surprises

Although it’s a bad idea to use resource default statements, it’s a good idea to be tolerant of them when writing modules. There are two ways to avoid having resource default statements affect the functionality of your module:

• If your resource has specific attribute requirements, set them explicitly instead of relying on defaults you expect.

• Have your class set its own default for the resource. This default will be limited to your class and classes it declares.

• Have your class inherit from an empty class. An explicit inherits statement forces the parent class to one of your own choosing, blocking flow-down inheritence.

In contrast, being tolerant can also mean not fighting valid uses of the module. Let the user specify defaults if the values (such as file owner) aren’t important for what the module does.

The ACL type

The ACL type and provider allow for the management of Windows access control lists (ACLs). This resource type provides much finer control than the file resource permissions. This resource type does not manage file content; you must use it as a supplement to a standard file resource. You use the ACL resource when simple read/write/execute permissions are not sufficiently granular.

This resource type is provided by the puppetlabs/acl module.

The anchor type

The anchor resource was an early fix for the problem of child class containment for class-based relationships. For the most part, it has been superseded by the contain function call. You might occasionally encounter modules that still use this resource type.

Augeas providers

Augeas types are native resource types and providers that use the Augeas configuration editing tool to manage the underlying configuration files. Augeas providers is a set of modules written and managed by the Augeas team. These modules provide a number of new resource types for managing common files, a set of libraries for the creation of new Augeas resource types, and a number of Augeas providers for existing types.

These providers are more focused and user friendly than the built-in augeas resource type. We recommend using these modules rather than attempting to call Augeas directly.

You can deploy all of the providers by installing the herculesteam/augeasproviders module with the puppet module tool, or you can install them individually. You can best manage individual installations by using r10k to handle the long list of modules.

The datacat types

datacat_collector and datacat_fragment serve a function similar to the concat defined type discussed in “The concat defined type”. Instead of sending file fragments to be combined by the agent, datacat creates data structures in the catalog, which can be rendered into a template or utilized by other resources.

You can use this module to build very complex configuration files using templates. datacat works by merging data structures from the various fragment resources. datacat then generates a new resource based on the target_resource parameter given to datacat_collector, and passes the merged data structure to that resource.

Try to avoid crossing module boundaries with datacat. If you need to declare fragments from multiple modules, use a defined type in the module that contains the collector as the external interface for adding fragments.

Combining datacat and concat is where wizards tremble in fear. Generating the datacat fragments and collectors during the catalog build while leaving the concat fragments to be assembled by the agent will create a complex web of interactions to debug.

datacat_fragment and datacat_collector are provided by the richardc/datacat module.

The file_line resource type

You can use the file_line resource type to add or remove lines from arbitrary text files. This resource type is useful when you need to perform edits scoped more narrowly than the entire file but where a native resource is unavailable.

This resource type is provided by the puppetlabs/stdlib module.

The gnupg_key type

This resource type allows for the management and distribution of GNU Privacy Guard (GPG) keys. GPG keys are widely used by installers to validate package integrity. This resource provider can help cryptographically validate yumrepo resources and other package downloads.

This resource type is provided by the golja/gnupg module.

The ini_setting and ini_subsetting resource types

These generic types allow granular management of specific items in INI files. Because the INI format is extremely common, you are almost guaranteed to find use for this resource type.

ini_setting provides per-line management of key/value pairs. Because you can declare the delimiter, spacing, and section(s), it is capable of managing virtually any file comprising simple key/value pairs. ini_setting is often used as a base for other resource providers. For example, it is the base provider for the yumrepo resource type.

ini_subsetting provides element-level management of INI values. The scope of the ini_subsetting type is extremely tight, allowing multiple modules to safely manage elements on a single line.

These resource types can help manage the following:

• /etc/sysconfig/ files containing Bash variables

• Java properties files

• puppet.conf and other puppet configuration settings

• Hashicorp HCL configuration files

These resource types are provided by the puppetlabs/inifile module.

The registry type

The registry type is invaluable for managing registry entries in Windows environments. This resource type is far more efficient and reliable than alternative approaches for editing registry keys.

This resource type is provided by the puppetlabs/registry module.

The reboot type

The reboot type allows Puppet to restart the node it is running on. Its primary purpose is to restart a system so that configuration changes can take effect. On Linux nodes a restart is usually required only to upgrade the kernel or install a kernel extension. Windows nodes might need to restart for routine software installation.

The reboot resource type is inactive unless it receives a notification signal. You can have multiple instances of reboot in your catalog, so long as each one has a unique resource title. It is safe to schedule multiple reboots from one or multiple resources.

If your Puppet runs are idempotent, only a single reboot should be required at the end of your run. The goal is to reach a consistent state during the run, rebooting only for the state to take effect. Ideally, no further changes should be pending when the system comes up. If further changes are needed after the reboot, your code is convergent rather than idempotent. On some platforms, this might be a necessary evil.

If you use reboot in a convergent way, it’s a good idea to schedule a Puppet run at system startup. This can help to avoid a very long convergence cycle, and is useful for cases in which additional postreboot configuration tasks need to be performed. Without an immediate postreboot Puppet run, your overall configuration time can easily exceed an hour. Much of this time will be spent waiting for the next scheduled run.

Note that the reboot type will reboot the system only if it the reboot resource receives a notification signal from another resource. Consider how you contain and isolate the reboot resource in order to prevent an errant signal from inadvertantly triggering a reboot.

The reboot resource type is provided by the puppetlabs/reboot module.

The vcs_repo type

The vcs_repo type allows you to create and manage version control repositories. Its primary use is for cloning repositories to a managed system.

This resource type is useful for the distribution of files and data from repositories other than the ones that host your Puppet code. There are situations for which you might want to have Puppet deploy revision-controlled content but do not want to commit that content to your Puppet repository. Cloning your website to your web servers is one such example.

This approach helps to enforce separation of site content away from your site-logic and site-specific configuration data. It’s also useful for enforcing access control requirements; each repository can have its own access rules.

Although you can use vcs_repo to distribute Puppet manifests, r10k provides significantly more deployment-oriented features. For more details, see Chapter 9.

This resource type is provided by the puppetlabs/vcs_repo module. It’s a good idea to also check the available providers; as of this writing Git, Mercurial, SVN, Bazaar, Perforce, and CVS are supported.

The windows_env native type and provider

The windows_env type allows you to manage Windows environment variables. A surprisingly large number of applications use environment variables to modify pathing or other behaviors. This module is invaluable in Windows environments.

This resource type is provided by the badgerious/windows_env module.

The concat defined type

The concat defined type allows you to build files from fragments, combining multiple file resources into a single complete file. This resource provider is useful when you need to produce files from large multiline chunks. It retains most of the efficiency of the file resource, but it allows multiple classes or instances of a defined type to contribute fragments.

The downside of concat is that it is not always intuitive. Although it’s much simpler to use than datacat, it is not nearly as simple as a conventional file resource. Like a file resource, concat must have complete control over the resulting output file. Ultimately, it’s designed to share inputs, not outputs.

Another consideration is that fragments must be defined in a consistent way for each file. It can be a good idea to wrap the file fragments in defined types to simplify and control their interface.

The concat defined type is provided by the puppetlabs/concat module and is bundled with Puppet Enterprise.

The account defined type

When managing users with Puppet, it is often useful to abstract away the creation of user, group, and other associated resources in order to better organize your data in Hiera, to remove redundent data, and to simplify account creation.

There are several good account modules available, including the pe_account module bundled with Puppet Enterprise. You can use these modules as-is or extended in order to meet your site-specific requirements.

The camptocamp/accounts module is another popular account defined type. It does not conflict with pe_account.