role

Table of Contents

• Introduction
• Setup
  • Setup Requirements
  • Compatibility
• Quickstart: Configure your namespace.
• Configuration
  • resolve_order
  • search_namespaces
• Notes
  • Windows Users
  • Trusted facts
• Development

Introduction

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

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.

Compatibility

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.

manifests/site.pp:

node 'default' {
  include ::role
}

Configure the namespace to use in hiera:

hiera/common.yaml:

---
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:

manifests/site.pp:

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

Configuration

resolve_order

Using the resolve order.

---
role::namespace: '::my_roles'
role::resolve_order:
  - 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:

role::resolve_order:
  - trusted
  - fail

search_namespaces

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: '::'
role::search_namespaces:
  - 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: ~
role::search_namespaces:
 - ''
 - {'my_roles': '::'}

Notes

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.

Development

Reference

Table of Contents

Classes

• role: Assigns the correct role to each node. It acts as a proxy which allows you to store your roles in a different namespaced module. For a singl
• role::default: Dummy default role that does nothing.

Functions

• role::expand_search_namespaces: Sanitizes Role::SearchNamespaces for use in role.
• role::translate_double_underscores: Translates all double (or more) underscores in a role to '::'
• role::translate_slash: Translates all (repeated) slashes in a role to '::'
• role::translate_with_map: Translate a role by executing a gsubstr(pattern, value, 'G') with patterns and values from the provided map.

Data types

• Role::ResolveMethod: Supported resolve methods
• Role::SearchNamespace: A SearchNamespace can be a single string or a hash.

Classes

role

Assigns the correct role to each node.

It acts as a proxy which allows you to store your roles in a different namespaced module. For a single host, you can also use a specific configuration (upstream / shared roles and profiles).

To get started, you should define the namespace (or search_namespaces) to use.

Parameters

The following parameters are available in the role class.

namespace

Data type: Optional[String]

The module namespace that holds your roles. If you are not using namespaces and map roles directly to class names, make this an empty string ('').

Default value: undef

search_namespaces

Data type: Optional[Array[Role::SearchNamespace]]

A list of namespaces to search. If using this, we will attempt to find the first existing role in order. If no match is found, the puppet run will fail.

Default value: undef

separator

Data type: String

Anything to put in between the namespace and the role.

Default value: '::'

resolve_order

Data type: Variant[Role::ResolveMethod, Array[Role::ResolveMethod]]

The order in which we will be looking for the correct role to use. Currently supported values are:

• trusted: Use a trusted fact. The name must be configured using trusted_extension_name.
• fact: Use a fact. The name must be configured using fact_name.
• param: Uses the provided role parameter. This can also be used to configure using hiera.
• callback: Use a function callback. The function must be configured using function_callback_name. (Not available on puppet 4.x!)
• default: Fall back to the default value. You would typically put this after other methods.
• fail: Fail the run if this method is reached. This enforces setting up a role and skips using the default role.

Default value: ['param', 'default']

role

Data type: Optional[String[1]]

The role this node should get.

Default value: undef

trusted_extension_name

Data type: Optional[String[1]]

Name of the trusted fact (extension).

Default value: undef

fact_name

Data type: Optional[String[1]]

Name of the fact that contains the role.

Default value: undef

function_callback_name

Data type: Optional[String[1]]

A function that returns the role.

Default value: undef

translate_role_callback

Data type: Variant[Undef, String[1], Hash]

Optionally, a function name that should be used or a map with gsubstr tuples.

• function name: A puppet function to call. It should accept a single value and return a string. (Not available on puppet 4.x!) See role::translate_slash and role::translate_double_underscores for examples.
• a Hash: A mapping with keypairs that is passed to role::translate_with_map.

Default value: undef

default_role

Data type: String

the default role to assume. Used when no resolve method provides a result.

Default value: 'default'

default_namespace

Data type: String

namespace to use if the default is used.

Default value: '::role'

default_separator

Data type: String

separator to use if the default is used.

Default value: '::'

role::default

Dummy default role that does nothing.

Functions

role::expand_search_namespaces

Type: Puppet Language

This function is used to sanitize user input and return a single map with namespace - separator entries.

Examples

hiera configured namespaces

$search_namespaces = [
  '',
  { 'my_roles' => '_' },
  'public_roles',
]
$expanded = role::expand_search_namespaces('::', $search_namespaces)
# => {'' => '::', 'my_roles' => '_', 'public_roles' => '::' }

role::expand_search_namespaces(String $separator, Variant[Role::SearchNamespace, Array[Role::SearchNamespace]] $search)

This function is used to sanitize user input and return a single map with namespace - separator entries.

Returns: Hash[String, String] Expanded configuration.

Examples

hiera configured namespaces

$search_namespaces = [
  '',
  { 'my_roles' => '_' },
  'public_roles',
]
$expanded = role::expand_search_namespaces('::', $search_namespaces)
# => {'' => '::', 'my_roles' => '_', 'public_roles' => '::' }

separator

Data type: String

Default separator to use when the namespace does not provide one.

search

Data type: Variant[Role::SearchNamespace, Array[Role::SearchNamespace]]

Role::SearchNamespaces to expand.

role::translate_double_underscores

Type: Puppet Language

Translates all double (or more) underscores in a role to '::'

role::translate_double_underscores(String $role)

Translates all double (or more) underscores in a role to '::'

Returns: String Translated role.

role

Data type: String

Role to perform translate on.

role::translate_slash

Type: Puppet Language

Translates all (repeated) slashes in a role to '::'

role::translate_slash(String $role)

Translates all (repeated) slashes in a role to '::'

Returns: String Translated role.

role

Data type: String

Role to perform translate on.

role::translate_with_map

Type: Puppet Language

Translate a role by executing a gsubstr(pattern, value, 'G') with patterns and values from the provided map.

`role::translate_with_map(String $role, Hash[

Variant[String, Regexp],
String

] $map, Boolean $strict = false)`

Translate a role by executing a gsubstr(pattern, value, 'G') with patterns and values from the provided map.

Returns: String Translated role.

role

Data type: String

Role to perform translate on.

map

Data type: Hash[ Variant[String, Regexp], String ]

A map with gsubstr translations with key as pattern and value as replacement.

strict

Data type: Boolean

Experimental parameter. If enabled, fails the puppet run when a role includes characters that are in the target map present as values. This would indicate that a role is being provided which would not have expected replacement values in use. (This could happen during a migration, for example.

Data types

Role::ResolveMethod

Supported resolve methods

Alias of Enum['trusted', 'param', 'fact', 'callback', 'default', 'fail']

Role::SearchNamespace

A SearchNamespace can be a single string or a hash.

Alias of Variant[String, Hash[String, Optional[String]]]