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