homeblogpuppet forge search by module compatibility

Puppet Forge Search by Module Compatibility

On the Puppet Forge, it hasn't always been easy to find a module designed for your version of Puppet or Puppet Enterprise and the operating system you want to work with. As of today, search filters are available to eliminate this problem. Now you can filter any search both by operating system and by your version of Puppet or Puppet Enterprise.

Compatibility information is displayed on every module page, like this:

Compatibility info for puppetlabs-ntp module

Last last year, I wrote to the Puppet-Developers mailing list about upcoming improvements to module metadata. Basically, we're expanding what the authoritative metadata format (metadata.json) can express. In one of the next major releases of Puppet, it'll be much easier to express this information in a single, authoritative format.

If you'd like to express module compatibility today and are willing to take a few additional steps to do so, we made improvements in Puppet 3.3.0 to make that possible. Compatibility information cannot be expressed in the Modulefile, but puppet module build will combine Modulefile with the new compatibility keys you can express in metadata.json, resulting in a module release that you can publish to the Puppet Forge.

To have your module included in search filters, and have compatibility information displayed on your module's page, you'll need to provide the raw information in the module's metadata. Compatibility information is supplied in the module's metadata.json with two new keys, operatingsystem_support and requirements. A complete example looks like this.

At a high level, these are the steps to add compatibility information for your module:

  1. Use puppet module build to generate a functional metadata.json file from your existing Modulefile.

  2. Copy metadata.json from the pkg folder into the root of your module (alongside Modulefile) to hand-add compatibility information.

  3. Edit metadata.json in the module root to add the new operatingsystem_support and requirements keys as described.

  4. Run puppet module build again to generate the final release tarball from a combination of your existing Modulefile and the new keys added to metadata.json.

  5. Publish to the Puppet Forge and try out the new search filters.

Let's demonstrate these steps by mocking a new release of puppetlabs-ntp.

The first step is to run puppet module build in the root of your module with a valid Modulefilepuppetlabs-ntp has a complete example. Running puppet module build will produce a valid metadata.json file in the pkg/username-module-version/ folder.

For the second step, copy that pkg/username-module-version/metadata.json file into the root of your module folder, alongside Modulefile. You'll add compatibility information to this file, which will be merged back into your tarball in a later step.

Step 3 is the biggest; it involves editing the metadata.json file you've copied alongside Modulefile to express your modules compatibility. This involves optionally adding two new keys, operatingsystem_support and requirements. Here's some documentation on those keys:

###Expressing Puppet & Puppet Enterprise Version Compatibility


Requirements is a list of external requirements for the module in the following format:

While any requirement can be expressed, we expose only "puppet" and “pe” requirements for Puppet version and Puppet Enterprise version, respectively through the Forge, on module pages and search filters.

Because Puppet before 3.0 does not follow semver, it is not recommended to express requirements on it.

We plan to support "mco", “facter” and “hiera” requirements in the future.

###Expressing Operating System Compatibility


This key is for expressing the operating systems (and optionally their versions) that your module supports. The OS will be used with Forge search filters, but the version data will just be treated as strings on module pages.

Here's a complete example that specifies versions in addition to operating systems.

Simply expressing the operating systems you support is perfectly valid.

We expect you to provide the values of Facter facts operatingsystem and operatingsystemrelease.

The puppetlabs-ntp module has a full example on GitHub using both of the new metadata keys.

Step 4: Once you're satisfied with your additions, the final step is to run puppet module build one more time in the root of your module. This time, Puppet will build your module tarball in the pkg/ directory with information from your Modulefile, plus the new keys you provided in metadata.json. You could commit the metadata.json to your version control repository for convenience, but it isn't needed beyond this step.

You're now ready to publish the tarball to the Puppet Forge. The compatibility information added to the module will be immediately available for use in search filters and will be displayed on each module page.

Two community members have already added compatibility information to their modules, and I'm excited to watch the community update the rest. Thanks to opentable/homes, golja/ioncubeloader — and thanks to all of you who use the Puppet Forge.

Ryan Coleman is the product owner for the Puppet Forge.

##Learn More