PDK Templates

The pdk-templates repository contains the default templates (or blueprints) used by the Puppet Development Kit to create, convert, and update modules.

The following table shows the directories where different types of template are stored.

Use this README to understand the purpose, basic usage, and common configurable values for PDK templates. For further information about PDK, refer to our documentation site.

Table of contents

• Introduction
• How templates are used by PDK
• Basic usage
• Adjusting templates via .sync.yml
  • Adding configuration values
  • Removing default configuration values
  • Excluding files from default behaviour
  • Unmanaged and delete keys
  • Setting custom gems in the Gemfile
  • Manage Rubocop rules
• PDK default config values
• Further Notes

How templates are used by PDK

When you use PDK to build, convert, or update a module, PDK accesses the relevant template in the pdk-templates repository to retrieve default “instructions” on how to build the module. Those instructions are applied to the local repo in which the command was run.

When configuring the module, PDK reads a set of default settings in .config_defaults.yml and merges it with the configuration settings in .sync.yml.

The result of this merge creates a hidden hash containing the final configuration of the module that PDK applies. Top-level keys of this resulting hash correspond to target files. A global configuration is merged with the configuration hash for a particular target file. This allows module developers to override or amend the configuration by adding new values through .sync.yml. For example, a knockout prefix (---) can be applied to keys in .sync.yml to remove default configuration values.

Target files are created by rendering a corresponding template which refers its configuration via the @configs hash.

You can configure PDK to make files executable if the file is executable in the template. To do this, include manage_execute_permissions: true either in the target file or globally via the common config key.

Basic Usage

By default PDK uses the templates within this repository to render files for use within a module. To use a third-party template, pass its URL using the –-template-url flag as shown in the following example:

pdk convert --template-url https://github.com/puppetlabs/pdk-templates

PDK will default to the main branch when looking at the repository. You can specify other branches by using the --template-ref, like this:

pdk convert --template-url https://github.com/puppetlabs/pdk-templates --template-ref branch_name

Note: Commands run on PDK will use the last specified template repository.

When you have specified the template repository, you can get started with creating a module, if you don't already have one. Once your module is created, you can customize PDK-templates by editing the .sync.yml to override the default configuration, and then running PDK update on the module so that the new settings are applied.

For more information on basic usage and more detailed description of PDK in action please refer to PDK documentation, where you can find detailed instructions on how to create, convert and update modules, as well as other useful commands.

Adjusting templates via .sync.yml

While we provide a basic template it is likely that it will not match what you need exactly, as such we allow it to be altered or added to through the use of the .sync.yml file.

Here we will provide some examples of how you can use .sync.yml. For a more comprehensive list of default settings, check the PDK default config values section.

Adding configuration values

Values can be added to the data passed to the templates, thus allowing you to make changes such as testing against additional operating systems or adding new rubocop rules.

To add a value to an array simply place it into the .sync.yml file as shown below, here is the structure to add an additional unit test run against Puppet 6:

.travis.yml:
  includes:
    - env: PUPPET_GEM_VERSION="~> 6.0" CHECK=parallel_spec
      rvm: 2.5.0

Removing default configuration values

Values can be removed from the data passed to the templates using the knockout prefix --- in .sync.yml.

To remove a value from an array, prefix the value ---. For example, to remove 2.7.8 from the ruby_versions array in .travis.yml:

.travis.yml:
  ruby_versions:
    - '---2.7.8'

To remove a key from a hash, set the value to ---. For example, to remove the ip fact from spec/default_facts.yml:

spec/default_facts.yml:
  networking:
    ip: '---'

Excluding files from default behaviour

You can also configure the system to ignore specific files when performing default configuration. For example, we can prevent all .erb files from being targeted by the .gitattributes group settings by using:

".gitattributes": 
  exclude: 
  - "*.erb"

Unmanaged and delete keys

The unmanaged and delete keys also allow you to override default configurations. The unmanaged key allows you to specify files that are to be left untouched by the conversion or update, and delete allows you to specify that a file should be excluded from the module when you convert or update the module.

In the following example, the unmanaged and delete keys are used to specify that, regardless of the default setting defined in config_defaults.yml, PDK should leave the ci.yml file unmodified and delete travis.yml.

.github/workflows/ci.yml: 
  unmanaged: true 

.travis.yml: 
  delete: true

Setting custom gems in the Gemfile

To add a custom internal puppet-lint plugin served from an internal Rubygems source, add an entry similar to the following in .sync.yml file and run pdk update.

Gemfile:
  optional:
    ':development':
      - gem: 'puppet-lint-my_awesome_custom_module'
        version: '>= 2.0'
        source: 'https://myrubygems.example.com/'

Manage Rubocop rules

To disable or enable certain Rubocop rules, use the following structure:

