Improve Troubleshooting section

Complete the onos-diagnostics subsection. Add Pipeline Walkthrough
as subsection of ONOS troubleshooting and fix a couple of wrong
namespace

Change-Id: Id6d58bd1ae587a268a96a43087e3997b677aee12
diff --git a/troubleshooting.rst b/troubleshooting.rst
index 149d051..77208dd 100644
--- a/troubleshooting.rst
+++ b/troubleshooting.rst
@@ -132,7 +132,7 @@
 
 .. code-block::
 
-    $ kubectl -n tost port-forward onos-tost-onos-classic-0 8101
+    $ kubectl -n sdfabric port-forward onos-tost-onos-classic-0 8101
     // In another terminal or you can send to /dev/null the port-forward
     $ ssh -p 8101 karaf@localhost
       The authenticity of host '[localhost]:8101 ([127.0.0.1]:8101)' can't be established.
@@ -164,7 +164,7 @@
 
 .. code-block::
 
-    $ kubectl -n tost exec -it onos-tost-onos-classic-0 -- bash apache-karaf-4.2.9/bin/client
+    $ kubectl -n sdfabric exec -it onos-tost-onos-classic-0 -- bash apache-karaf-4.2.9/bin/client
       Welcome to Open Network Operating System (ONOS)!
            ____  _  ______  ____
           / __ \/ |/ / __ \/ __/
@@ -199,6 +199,11 @@
 to the ONOS state by issuing specific CLI commands. We report in the section `Frequently Used Commands`_ few commands we frequently use
 when troubleshooting SD-Fabric.
 
+Pipeline Walk-through
+^^^^^^^^^^^^^^^^^^^^^
+.. note::
+  More information of Pipeline Walk-through is coming soon
+
 onos-diagnostics
 ^^^^^^^^^^^^^^^^
 
@@ -216,7 +221,52 @@
 - **Diagnostics**.
 
 We have built a tool `onos-diagnostics-k8s <https://wiki.onosproject.org/display/ONOS/ONOS+Remote+Admin+Tools>`_
-to help you easily collect and package ONOS diagnostics.
+to help you easily collect and package ONOS diagnostics. The tool collects various information from the running
+ONOS cluster and packages it into one, easy-to-share archive file. This tool is distributed as part of the ONOS
+software itself (under bin directory), but is also available as part of a small archive of remote tools to administer
+an ONOS cluster (`onos-admin-\*.tar.gz`).
+
+Alternatively, it is possible to use ``onos-diagnostics-k8s`` in Kubernetes enabled environments. The tool will produce
+the same results of onos-diagnostics and relies only on ``kubectl`` commands. The tool need to know the name of
+the namespace and this can be provided through the option ``-s``. Then, you have to provide the names of the target
+pods. To avoid having to specify these names as part of the command, you can export the ``ONOS_PODS`` environment
+variable. Here’s an example of how to set the variable:
+
+.. code-block::
+
+    $ export ONOS_PODS="onos-0 onos-1 onos-2"
+
+The tool needs to know the Karaf home (path from the mount point). To avoid having to specify this path as part
+of the command, you can export the ``KARAF_HOME`` environment variable:
+
+.. code-block::
+
+    $ export KARAF_HOME="apache-karaf-4.2.9"
+
+Once done, the ``onos-diagnostics-k8s`` tool can be run as follows:
+
+.. code-block::
+
+    $ onos-diagnostics-k8s -s sdfabric
+
+There is the option ``-n`` that allows for naming the resulting archive file for differentiation between different
+cluster instances, e.g.
+
+.. code-block::
+
+    # This will produce archive file /tmp/delta-pod-diags.tar.gz
+    $ onos-diagnostics-k8s -s sdfabric -n delta-pod
+
+By default ``onos-diagnostics-k8s`` will use ``ONOS_PROFILE`` to collect the diagnostics, you can tailor the behavior of the
+command to your needs by specifying a different `profile <https://github.com/opennetworkinglab/onos/blob/master/tools/package/runtime/bin/onos-diagnostics-profile>`_.
+For SD-Fabric we suggest to use ``TRELLIS_PROFILE``. The resulting `/tmp/\*-diags.tar.gz` file will contain all
+relevant information about the ONOS cluster.
+
+The following is an example of a complete ``onos-diagnostics-k8s`` command:
+
+.. code-block::
+
+    $ DIAGS_PROFILE=TRELLIS_PROFILE onos-diagnostics-k8s -k apache-karaf-4.2.9 -s sdfabric onos-tost-onos-classic-0 onos-tost-onos-classic-1 onos-tost-onos-classic-2
 
 UP4 Troubleshooting
 -------------------
@@ -258,7 +308,7 @@
 ^^^^
 To execute following ONOS CLI commands,
 
-- Create K8s port forwarding by `kubectl -n tost port-forward onos-tost-onos-classic-0 8101`
+- Create K8s port forwarding by `kubectl -n sdfabric port-forward onos-tost-onos-classic-0 8101`
 - Login to ONOS CLI by `ssh -p 8101 karaf@localhost`. Default password is `karaf`
 
 ONOS basics