[collect] Update docstrings for collect for help command

Updates the docstrings for collect components for the new `help`
command, including minor formatting changes to make the help output more
human-friendly.

This includes docstring updates and changes to transports and cluster
profiles.

Signed-off-by: Jake Hunsaker <jhunsake@redhat.com>

8 files changed, 114 insertions, 16 deletions

diff --git a/sos/collector/clusters/jbon.py b/sos/collector/clusters/jbon.py
index 8f083ac6..219e1901 100644
--- a/sos/collector/clusters/jbon.py
+++ b/sos/collector/clusters/jbon.py
@@ -12,11 +12,14 @@ from sos.collector.clusters import Cluster
 
 
 class jbon(Cluster):
-    '''Just a Bunch of Nodes
-
-    Used when --cluster-type=none (or jbon), to avoid cluster checks, and just
-    use the provided --nodes list
-    '''
+    """
+    Used when --cluster-type=none (or jbon) to avoid cluster checks, and just
+    use the provided --nodes list.
+
+    Using this profile will skip any and all operations that a cluster profile
+    normally performs, and will not set any plugins, plugin options, or presets
+    for the sos report generated on the nodes provided by --nodes.
+    """
 
     cluster_name = 'Just a Bunch Of Nodes (no cluster)'
     packages = None
diff --git a/sos/collector/clusters/kubernetes.py b/sos/collector/clusters/kubernetes.py
index 99f788dc..04752977 100644
--- a/sos/collector/clusters/kubernetes.py
+++ b/sos/collector/clusters/kubernetes.py
@@ -13,7 +13,12 @@ from sos.collector.clusters import Cluster
 
 
 class kubernetes(Cluster):
-
+    """
+    The kuberentes cluster profile is intended to be used on kubernetes
+    clusters built from the upstream/source kubernetes (k8s) project. It is
+    not intended for use with other projects or platforms that are built ontop
+    of kubernetes.
+    """
     cluster_name = 'Community Kubernetes'
     packages = ('kubernetes-master',)
     sos_plugins = ['kubernetes']
diff --git a/sos/collector/clusters/ocp.py b/sos/collector/clusters/ocp.py
index ae93ad58..f1714239 100644
--- a/sos/collector/clusters/ocp.py
+++ b/sos/collector/clusters/ocp.py
@@ -16,7 +16,40 @@ from sos.utilities import is_executable
 
 
 class ocp(Cluster):
-    """OpenShift Container Platform v4"""
+    """
+    This profile is for use with OpenShift Container Platform (v4) clusters
+    instead of the kubernetes profile.
+
+    This profile will favor using the `oc` transport type, which means it will
+    leverage a locally installed `oc` binary. This is also how node enumeration
+    is done. To instead use SSH to connect to the nodes, use the
+    '--transport=control_persist' option.
+
+    Thus, a functional `oc` binary for the user executing sos collect is
+    required. Functional meaning that the user can run `oc` commands with
+    clusterAdmin privileges.
+
+    If this requires the use of a secondary configuration file, specify that
+    path with the 'kubeconfig' cluster option.
+
+    Alternatively, provide a clusterAdmin access token either via the 'token'
+    cluster option or, preferably, the SOSOCPTOKEN environment variable.
+
+    By default, this profile will enumerate only master nodes within the
+    cluster, and this may be changed by overriding the 'role' cluster option.
+    To collect from all nodes in the cluster regardless of role, use the form
+    -c ocp.role=''.
+
+    Filtering nodes by a label applied to that node is also possible via the
+    label cluster option, though be aware that this is _combined_ with the role
+    option mentioned above.
+
+    To avoid redundant collections of OCP API information (e.g. 'oc get'
+    commands), this profile will attempt to enable the openshift plugin on only
+    a single master node. If the none of the master nodes have a functional
+    'oc' binary available, *and* the --no-local option is used, that means that
+    no API data will be collected.
+    """
 
     cluster_name = 'OpenShift Container Platform v4'
     packages = ('openshift-hyperkube', 'openshift-clients')
diff --git a/sos/collector/clusters/ovirt.py b/sos/collector/clusters/ovirt.py
index bd2d0c74..4587a1ca 100644
--- a/sos/collector/clusters/ovirt.py
+++ b/sos/collector/clusters/ovirt.py
@@ -17,6 +17,33 @@ ENGINE_KEY = '/etc/pki/ovirt-engine/keys/engine_id_rsa'
 
 
 class ovirt(Cluster):
