Plug-ins in Modules

This version of Puppet is not included in Puppet Enterprise. The latest version of PE includes Puppet 4.10.

Puppet supports several kinds of plug-ins, which can be distributed in modules. These plug-ins enable new features for managing your nodes. Plug-ins are often included in modules downloaded from the Puppet Forge, and you can also develop your own.

Installing plug-ins

Plug-ins are automatically enabled when you install the module that contains them. You don’t have to do anything else: once a module is installed in an environment’s modulepath, its plug-ins are available when managing nodes in that environment.

Auto-download of agent-side plug-ins (pluginsync)

Some plug-ins are used by Puppet Server, which can load them directly from modules. But other plug-ins (facts, custom resource types and providers) are used by Puppet agent, which doesn’t have direct access to the server’s modules.

To enable this, Puppet agent automatically downloads plug-ins from the server at the start of each agent run. Those plug-ins are then available during the run.

Puppet agent syncs plug-in files from every module in its environment’s modulepath, regardless of whether that node uses any classes from a given module. In other words, even if you don’t declare any classes from the stdlib module, nodes will still use stdlib’s custom facts.

Technical details of pluginsync

Pluginsync takes advantage of the same file serving features used by the file resource type.

Puppet Server creates two special file server mount points for pluginsync, and populates them with the aggregate contents of certain subdirectories of modules. Before doing an agent run, Puppet agent recursively manages the contents of those mount points into two cache directories on disk. The agent performs the following functions:

  1. Sends a GET request to /puppet/v3/file_metadatas/<MOUNT POINT>,
  2. Compares the resulting checksums and ownership info to local files
  3. Deletes any unmanaged files,
  4. Retrieves content data for any missing or out-of-date files, and
  5. Sets permissions as needed.

The following table shows the corresponding module subdirectories, mount points, and agent-side directories for each kind of plug-in:

Plug-in type Module subdirectory Mount point Agent directory
External facts <MODULE>/facts.d pluginfacts <VARDIR>/facts.d
Ruby plug-ins <MODULE>/lib plugins <VARDIR>/lib

(<VARDIR> is Puppet agent’s cache directory, which is located at /var/opt/puppetlabs/puppet/cache, %PROGRAMDATA%\PuppetLabs\puppet\cache, or ~/.puppetlabs/opt/puppet/cache.)

Types of plug-ins

Puppet supports several kinds of plug-ins:

Facts and Augeas lenses are used solely by Puppet agent. Functions are used solely by Puppet Server. Resource types and providers are used by both. (Note that Puppet apply acts as both agent and server.)

Adding plug-ins to a module

To add plug-ins to a module, put them in the following directories:

Type of plug-in Module subdirectory
Facts lib/facter
Functions (Ruby, modern Puppet::Functions API) lib/puppet/functions
Functions (Ruby, legacy Puppet::Parser::Functions API) lib/puppet/parser/functions
Functions (Puppet language) functions
Resource types lib/puppet/type
Resource providers lib/puppet/provider
External facts facts.d
Augeas lenses lib/augeas/lenses

In all cases, you must name files and additional subdirectories according to the plug-in type’s loading requirements.

To illustrate, a module that included every type of plug-in would have a directory structure like this:

  • mymodule (the module’s top-level directory; this module is named mymodule.)
    • lib
      • facter
        • my_custom_fact.rb
      • puppet
        • functions
          • modern_function.rb
        • parser
          • functions
            • classic_function.rb
        • type
          • mymodule_instance.rb
        • provider
          • exec
            • powershell.rb
      • augeas
        • lenses
          • custom.lns
    • functions
      • convertdata.pp (contains a function named mymodule::convertdata.)
    • facts.d
      • datacenter.py (an executable script that returns fact data.)

Issues with server-side plug-ins

If you encounter problems with conflicting versions of the same plug-in in different environments, you can fix these issues as described below.

Environments aren’t completely isolated for certain kinds of plug-ins. If a plug-in of the same name exists in different versions in multiple environments, Puppet loads the plug-in from the first environment to use that plug-in, then continues to use that version of the plug-in for all subsequent environments.

This issue can occur with the following plug-in types:

  • Custom resource types. To avoid resource type conflicts, use the puppet generate types command as described in environment isolation documentation.
  • Custom functions, only with the legacy Puppet::Parser::Functions API. To fix the issue, rewrite functions with the modern API, which is not affected by this issue.

↑ Back to top