diff options
| -rw-r--r-- | docs/clusters.rst | 1 | ||||
| -rw-r--r-- | sos/collector/clusters/__init__.py | 106 |
2 files changed, 84 insertions, 23 deletions
diff --git a/docs/clusters.rst b/docs/clusters.rst index 4388edb0..109c2cd7 100644 --- a/docs/clusters.rst +++ b/docs/clusters.rst @@ -4,5 +4,4 @@ .. automodule:: sos.collector.clusters :noindex: :members: - :undoc-members: :show-inheritance: diff --git a/sos/collector/clusters/__init__.py b/sos/collector/clusters/__init__.py index 43a4b49e..700687aa 100644 --- a/sos/collector/clusters/__init__.py +++ b/sos/collector/clusters/__init__.py @@ -14,6 +14,40 @@ from sos.options import ClusterOption class Cluster(): + """This is the class that cluster profiles should subclass in order to + add support for different clustering technologies and environments to + sos-collector. + + A profile should at minimum define a package that indicates the node is + configured for the type of cluster the profile is intended to serve and + then additionally be able to return a list of enumerated nodes via the + ``get_nodes()`` method + + + :param commons: The commons dict containing system information. The same as + what is handed to ``Plugin()`` + :type commons: ``dict`` + + + :cvar option_list: Options supported by the profile, and set by the + --cluster-option cmdline arg + :vartype option_list: ``list`` of ``tuples`` + + :cvar packages: What package(s) should this profile enable on + :vartype packages: ``tuple`` + + :cvar sos_plugins: Which plugins to forcibly enable for node reports + :vartype sos_plugins: ``list`` + + :cvar sos_plugin_options: Plugin options to forcibly set for nodes + :vartype sos_plugin_options: ``dict`` + + :cvar sos_preset: A SoSReport preset to forcibly enable on nodes + :vartype sos_preset: ``str`` + + :cvar cluster_name: The name of the cluster type + :vartype cluster_name: ``str`` + """ option_list = [] packages = ('',) @@ -23,16 +57,6 @@ class Cluster(): cluster_name = None def __init__(self, commons): - """This is the class that cluster profile should subclass in order to - add support for different clustering technologies and environments to - sos-collector. - - A profile should at minimum define a package that indicates the node is - configured for the type of cluster the profile is intended to serve and - then additionall be able to return a list of enumerated nodes via the - get_nodes() method - """ - self.master = None self.cluster_ssh_key = None self.tmpdir = commons['tmpdir'] @@ -83,8 +107,14 @@ class Cluster(): self.soslog.warn(self._fmt_msg(msg)) def get_option(self, option): - """This is used to by clusters to check if a cluster option was - supplied to sos-collector. + """ + This is used to by clusters to check if a cluster option was + supplied to sos collect + + :param option: The name of the option to fetch + :type option: ``str`` + + :returns: The value of the requested option if it exists, or ``False`` """ # check CLI before defaults for opt in self.opts.cluster_options: @@ -108,27 +138,42 @@ class Cluster(): self.cluster_ssh_key = key def exec_master_cmd(self, cmd, need_root=False): - """Used to retrieve output from a (master) node in a cluster""" + """Used to retrieve command output from a (master) node in a cluster + + :param cmd: The command to run + :type cmd: ``str`` + + :param need_root: Does the command require root privileges + :type need_root: ``bool`` + + :returns: The output and status of `cmd` + :rtype: ``dict`` + """ res = self.master.run_command(cmd, get_pty=True, need_root=need_root) if res['stdout']: res['stdout'] = res['stdout'].replace('Password:', '') return res def setup(self): - """This MAY be used by a cluster to do prep work in case there are + """ + This MAY be used by a cluster to do prep work in case there are extra commands to be run even if a node list is given by the user, and thus get_nodes() would not be called """ pass def check_enabled(self): - """This may be overridden by clusters + """ + This may be overridden by clusters - This is called by sos-collector on each cluster type that exists, and + This is called by sos collect on each cluster type that exists, and is meant to return True when the cluster type matches a criteria that indicates that is the cluster type is in use. Only the first cluster type to determine a match is run + + :returns: ``True`` if the cluster profile should be used, or ``False`` + :rtype: ``bool`` """ for pkg in self.packages: if self.master.is_installed(pkg): @@ -136,9 +181,14 @@ class Cluster(): return False def get_nodes(self): - """This MUST be overridden by a cluster. + """ + This MUST be overridden by a cluster profile subclassing this class + A cluster should use this method to return a list or string that contains all the nodes that a report should be collected from + + :returns: A list of node FQDNs or IP addresses + :rtype: ``list`` or ``None`` """ pass @@ -150,15 +200,22 @@ class Cluster(): return [] def get_node_label(self, node): - """Used by SosNode() to retrieve the appropriate label from the cluster - as set by set_node_label() in the cluster profile. + """ + Used by ``SosNode()`` to retrieve the appropriate label from the + cluster as set by ``set_node_label()`` in the cluster profile. + + :param node: The name of the node to get a label for + :type node: ``str`` + + :returns: The label to use for the node's report + :rtype: ``str`` """ label = self.set_node_label(node) node.manifest.add_field('label', label) return label def set_node_label(self, node): - """This may be overridden by clusters. + """This may be overridden by clusters profiles subclassing this class If there is a distinction between masters and nodes, or types of nodes, then this can be used to label the sosreport archive differently. @@ -166,8 +223,12 @@ class Cluster(): return '' def format_node_list(self): - """Format the returned list of nodes from a cluster into a known + """ + Format the returned list of nodes from a cluster into a known format. This being a list that contains no duplicates + + :returns: A list of nodes, without extraneous entries from cmd output + :rtype: ``list`` """ try: nodes = self.get_nodes() @@ -185,7 +246,8 @@ class Cluster(): return node_list def _run_extra_cmd(self): - """Ensures that any files returned by a cluster's run_extra_cmd() + """ + Ensures that any files returned by a cluster's run_extra_cmd() method are properly typed as a list for iterative collection. If any of the files are an additional sosreport (e.g. the ovirt db dump) then the md5 sum file is automatically added to the list |