+    """
+    This cluster profile is for the oVirt/RHV project which provides for a
+    virtualization cluster built ontop of KVM.
+
+    Nodes enumerated will be hypervisors within the envrionment, not virtual
+    machines running on those hypervisors. By default, ALL hypervisors within
+    the environment are returned. This may be influenced by the 'cluster' and
+    'datacenter' cluster options, which will limit enumeration to hypervisors
+    within the specific cluster and/or datacenter. The spm-only cluster option
+    may also be used to only collect from hypervisors currently holding the
+    SPM role.
+
+    Optionally, to only collect an archive from manager and the postgresql
+    database, use the no-hypervisors cluster option.
+
+    By default, a second archive from the manager will be collected that is
+    just the postgresql plugin configured in such a way that a dump of the
+    manager's database that can be explored and restored to other systems will
+    be collected.
+
+    The ovirt profile focuses on the upstream, community ovirt project.
+
+    The rhv profile is for Red Hat customers running RHV (formerly RHEV).
+
+    The rhhi_virt profile is for Red Hat customers running RHV in a
+    hyper-converged setup and enables gluster collections.
+    """
 
     cluster_name = 'Community oVirt'
     packages = ('ovirt-engine',)
diff --git a/sos/collector/clusters/satellite.py b/sos/collector/clusters/satellite.py
index 7c21e553..5e28531d 100644
--- a/sos/collector/clusters/satellite.py
+++ b/sos/collector/clusters/satellite.py
@@ -13,7 +13,14 @@ from sos.collector.clusters import Cluster
 
 
 class satellite(Cluster):
-    """Red Hat Satellite 6"""
+    """
+    This profile is specifically for Red Hat Satellite 6, and not earlier
+    releases of Satellite.
+
+    While note technically a 'cluster' in the traditional sense, Satellite
+    does provide for 'capsule' nodes which is what this profile aims to
+    enumerate beyond the 'primary' Satellite system.
+    """
 
     cluster_name = 'Red Hat Satellite 6'
     packages = ('satellite', 'satellite-installer')
diff --git a/sos/collector/transports/control_persist.py b/sos/collector/transports/control_persist.py
index 3e848b41..ae6c7e43 100644
--- a/sos/collector/transports/control_persist.py
+++ b/sos/collector/transports/control_persist.py
@@ -26,10 +26,18 @@ from sos.utilities import sos_get_command_output
 
 
 class SSHControlPersist(RemoteTransport):
-    """A transport for collect that leverages OpenSSH's Control Persist
+    """
+    A transport for collect that leverages OpenSSH's ControlPersist
     functionality which uses control sockets to transparently keep a connection
     open to the remote host without needing to rebuild the SSH connection for
-    each and every command executed on the node
+    each and every command executed on the node.
+
+    This transport will by default assume the use of SSH keys, meaning keys
+    have already been distributed to target nodes. If this is not the case,
+    users will need to provide a password using the --password or
+    --password-per-node option, depending on if the password to connect to all
+    nodes is the same or not. Note that these options prevent the use of the
+    --batch option, as they require user input.
     """
 
     name = 'control_persist'
diff --git a/sos/collector/transports/local.py b/sos/collector/transports/local.py
index 2996d524..dd72053c 100644
--- a/sos/collector/transports/local.py
+++ b/sos/collector/transports/local.py
@@ -15,9 +15,10 @@ from sos.collector.transports import RemoteTransport
 
 
 class LocalTransport(RemoteTransport):
-    """A 'transport' to represent a local node. This allows us to more easily
-    extend SoSNode() without having a ton of 'if local' or similar checks in
-    more places than we actually need them
+    """
+    A 'transport' to represent a local node. No remote connection is actually
+    made, and all commands set to be run by this transport are executed locally
+    without any wrappers.
     """
 
     name = 'local_node'
diff --git a/sos/collector/transports/oc.py b/sos/collector/transports/oc.py
index 720dd61d..0fc9eee8 100644
--- a/sos/collector/transports/oc.py
+++ b/sos/collector/transports/oc.py
@@ -18,15 +18,29 @@ from sos.utilities import (is_executable, sos_get_command_output,
 
 
 class OCTransport(RemoteTransport):
-    """This transport leverages the execution of commands via a locally
+    """
+    This transport leverages the execution of commands via a locally
     available and configured ``oc`` binary for OCPv4 environments.
 
+    The location of the oc binary MUST be in the $PATH used by the locally
+    loaded SoS policy. Specifically this means that the binary cannot be in the
+    running user's home directory, such as ~/.local/bin.
+
     OCPv4 clusters generally discourage the use of SSH, so this transport may
     be used to remove our use of SSH in favor of the environment provided
     method of connecting to nodes and executing commands via debug pods.
 
-    Note that this approach will generate multiple debug pods over the course
-    of our execution
+    The debug pod created will be a privileged pod that mounts the host's
+    filesystem internally so that sos report collections reflect the host, and
+    not the container in which it runs.
+
+    This transport will execute within a temporary 'sos-collect-tmp' project
+    created by the OCP cluster profile. The project will be removed at the end
+    of execution.
+
+    In the event of failures due to a misbehaving OCP API or oc binary, it is
+    recommended to fallback to the control_persist transport by manually
+    setting the --transport option.
     """
 
     name = 'oc'