Ryan Coleman
2014-Mar-06 21:56 UTC
[Puppet Users] Search filters have been added to the Puppet Forge. Here's how to add compatibility expressions to your module.
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+unsubscribe@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.