Forge Home


Map roles in different namespaces


3,874 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.3.0 (latest)
  • 0.2.1
released Aug 28th 2019
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet > 3.0.0 < 7.0.0
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'vStone-role', '0.3.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add vStone-role
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install vStone-role --version 0.3.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



vStone/role — version 0.3.0 Aug 28th 2019


Table of Contents


This module aims to abstract resolving the correct role for your machine. It supports several ways to figure out the role:

  • Use trusted facts
  • Use facts
  • Use a parameter (allows configuration through hiera)
  • Use a custom function (Note, only available on Puppet > 5.x)
  • Fallback to a default
  • or Fail if there is no role found.

It also allows setting up a waterfall mechanism: no trusted fact? how about a regular one? a param?


Setup Requirements

Depending on how you want to use this module, you will need to learn about:

  • hiera
  • trusted facts
  • (custom) facts
  • writing functions

On a puppet side: we depend on the stdlib module for additional functions.


Most functionality should be usable with > puppet 4.x with the exception of features that depend on #call().

  • callback in role::resolve_order is not supported on puppet < 5.x
  • using a function name as role::translate_role_callback is not supported on puppet < 5.x

Quickstart: Configure your namespace.

Include role in your (default) node.


node 'default' {
  include ::role

Configure the namespace to use in hiera:


role::namespace: '::my_roles'

You can also define configuration parameters for the role module here. This will disallow users to overwrite the configuration in hiera:


node 'default' {
  class {'role':
    namespace => 'my_roles'



Using the resolve order.

role::namespace: '::my_roles'
  - trusted
  - fact
  - param
  - default

Load a base profile directly as default role:

role::default_namespace: ''
role::default_separator: ''
role::default_role: profile_base

Enforce setting up a role using trusted facts or fail the puppet run:

  - trusted
  - fail


It is possible to search for a role in multiple namespaces. To do this, supply an (non-empty) array with namespaces to look in.

By example:

role::separator: '::'
  - shared_roles
  - my_roles
  - {'': ''}
  - {customer: '_'}

The module will attempt to find the following classes (in order) for role foobar and use the first one that exists.

  • shared_roles::foobar
  • my_roles::foobar
  • foobar
  • customer_foobar

Note: A namespace parameter will always take precedence. In hiera, you can force a undef or nil value using ~.

role::namespace: ~
 - ''
 - {'my_roles': '::'}


Windows Users

When you have (puppet) developers that work on Windows workstations, you should prevent using :: (double colons) in your role names. Using such a role (foo::bar) in combination with hiera could result in filenames with :: in them. This will effectively prevent any Windows user from checking out the repository.

In stead, you can choose any other separator (__ for example) and remap the role to a class name using translate_role_callback. For role foo__bar, the following example would result in myspace::foo::bar being included.

role::namespace: 'myspace'
role::translate_role_callback: 'role::translate_double_underscores'

Trusted facts

If you intend to use trusted facts as classification for your roles, take the following remarks into account:

  • Do not use trusted in combination with facts in the resolve_order: Facts can easily be overridden on the agent side.
  • Your hiera hierarchy should not use anything besides trusted facts. Same reason applies.