Customize your module configuration

PDK uses a default template to configure modules. You can customize your configuration by specifying your own custom template, customizing specific template settings, or setting module metadata.json default values.

On this page:

Specify a custom template

You can specify a custom template when creating a new module or when converting an existing module.

Fork the default template from the pdk-templates project on GitHub and make any changes you need.

Major changes to the Gemfile or Rakefile of the default template can cause errors with PDK. Test these changes thoroughly.
Run either the pdk convert or the pdk new module command with the --template-url option. For example:
Copy
```
pdk convert --template-url https://github.com/myrepo/custom-module-template
```

Result

The custom template location is added to the module's metadata.json file in the template-url field. Going forward, every time you run pdk update, PDK applies your custom template to the module.

Customize the default template

You can customize the default template on an existing module, whether you created it with PDK or you are converting it to PDK. To customize a new module, first create the module with PDK, and then apply any changes you want to the template.

To customize the default template, update the .sync.yml file in your module. This file must be in the top directory of the module and must be in a valid YAML format. When you convert or update a module, PDK reads the .sync.yml file and applies those changes to the relevant files.

In the sync.yml file, specify the file you want to manage with a top-level key, such as appveyor.yml. Then add keys, indented two spaces, to change configuration of that file. For example:

Setting delete: true deletes the named file, even if it is supplied through the module template.
Setting unmanaged: true ignores the named file, even if it is supplied through the module template.
To see a complete updated list of sync.yml settings, see the pdk-templates README.

For example, this .sync.yml file removes the appveyor.yml file from the module. It also changes the Travis CI configuration to use Ruby version 2.1.9 and to run the command bundle exec rake rubocop as the test script in the module.

Copy

appveyor.yml:
  delete: true
.travis.yml:
  extras:
  -rvm: 2.1.9
   script: bundle exec rake rubocop

Set module metadata.json default values

Set persistent defaults for module metadata fields, such as author, template-url, and license with PDK commands. See Set module metadata.json default values for details.

Customize unit and unit acceptance tests

When the default unit test configuration does not meet your requirements, you can customize unit and unit acceptance tests for a module. For customizations that directly set a value, for example, the location of an ignore file, edit the sync.yml file. For customizations where values are set conditionally, for example, tests that apply to only one OS, edit settings in local RSpec helper files.

Customize simple unit test settings

Make direct changes to configuration settings in sync.yml in the root directory of your module. In sync.yml, you can customize settings for Git, ignore files, YARD, Rake, Rubocop, the Gemfile, default facts, and RSpec testing.

Read more about customizing settings in sync.yml in the PDK template documentation.

For a reference implementation, see the following example in the puppetlabs-apache module:

sync.yml

Customize conditionally set values for unit tests and unit acceptance tests

Customize values that must be defined conditionally in spec_helper_local.rb (for unit tests) and spec_helper_acceptance_local.rb (for unit acceptance tests). For example, you can customize a unit test for a particular OS in spec_helper_local.rb.

Create spec_helper_local.rb and spec_helper_acceptance_local.rb files as needed in the module's spec directory.

For reference implementations, see the following examples in the puppetlabs-apache module:

Add custom facts to PDK unit tests

Unit tests rely on a predefined set of facts from voxpupuli-facterdb. As older OS reach end of life (EOL), their facts are no longer available to PDK, causing OS-specific spec tests to fail. When needed facts are not available, you can add custom facts to PDK unit tests via spec_helper_local.rb by completing the following steps.

These fact files provide the values that are loaded during unit test runs instead of, or in addition to, the default fact data.

Custom facts added using this approach are intended for unit testing only; how facts are collected or used at runtime does not change.

Before you begin:

You have an existing module created with PDK.
You know which additional facts you want to add and you have a facts file, for example, redhat-7-x86_64.facts.

If the <MODULE>/spec/fixtures/facts directory does not already exist, create it.
Copy
```
mkdir -p <MODULE>/spec/fixtures/facts
```

Add custom facts to your module’s spec/fixtures/facts directory.

Copy

cp /<PATH_TO_FACTS_FILE>/<FACTS_FILE> spec/fixtures/facts/<FACTS_FILE>

For example:

Copy

cp /<PATH_TO_FACTS_FILE>/redhat-7-x86_64.facts spec/fixtures/facts/redhat-7-x86_64.facts

Configure your test environment so that PDK and RSpec can locate and load the custom fact files you added.

If the module doesn't have a <MODULE>/spec/spec_helper_local.rb file, create one.

In spec/spec_helper_local.rb, after any require statements, add the following lines:
Copy
```
module_spec_dir = File.dirname(__FILE__) custom_facts = File.join(module_spec_dir, 'fixtures', 'facts') ENV['FACTERDB_SEARCH_PATHS'] = custom_facts
```
Run your module’s unit tests.
Copy
```
pdk test unit
```
Your custom facts and default facts from spec/default_facts.yml will be loaded during testing. When you successfully add facts, running tests show code related to the added facts passing. For example, if you added RHEL 7 custom facts, the RHEL 7-related code now passes.

If the tests fail, make sure the added facts are in the correct location, for example, my_module/spec/fixtures/facts/redhat-7-x86_64.facts, and that the file extension is .facts.

Optional: Add custom facts with a third‑party facts tool

You can use rspec-puppet-facts, a third‑party tool, to add custom fact sets during testing for different OS. You can use it if it fits your workflow, but it is not required to add custom facts for testing.

This tool is not maintained or supported by Puppet and its user interface and usage and is subject to change without notice. For the latest published information about rpec-puppet-facts, see the rspec-puppet-facts README.