.rubocop.yml:
  default_configs:
    Style/Documentation:
      Enabled: false

PDK default config values

The following is a description and explanation of each of the keys within .config_defaults.yml. This will help clarify the default settings that are applied by PDK.

All the values defined below can be overriden through .sync.yml.

common

Settings common to all templates

.gitattributes

A .gitattributes file in your repo allows you to ensure consistent git settings.

.gitignore

A .gitignore file in your repo allows you to specify intentionally untracked files to ignore.

Github Workflows

These workflows are depending on puppet-internal resources and are currently not suited for public consumption. Feel free to take them as inspiration how to run some tests on Github Actions. Please let us know at ia_content@puppet.com what you come up with!

.github/workflows/release_prep.yml

The release_prep workflow prepares a module release PR. By default the workflow can be triggered manually when a release preparation PR needs to be created, however it allows setting a cron based trigger that can run automatically. To set up the automated release cron you can add a configuration to your .sync.yml file that matches the following example:

release_schedule:
   cron: '0 3 * * 6'

In this example the automated release prep workflow is triggered every Saturday at 3 am.

.pdkignore

A .pdkignore file in your repo allows you to specify files to ignore when building a module package with pdk build.

.yardopts

YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions.

Rakefile

Rake is a Make-like program implemented in Ruby. Tasks and dependencies are specified in standard Ruby syntax within the Rakefile, present in the root directory of the code repository. Within modules context Rake tasks are used quite frequently, from ensuring the integrity of a module, running validation and tests, to tasks for releasing modules.

Rakefile:
  extras:
  - \'PuppetSyntax.exclude_paths = ["plans/**/*.pp","central/modules/deployments/plans/**/*.pp"]\'

.rubocop.yml

RuboCop is a Ruby static code analyzer. We use Rubocop to enforce a level of quality and consistency within Ruby code. Rubocop can be configured within .rubocop.yml which is located in the root directory of the code repository. Rubocop works by defining a sanitized list of cops that'll cleanup a code base without much effort, all of which support autocorrect and that are fairly uncontroversial across wide segments of the Community.

Gemfile

A Gemfile is a file we create which is used for describing gem dependencies for Ruby programs. All modules should have an associated Gemfile for installing the relevant gems. As development and testing is somewhat consistant between modules we have used the template to define a set of gems relevant to these processes.

Within each Gem group defined using the options above one or more gem item definitions may be listed in an array. Each item in that array must be a gem item hash.

spec/default_facts.yml

The spec/default_facts.yml file contains a list of facts to be used by default when running rspec tests

---
networking:
  ip: "172.16.254.254"
  ip6: "FE80:0000:0000:0000:AAAA:AAAA:AAAA"
  mac: "AA:AA:AA:AA:AA:AA"
is_pe: false

spec/spec_helper.rb

The spec/spec_helper.rb file contains setup for rspec tests

Further Notes

Please note that the early version of this template contained only a 'moduleroot' directory, and did not have a 'moduleroot_init'. The PDK 'pdk new module' command will still work with templates that only have 'moduleroot', however the 'pdk convert' command will fail if the template does not have a 'moduleroot_init' directory present. To remedy this please use the up to date version of the template.

Security Considerations on Github Actions

As explained in Use GitHub actions at your own risk, when running github actions from outside the organisation, there is a risk that symbolic references get taken over by malicious actors. Similar things happened before in other ecosystems and other packaging registries. The blog post goes on to suggest pinning to specific SHAs and provides some tooling to do so. The downsides for us are that the tooling doesn't work well with our ERB templating, and the additional cost of updating the SHAs across all modules. Instead we fork at-risk actions into the puppetlabs namespace and use them from there. This allows us to consume updates at our pace and deploy changes across all modules without delay, while avoiding actions that surreptitiously change while we're not looking.

Since this still has some overhead, we exclude some "big-name" action maintainers:

• Anything maintained by Github, e.g. https://github.com/actions
• Anything maintained as part of a bigger OSS project we're using, like https://github.com/ruby/setup-ruby
• Anything maintained by a Puppet employee

Updating actions guidelines

To keep efforts low when updating actions, we list all forked actions here. To keep confusion to a minimum, the version we use is always on a pdk-templates-v1 branch. This way we can update (git fetch/git push) forked repositories with no prejudice, test out the changes, and only then update the pdk-templates-v1 branch. That said, the branches used in pdk-templates should only contain upstream code and changes already in an upstream PR to minimize the diff we're carrying. If we later need to support multiple versions of an action as we roll out changes, we can increment the -v1 part in the branch name to manage multiple versions.

• kvrhdn/gha-buildevents ➡️ puppetlabs/kvrhdn-gha-buildevents
• Gamesight/slack-workflow-status ➡️ puppetlabs/Gamesight-slack-workflow-status

The repos have restricted access only to @modules team members.