Integrating PDK

PDK has now well and truly arrived on the Puppet landscape. With Puppet 6, its mandatory in order to build Puppet modules (unless you stay on an older version of Puppet of course…).

That means third party tools like PDQTest need to integrate PDK somehow or be stuck forever on older versions of Puppet.

According to @rodjek from Puppet, PDQTest is the first third party testing framework to integrate PDK. We think that’s pretty cool!

In this article, we explore how PDK was integrated into PDQTest. If you maintain your own testing tool, this is sure to save you some effort.


  • Full compatibility with PDK - don’t force users to chose between test frameworks
  • Robust, repeatable tests for both workstations and CI on Linux and Windows

What does using PDK do a puppet module?

Enabling PDK touches several parts of your module, notably:

  • It takes over ownership of some files (Gemfile, Rakefile, etc)
  • It edits metadata.json to declare PDK compatibility

With these integration points in place, your up and running with PDK.

Users are encouraged to run pdk update as new version of PDK are released and this will rewrite the files that PDK originally placed.

Files are re-written based on templates and these templates can be either altered by feeding them parameters through the .sync.yml file or or the templates can be completely replaced by maintaining your own repository of PDK templates.

Because PDK owns these files, the simplest thing to do is let PDK have them and don’t try to do things like add your own gems to the Gemfile or your own tasks to the Rakefile, unless you want to put together an override in .sync.yml.

How did we end up integrating PDK

PDK alters the Gemfile.lock when different PDK commands are run. The simplest workaround for this turned out to be a separate Gemfile which we keep in the .pdqtest directory. Since our users run PDQTest via the make command, all of the directory jumping was kept in the Makefile (make.ps1 for our Windows users).

To run PDK commands, you have to shell out and make system calls to pdk. This is simple on Linux but requires a little finesse on Windows since pdk is actually a PowerShell construct on this platform.

To avoid the need to maintain our own template repository or vendor ones from PDK, we use PDK itself to create a new module and copy out the files we want if users update a PDQTest 1.x module using pdqtest init.

What other approaches were tried?

  • Adding PDQTest to the main Gemfile - gets clobbered by pdk update
  • Adding PDQTest to the special file Gemfile.local - kinda worked but failed in CI due to PDK rebundling while running, also ran into PDK-1177 which needed further workarounds
  • Use pdk bundle exec to obtain access to the pdk command from a ruby executable that was itself started with pdk bundle exec - crashed

Where to get help?

The first place to go for help is the #testing channel on Puppet Community Slack - don’t suffer in silence, the Puppet team are always keen to help.

How exactly does PDQTest integrate PDK?

Checkout the PDK Integration docs and if you want to go even deeper, the source code.

How can Puppet make PDK integration easier?

A public Ruby API and a way to side-load our own rubygems would be a welcome addition.

The idea of having to maintain templates as well as puppet modules is not a compelling value proposition from Declarative System’s “delete your code” standpoint and rewriting ruby scripts based on data in .yml files feels a little clunky. Perhaps a “well known file to override from” would be an approach worth investigating.

More docs and blogs that address the integration story… Like this one!

Post comment