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/dict.txt b/dict.txt
index 3b41902..57bcd18 100644
--- a/dict.txt
+++ b/dict.txt
@@ -86,6 +86,7 @@
ip
jitter
json
+Karaf
keepalives
lifecycle
linecard
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