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 #[](‘roles’) 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(host, role) ⇒ Object

Add the provided role to the host

Parameters:

  • host (Host) —

    Host to add role to

  • role (String) —

    The role to add to host



159
160
161
 
# File 'lib/beaker/dsl/roles.rb', line 159

def add_role(host, role)
  host[:roles] = host[:roles] | [role]
end

#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



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/beaker/dsl/roles.rb', line 171

def add_role_def role
  if role.is_a?(Array)
    role.each do |r|
      add_role_def r
    end
  elsif not respond_to? role
    if !/\A[[:alpha:]]+[a-zA-Z0-9_]*[!?=]?\Z/.match?(role)
      raise ArgumentError, "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
      hosts_with_role = hosts_with_role.pop if hosts_with_role.length == 1
      hosts_with_role
    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



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

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



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

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



151
152
153
 
# File 'lib/beaker/dsl/roles.rb', line 151

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 or :version is not specified, then either the ‘aio’ role or type will be needed for a host to be the AIO version.

True if host has

* PE version (:pe_ver) >= 4.0
* FOSS version (:version) >= 4.0
* the role 'aio'
* the type 'aio'

Returns:

  • (Boolean) —

    whether or not a host is AIO-capable



135
136
137
138
139
140
141
142
143
144
 
# File 'lib/beaker/dsl/roles.rb', line 135

def aio_version?(host)
  %i[pe_ver version].each do |key|
    version = host[key]
    return !version_is_less(version, '4.0') if version && !version.empty?
  end
  return true if host[:roles] && host[:roles].include?('aio')
  return true if host[:type] && /(\A|-)aio(\Z|-)/.match(host[:type])

  false
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



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

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:



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

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:



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

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:



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

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.



247
248
249
250
251
 
# File 'lib/beaker/dsl/roles.rb', line 247

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



225
226
227
228
229
230
231
 
# File 'lib/beaker/dsl/roles.rb', line 225

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.



237
238
239
240
241
 
# File 'lib/beaker/dsl/roles.rb', line 237

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



213
214
215
 
# File 'lib/beaker/dsl/roles.rb', line 213

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:



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

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



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

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