Module: Beaker::DSL::Roles

Included in:
Beaker::DSL
Defined in:
lib/beaker/dsl/roles.rb

Overview

Identifying hosts.

This aids in reaching common subsets of hosts in a testing matrix.

It requires the class it is mixed into to provide the attribute hosts which contain the hosts to search, these should implement Host's interface. They, at least, must have #[] and #to_s available and provide an array when # is called.

Also the constant Outcomes::FailTest needs to be defined it will be raised in error conditions

Instance Method Summary collapse

Instance Method Details

#add_role_def(role) ⇒ Object

Create a new role method for a given arbitrary role name. Makes it possible to be able to run commands without having to refer to role by String or Symbol. Will not add a new method definition if the name is already in use. Symbol or an Array of Strings or Symbols.

Examples:

Basic usage

add_role_def('myrole')
on myrole, "run command"

Parameters:

  • role (String, Symbol, Array[String,Symbol]) —

    The role that you wish to create a definition for, either a String



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/beaker/dsl/roles.rb', line 151

def add_role_def role
  if role.kind_of?(Array)
    role.each do |r|
      add_role_def r
    end
  else
    if not respond_to? role
      if role !~ /\A[[:alpha:]]+[a-zA-Z0-9_]*[!?=]?\Z/
        raise "Role name format error for '#{role}'.  Allowed characters are: \na-Z\n0-9 (as long as not at the beginning of name)\n'_'\n'?', '!' and '=' (only as individual last character at end of name)"
      end
      self.class.send :define_method, role.to_s do
        hosts_with_role = hosts_as role.to_sym
        if hosts_with_role.length == 1
          hosts_with_role = hosts_with_role.pop
        end
        hosts_with_role
      end
    end
  end
end

#agent_only(host) ⇒ Boolean

Determine if this host is exclusively an agent (only has a single role 'agent')

Examples:

Basic usage

if agent_only(host)
  puts "this host is ONLY an agent!"
end

Parameters:

  • host (Host) —

    Beaker host to check

Returns:

  • (Boolean) —

    True if agent-only, false otherwise



118
119
120
 
# File 'lib/beaker/dsl/roles.rb', line 118

def agent_only(host)
    host['roles'].length == 1 && host['roles'].include?('agent')
end

#agents ⇒ Array<Host>

The hosts for which ['roles'] include 'agent'

Examples:

Basic usage

agents.each do |agent|
  ...test each agent in turn...
end

Returns:

  • (Array<Host>) —

    May be empty



27
28
29
 
# File 'lib/beaker/dsl/roles.rb', line 27

def agents
  hosts_as 'agent'
end

#aio_agent?(host) ⇒ Boolean

Determine if the host is an AIO agent

Parameters:

  • host (Host) —

    Beaker host to check

Returns:

  • (Boolean) —

    whether this host is an AIO agent or not



139
140
141
 
# File 'lib/beaker/dsl/roles.rb', line 139

def aio_agent?(host)
  aio_version?(host) && agent_only(host)
end

#aio_version?(host) ⇒ Boolean

Note:

aio version is just a base-line condition. If you want to check that a host is an aio agent, refer to #aio_agent?.

Determine whether a host has an AIO version or not. If a host :pe_ver is not specified, then it is open-ended, and as such, can be an AIO version depending on the context.

Returns:

  • (Boolean) —

    whether or not a host is AIO-capable



130
131
132
 
# File 'lib/beaker/dsl/roles.rb', line 130

def aio_version?(host)
  return !( host[:pe_ver] && version_is_less(host[:pe_ver], '4.0') )
end

#any_hosts_as?(role) ⇒ Boolean

Determine if there is a host or hosts with the given role defined if any_hosts_as?(:master) puts "master is defined" end

Examples:

Usage

Returns:

  • (Boolean) —

    True if there is a host with role, false otherwise



180
181
182
 
# File 'lib/beaker/dsl/roles.rb', line 180

def any_hosts_as?(role)
  hosts_as(role).length > 0
end

#dashboard ⇒ Host

The host for which ['roles'] include 'dashboard'

Examples:

Basic usage

on, agent, "curl https://#{database}/nodes/#{agent}"

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



