Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 38 ยท Testing and Code Management

PDK and Module Development

Build modules with the Puppet Development Kit: pdk new module, new class and define, pdk validate, pdk test unit, metadata.json, versioning, Puppet Strings and publishing.

You could create a module by making a few folders by hand, and many people did for years. The Puppet Development Kit (PDK) replaces that with one command-line tool that creates the right layout, keeps test and lint configuration up to date, and runs all the checks you met in the previous lessons with a single call. It bundles its own Ruby and Puppet, so you do not need to install a development stack just to work on a module.

This lesson walks through the PDK workflow from an empty directory to a published module. PDK is a command-line tool, so the commands are read-only examples and the runnable blocks are JavaScript stand-ins that explain module metadata and version rules.

Creating a module

Terminal
pdk new module profile_base

PDK asks a few questions (author, license, supported operating systems) and generates the skeleton:

Path Purpose
manifests/ Classes and defined types (init.pp holds the main class)
templates/, files/ EPP templates and static files
lib/ Custom facts, functions, types, providers
data/ and hiera.yaml Module-level default data
spec/ Unit tests
metadata.json Name, version, dependencies, supported OS list
.fixtures.yml, .sync.yml Test fixtures and template settings
Rakefile, Gemfile Task runner and gems

Add code with generator commands. They create both the manifest and a matching starter test:

Terminal
pdk new class profile_base::ntp
pdk new defined_type profile_base::user
pdk new function profile_base::buffer_mb
pdk new fact datacenter
pdk new task cleanup
pdk new transport mydevice

Validate and test

Terminal
pdk validate               # lint, parser validate, YAML, metadata checks
pdk validate --auto-correct
pdk test unit              # run rspec-puppet in the module
pdk test unit --tests=spec/classes/ntp_spec.rb
pdk test unit --parallel

pdk validate runs the checks described in Puppet Lint and Parser Validate plus metadata linting; pdk test unit runs the unit tests from RSpec-puppet. The tool uses the module's pinned dependencies, so the same command gives the same result on a laptop and in CI.

Keep your module current with the PDK template. When PDK releases improved defaults you run:

Terminal
pdk update

and review the generated changes like any other pull request.

metadata.json

The metadata file is the module's identity card. The Forge, puppet module and the dependency resolvers read it:

JSON
{
  "name": "acme-profile_base",
  "version": "1.2.0",
  "author": "Acme Platform Team",
  "summary": "Base configuration shared by all servers",
  "license": "Apache-2.0",
  "source": "https://git.example.com/puppet/profile_base",
  "dependencies": [
    { "name": "puppetlabs/stdlib", "version_requirement": ">= 9.0.0 < 10.0.0" }
  ],
  "operatingsystem_support": [
    { "operatingsystem": "Ubuntu", "operatingsystemrelease": ["22.04", "24.04"] },
    { "operatingsystem": "Rocky", "operatingsystemrelease": ["9"] }
  ],
  "requirements": [
    { "name": "puppet", "version_requirement": ">= 7.0.0 < 9.0.0" }
  ]
}

Two fields drive your tests. operatingsystem_support determines what on_supported_os loops over, and dependencies determines what the Forge installs alongside your module.

Semantic versioning

Use semantic versioning: MAJOR.MINOR.PATCH. Increase MAJOR when you break callers (removing a parameter, renaming a class), MINOR for backward-compatible features, PATCH for fixes. Dependency ranges use the same convention, which is why >= 9.0.0 < 10.0.0 means "any 9.x".

Documenting with Puppet Strings

Documentation comments above classes are parsed by Puppet Strings to build a reference:

PUPPET
# @summary Manages the NTP client
#
# @param servers
#   Time servers, in order of preference.
# @example Use a regional pool
#   class { 'profile_base::ntp': servers => ['0.pool.ntp.org'] }
class profile_base::ntp (
  Array[String] $servers = ['pool.ntp.org'],
) { }
Terminal
pdk bundle exec puppet strings generate --format markdown

The documentation lint check keeps this honest: it complains when a public class has no comment.

Publishing

Terminal
pdk build                  # creates pkg/acme-profile_base-1.2.0.tar.gz
pdk release                # bumps version, builds, and can publish to the Forge

For internal modules you rarely publish at all. You reference the Git repository from the control repo's Puppetfile, see R10k and the Control Repo.

Stand-ins: metadata rules

The first block implements the semver check used when choosing a version bump. The second checks a version against a dependency range like >= 9.0.0 < 10.0.0. Both are JavaScript stand-ins for rules the real tooling applies.

JS Stand-in: choose the next semantic version

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: does a version satisfy a dependency range?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Habits of good module authors

  • One purpose per module; do not pack unrelated classes together.
  • Keep defaults safe and every setting a documented parameter with a type.
  • Support a stated list of operating systems and test every one.
  • Add a CHANGELOG, and bump the version in metadata.json in the same commit as the change.
  • Run pdk validate and pdk test unit in CI on every pull request.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command creates a new module skeleton?

    pdk new module generates the directory layout, metadata and test configuration.
  2. 2. What does pdk validate NOT do?

    Validation is static. Acceptance tests are separate (Litmus).
  3. 3. You remove a parameter that callers use. Which part of the version changes?

    Breaking changes require a MAJOR bump under semantic versioning.
  4. 4. Which metadata field defines the operating systems tested by on_supported_os?

    rspec-puppet-facts reads operatingsystem_support to build the test matrix.

Summary

  • PDK creates modules, generates classes/defines/functions/facts, and runs validation and unit tests with one toolchain.
  • metadata.json carries name, version, dependencies and the supported OS list.
  • Follow semantic versioning for the module and for dependency ranges.
  • Document with Puppet Strings comments.
  • Internal modules are usually consumed straight from Git by the control repo.

Next: Acceptance Testing with Litmus