I've posted this to Puppet-Users to better ensure those publishing to the Puppet Forge see it. If you want to reply, please reply to Puppet-Dev.
With the launch of Puppet Enterprise 3.2 this week, the Puppet Forge added search filters to help people find modules that are compatible with their Puppet versions and managed operating systems. If you've published a module to the Puppet Forge, here's how you can add compatibility information to your module metadata for use within the search filters and module pages. As the steps to do this are decreased, we'll add supporting documentation to docs.puppetlabs.com. This process is considered interim. Last last year, I wrote to the Puppet-Developers mailing list [1] 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 it 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: https://github.com/puppetlabs/puppetlabs-ntp/blob/3.0.3/metadata.json#L2 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 I'll demonstrate the complete steps below to express compatibility in your module 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 Modulefile [2]. puppetlabs/ntp has a complete example [3]. Running `puppet module build` will produce a valid metadata.json file in the pkg/username-module-version/ folder. Second, 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. The biggest step (3 above) 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. The formatting took a hit moving to plain text. requirements Requirements is a list of external requirements of the module of the form: "requirements": [ {"name": "pe", "version_requirement": "3.x"}] "name" is the name of the requirement. "version_requirement" can be a semver version range similar to dependencies. While any requirement can be expressed, we only expose "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. operatingsystem_support 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. "operatingsystem_support": [ { "operatingsystem":"RedHat", "operatingsystemrelease":[ "5.0", "6.0" ] }, { "operatingsystem": "Ubuntu", "operatingsystemrelease": [ "12.04", "10.04" ] } ] Simply expressing the operating systems you support is perfectly valid. "operatingsystem_support": [ { "operatingsystem": "RedHat", }, { "operatingsystem": "Ubuntu", }, { "operatingsystem": "Debian", } { "operatingsystem": "CentOS", }, ] We expect you to provide the values of Facter facts operatingsystem and operatingsystemrelease. The puppetlabs/ntp module has a full example on GitHub [4] using both of the new metadata keys. Once you're satisfied with your additions, the final step (4 above) 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. [1] https://groups.google.com/forum/#!topic/puppet-dev/6PxwrXtuPGo/discussion [2] http://docs.puppetlabs.com/puppet/latest/reference/modules_publishing.html#write-a-modulefile [3] https://github.com/puppetlabs/puppetlabs-ntp/blob/3.0.3/Modulefile [4] https://github.com/puppetlabs/puppetlabs-ntp/blob/3.0.3/metadata.json If you have any trouble with these steps, feel free to email me or find me as ryanycoleman in #puppet or #puppet-dev on Freenode IRC. We fully intend to eliminate the extra steps in a future version of Puppet and we're looking into alternatives to direct editing of JSON for those who prefer not to. Thanks for taking the time to read this and add compatibility expressions to your Forge module. --Ryan -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-users/CAFkZv1uSCYZXQj6JjxZqR_cN4QKDgVniv%2BdGuySt51Naj7%3DS7w%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