70
71
72
 
# File 'lib/beaker/dsl/roles.rb', line 70

def dashboard
  find_host_with_role :dashboard
end

#database ⇒ Host

The host for which ['roles'] include 'database'

Examples:

Basic usage

on, agent, "curl -k http://#{database}:8080"

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



57
58
59
 
# File 'lib/beaker/dsl/roles.rb', line 57

def database
  find_host_with_role :database
end

#default ⇒ Host

The default host

  • if only one host defined, then that host OR
  • host with 'default' as a role OR
  • host with 'master' as a role

Examples:

Basic usage

on, default, "curl https://#{database}/nodes/#{agent}"

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



88
89
90
 
# File 'lib/beaker/dsl/roles.rb', line 88

def default
  find_host_with_role :default
end

#find_at_most_one(role) ⇒ Host

Returns the host, or nil if not found

Parameters:

  • role (Symbol, String) —

    The role to find a host for

Returns:

  • (Host) —

    Returns the host, or nil if not found

Raises:

  • Raises a failure exception if more than one host that matches the specified role is found.



230
231
232
233
234
 
# File 'lib/beaker/dsl/roles.rb', line 230

def find_at_most_one role
  find_at_most_one_host_with_role(hosts, role)
rescue ArgumentError => e
  raise DSL::Outcomes::FailTest, e.to_s
end

#find_host_with_role(role) ⇒ Host

finds the appropriate number of hosts for a given role determines whether to allow no server using the masterless option

Parameters:

  • role (Symbol, String) —

    The role to find a host for

Returns:

  • (Host) —

    Returns the host, or nil if masterless and none are found for that role

Raises:

  • Throws an exception if an inappropriate number of hosts are found for that role



208
209
210
211
212
213
214
 
# File 'lib/beaker/dsl/roles.rb', line 208

def find_host_with_role role
  if (defined? options) && options[:masterless]
    find_at_most_one role
  else
    find_only_one role
  end
end

#find_only_one(role) ⇒ Host

Returns the host, if one and only one is found

Parameters:

  • role (Symbol, String) —

    The role to find a host for

Returns:

  • (Host) —

    Returns the host, if one and only one is found

Raises:

  • Raises a failure exception if one and only one host that matches the specified role is NOT found.



220
221
222
223
224
 
# File 'lib/beaker/dsl/roles.rb', line 220

def find_only_one role
  only_host_with_role(hosts, role)
rescue ArgumentError => e
  raise DSL::Outcomes::FailTest, e.to_s
end

#hosts_as(desired_role = nil) ⇒ Array<Host>

Select hosts that include a desired role from #hosts

Examples:

Basic usage

hairy = hosts_as :yak
hairy.each do |yak|
  on yak, 'shave'
end

Parameters:

  • desired_role (String, Symbol) (defaults to: nil) —

    The role to select for

Returns:

  • (Array<Host>) —

    The hosts that match desired_role, may be empty



196
197
198
 
# File 'lib/beaker/dsl/roles.rb', line 196

def hosts_as(desired_role = nil)
  hosts_with_role(hosts, desired_role)
end

#master ⇒ Host

The host for which ['roles'] include 'master'. If no host has the 'master' role, then use the host defined as 'default'. If no host is defined as a 'master' and there is no 'default' host defined then it either raises an error (has a master), or it returns nil (masterless)

Examples:

Basic usage

on, master, 'cat /etc/puppet/puppet.conf'

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



44
45
46
 
# File 'lib/beaker/dsl/roles.rb', line 44

def master
  find_host_with_role :master
end

#not_controller(host) ⇒ Boolean

Determine if host is not a controller, does not have roles 'master', 'dashboard' or 'database'.

Examples:

Basic usage

if not_controller(host)
  puts "this host isn't in charge!"
end

Returns:

  • (Boolean) —

    True if agent-only, false otherwise



102
103
104
105
106
 
# File 'lib/beaker/dsl/roles.rb', line 102

def not_controller(host)
  controllers = ['dashboard', 'database', 'master', 'console']
  matched_roles = host['roles'].select { |v| controllers.include?(v) }
  matched_roles.length == 0
end