Puppet Class: role

Defined in:
manifests/init.pp

Overview

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:

  • namespace (Optional[String]) (defaults to: undef) —

    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 (”).

  • search_namespaces (Optional[Array[Role::SearchNamespace]]) (defaults to: undef) —

    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.

  • separator (String) (defaults to: '::') —

    Anything to put in between the namespace and the role.

  • resolve_order (Variant[Role::ResolveMethod, Array[Role::ResolveMethod]]) (defaults to: ['param', 'default']) —

    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.

  • role (Optional[String[1]]) (defaults to: undef) —

    The role this node should get.

  • trusted_extension_name (Optional[String[1]]) (defaults to: undef) —

    Name of the trusted fact (extension).

  • fact_name (Optional[String[1]]) (defaults to: undef) —

    Name of the fact that contains the role.

  • function_callback_name (Optional[String[1]]) (defaults to: undef) —

    A function that returns the role.

  • translate_role_callback (Variant[Undef, String[1], Hash]) (defaults to: undef) —

    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_role (String) (defaults to: 'default') —

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

  • default_namespace (String) (defaults to: 'role') —

    namespace to use if the default is used.

  • default_separator (String) (defaults to: '::') —

    separator to use if the default is used.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'manifests/init.pp', line 37

class role (
  Optional[String] $namespace = undef,
  String $separator = '::',
  Variant[Role::ResolveMethod, Array[Role::ResolveMethod]] $resolve_order = ['param', 'default'],

  Optional[String[1]] $role                   = undef,
  Optional[String[1]] $trusted_extension_name = undef,
  Optional[String[1]] $fact_name              = undef,
  Optional[String[1]] $function_callback_name = undef,
  Variant[Undef, String[1], Hash] $translate_role_callback = undef,

  Optional[Array[Role::SearchNamespace]] $search_namespaces = undef,

  String $default_role      = 'default',
  String $default_namespace = 'role',
  String $default_separator = '::',
) {
  # Check if the required 'configuration' is present
  if 'trusted' in $resolve_order {
    assert_type(String[1], $trusted_extension_name) |$_exp, $_actual| {
      fail('You should specify the trusted_extension_name when trusted is used in the resolve_array')
    }
  }
  if 'fact' in $resolve_order {
    assert_type(String[1], $fact_name) |$_exp, $_actual| {
      fail('You should specify the fact_name when fact is used in the resolve_array')
    }
  }
  if 'callback' in $resolve_order {
    assert_type(String[1], $function_callback_name) |$_exp, $_actual| {
      fail('You should specify the function_callback_name when callback is used in the resolve_array')
    }
  }
  unless $namespace or ($search_namespaces and size($search_namespaces) > 0) {
    fail('Either namespace or a not empty search_namespaces must be provided.')
  }

  $resolve_array = [$resolve_order].flatten.reduce([]) |Array[Optional[String]] $found, String $method| {
    case $method {
      'param' : {
        if $role {
          $resolved = $role
        }
        else {
          $resolved = undef
        }
      }
      'fact': {
        if $fact_name and $fact_name in $::facts {
          $resolved = $::facts[$fact_name]
        }
        else {
          $resolved = undef
        }
      }
      'callback': {
        if $function_callback_name {
          $resolved = call($function_callback_name)
        }
        else {
          $resolved = undef
        }
      }
      'trusted': {
        if $trusted_extension_name and $trusted_extension_name in $::trusted['extensions'] {
          $resolved = $::trusted['extensions'][$trusted_extension_name]
        }
        else {
          $resolved = undef
        }
      }
      'fail': {
        if $found.filter |$value| { $value =~ NotUndef }.length() == 0 {
          $tried = $resolve_order.reduce([]) |$tries, $method| {
            if ($method == 'fail') { break() }
            $tries + $method
          }.join(', ')
          fail("Unable to resolve a role and hard failure requested. Attempted methods: ${tried}.")
        }
        break()
      }
      default: {
        $resolved = undef
        break()
      }
    }
    $found + [$resolved]
  }.filter |$value| { $value =~ NotUndef }

  # Nothing was resolved.
  if size($resolve_array) == 0 {
    include "${default_namespace}${default_separator}${default_role}"
  } else {
    $resolved = $translate_role_callback ? {
      undef   => $resolve_array[0],
      Hash    => role::translate_with_map($resolve_array[0], $translate_role_callback),
      default => call($translate_role_callback, $resolve_array[0]),
    }

    # namespace was provided.
    if $namespace {
      include "${namespace}${separator}${resolved}"
    }
    # search_namespaces
    else {
      # sanitize the array with namespaces
      $search = role::expand_search_namespaces($separator, $search_namespaces)
      # find roles with a class that actually exists
      $existing_roles = $search.map |String $space, String $separator| {
        $rolename = "${space}${separator}${resolved}"
        if defined($rolename) { $rolename }
        else { false }
      }.filter |$val| {
        $val =~ String
      }
      if size($existing_roles) > 0 {
        include $existing_roles[0]
      } else {
        fail("Requested role '${resolved}' not found on any of the search namespaces.")
      }
    }
  }
}