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: -
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: - config (cumin.Config) -- the configuration for Cumin.
- hosts (ClusterShell.NodeSet.NodeSet) -- the hosts to target for the remote execution.
- dry_run (bool, optional) -- whether this is a DRY-RUN.
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 systemstr
as second.Return type: list
-
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 outputsstr
as second. This is because NodeSet are not hashable.Return type: 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 hostsClusterShell.NodeSet.NodeSet
as first item andfloat
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.