remote

Remote module to execute commands on hosts via Cumin.

class spicerack.remote.Remote(config, dry_run=True)[source]

Bases: object

Remote class to interact with Cumin.

Initialize the instance.

Parameters:
  • config (str) -- the path of Cumin's configuration file.
  • dry_run (bool, optional) -- whether this is a DRY-RUN.
query(query_string)[source]

Execute a Cumin query and return the matching hosts.

Parameters:query_string (str) -- the Cumin query string to execute.
Returns:RemoteHosts instance matching the given query.
Return type:spicerack.remote.RemoteHosts
exception spicerack.remote.RemoteCheckError[source]

Bases: spicerack.exceptions.SpicerackCheckError

Custom exception class for check errors of this module.

exception spicerack.remote.RemoteError[source]

Bases: spicerack.exceptions.SpicerackError

Custom exception class for errors of this module.

exception spicerack.remote.RemoteExecutionError(retcode, message)[source]

Bases: spicerack.remote.RemoteError

Custom exception class for remote execution errors.

Override parent constructor to add the return code attribute.

class spicerack.remote.RemoteHosts(config, hosts, dry_run=True)[source]

Bases: object

Remote Executor class.

This class can be extended to customize the interaction with remote hosts passing a custom factory function to spicerack.remote.Remote.query.

Initialize the instance.

Parameters:
Raises:

spicerack.remote.RemoteError -- if no hosts were provided.
hosts

Getter for the hosts property.

Returns:a copy of the targeted hosts.
Return type:ClusterShell.NodeSet.NodeSet
init_system()[source]

Detect the init system.

Returns:a list of 2-element tuples with hosts ClusterShell.NodeSet.NodeSet as first item and the init system str as second.
Return type:list
reboot(batch_size=1, batch_sleep=180.0)[source]

Reboot hosts.

Parameters:
  • batch_size (int, optional) -- how many hosts to reboot in parallel.
  • batch_sleep (float, optional) -- how long to sleep between one reboot and the next.
static results_to_list(results, callback=None)[source]

Extract execution results into a list converting them with an optional callback.

Todo

move it directly into Cumin.

Parameters:
  • results (generator) -- generator returned by run_sync() and run_async() to iterate over the results.
  • callback (callable, optional) -- an optional callable to apply to each result output (it can be multiline). The callback will be called with a the string output as the only parameter and must return the extracted value. The return type can be chosen freely.
Returns:

a list of 2-element tuples with hosts ClusterShell.NodeSet.NodeSet as first item and the extracted outputs str as second. This is because NodeSet are not hashable.
Return type:

list
Raises:

spicerack.remote.RemoteError -- if unable to run the callback.
run_async(*commands, success_threshold=1.0, batch_size=None, batch_sleep=None, is_safe=False)[source]

Execute commands on hosts matching a query via Cumin in async mode.

Parameters:
  • *commands (str, cumin.transports.Command) -- arbitrary number of commands to execute on the target hosts.
  • success_threshold (float, optional) -- to consider the execution successful, must be between 0.0 and 1.0.
  • batch_size (int, str, optional) -- the batch size for cumin, either as percentage (e.g. 25%) or absolute number (e.g. 5).
  • batch_sleep (float, optional) -- the batch sleep in seconds to use in Cumin before scheduling the next host.
  • is_safe (bool, optional) -- whether the command is safe to run also in dry-run mode because it's a read-only command that doesn't modify the state.
Returns:

cumin.transports.BaseWorker.get_results to allow to iterate over the results.
Return type:

generator
Raises:

RemoteExecutionError -- if the Cumin execution returns a non-zero exit code.
run_sync(*commands, success_threshold=1.0, batch_size=None, batch_sleep=None, is_safe=False)[source]

Execute commands on hosts matching a query via Cumin in sync mode.

Parameters:
  • *commands (str, cumin.transports.Command) -- arbitrary number of commands to execute on the target hosts.
  • success_threshold (float, optional) -- to consider the execution successful, must be between 0.0 and 1.0.
  • batch_size (int, str, optional) -- the batch size for cumin, either as percentage (e.g. 25%) or absolute number (e.g. 5).
  • batch_sleep (float, optional) -- the batch sleep in seconds to use in Cumin before scheduling the next host.
  • is_safe (bool, optional) -- whether the command is safe to run also in dry-run mode because it's a read-only command that doesn't modify the state.
Returns:

cumin.transports.BaseWorker.get_results to allow to iterate over the results.
Return type:

generator
Raises:

RemoteExecutionError -- if the Cumin execution returns a non-zero exit code.
uptime()[source]

Get current uptime.

Returns:a list of 2-element tuple instances with hosts ClusterShell.NodeSet.NodeSet as first item and float uptime as second item.
Return type:list
wait_reboot_since(since)[source]

Poll the host until is reachable and has an uptime lower than the provided datetime.

Parameters:since (datetime.datetime) -- the time after which the host should have booted.
Raises:spicerack.remote.RemoteCheckError -- if unable to connect to the host or the uptime is higher than expected.
class spicerack.remote.RemoteHostsAdapter(remote_hosts)[source]

Bases: object

Base adapter to write classes that expand the capabilities of RemoteHosts.

This adapter class is a helper class to reduce duplication when writing classes that needs to add capabilities to a RemoteHosts instance. The goal is to not extend the RemoteHosts but instead delegate to its instances. This class fits when a single RemoteHosts instance is enough, but for more complex cases, in which multiple RemoteHosts instances should be orchestrated, it's ok to not extend this class and create a standalone one.

Initialize the instance.

Parameters:remote_hosts (spicerack.remote.RemoteHosts) -- the instance to act on the remote hosts.