Forge Home


Map roles in different namespaces


3,615 latest version

5.0 quality score

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.