| .. SPDX-FileCopyrightText: 2021 Open Networking Foundation <info@opennetworking.org> |
| .. SPDX-License-Identifier: Apache-2.0 |
| |
| .. _troubleshooting_guide: |
| |
| Troubleshooting Guide |
| ===================== |
| |
| In this section we are going to provide hints and useful commands to help you troubleshoot traffic-related problems |
| or k8s related issues. It is important to remember that these two types of issues are highly related as both |
| control plane software and data plane software are containerized and deployed as Kubernetes services in SD-Fabric. |
| Please refer to :ref:`architecture_design` for further details. |
| |
| K8s troubleshooting |
| ------------------- |
| |
| We assume that the tool ``kubectl`` have been install already on your local machine. |
| First step is to setup the proper ``kubeconfig`` file to access the k8s cluster you want to troubleshoot: |
| |
| .. code-block:: |
| |
| $ export KUBECONFIG=~/kubeconfig/dev-sdfabric-menlo |
| $ kubectl config use-context dev-sdfabric-menlo |
| Switched to context "dev-sdfabric-menlo". |
| |
| You can get the list of the k8s namespaces using ``kubectl get`` command: |
| |
| .. code-block:: |
| |
| $ kubectl get namespaces |
| ... |
| kube-node-lease Active 68d |
| kube-public Active 68d |
| kube-system Active 68d |
| security-scan Active 68d |
| sdfabric Active 26h |
| |
| Let's assume that SD-Fabric resources are deployed under the namespace ``sdfabric``, so make sure that the ``sdfabric`` |
| namespace has been properly created (additionally other namespaces could be created - please check your overarching chart). |
| |
| If the deployment is not successful, |
| a first check is to make sure there are enough available nodes in the target cluster. |
| You can check the available nodes through ``kubectl get nodes`` command: |
| |
| .. code-block:: |
| |
| $ kubectl get nodes -o wide |
| NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME |
| compute1 Ready controlplane,etcd,worker 39d v1.18.8 10.76.28.74 <none> Ubuntu 18.04.6 LTS 5.4.0-73-generic docker://20.10.9 |
| compute2 Ready controlplane,etcd,worker 39d v1.18.8 10.76.28.72 <none> Ubuntu 18.04.5 LTS 5.4.0-73-generic docker://19.3.15 |
| compute3 Ready controlplane,etcd,worker 39d v1.18.8 10.76.28.68 <none> Ubuntu 18.04.5 LTS 5.4.0-73-generic docker://19.3.15 |
| leaf1 Ready worker 39d v1.18.8 10.76.28.70 <none> Debian GNU/Linux 9 (stretch) 4.14.49-OpenNetworkLinux docker://19.3.15 |
| leaf2 Ready worker 39d v1.18.8 10.76.28.71 <none> Debian GNU/Linux 9 (stretch) 4.14.49-OpenNetworkLinux docker://19.3.15 |
| |
| You should have at least `3+N` available nodes, where N depends on the deployed network topology. Please note that ONOS |
| cannot be scheduled on the network devices (these are special worker nodes), and different ONOS cannot share the same worker |
| node (the same applies for Atomix). |
| |
| At least you should have some basic containers that are present in each deployment. |
| You can get the list of the pods by using ``kubectl get pods -n sdfabric``: |
| |
| .. code-block:: |
| |
| $ kubectl get pods -n sdfabric -o wide |
| NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES |
| onos-tost-atomix-0 1/1 Running 0 6h31m 10.72.106.161 compute3 <none> <none> |
| onos-tost-atomix-1 1/1 Running 0 6h31m 10.72.111.229 compute1 <none> <none> |
| onos-tost-atomix-2 1/1 Running 0 6h31m 10.72.75.254 compute2 <none> <none> |
| onos-tost-onos-classic-0 1/1 Running 0 98m 10.72.106.133 compute3 <none> <none> |
| onos-tost-onos-classic-1 1/1 Running 0 6h31m 10.72.111.207 compute1 <none> <none> |
| onos-tost-onos-classic-2 1/1 Running 0 6h31m 10.72.75.247 compute2 <none> <none> |
| onos-tost-onos-classic-onos-config-loader-ddc9d68bb-lq97t 1/1 Running 0 6h19m 10.72.106.190 compute3 <none> <none> |
| stratum-bwlvh 1/1 Running 0 6h31m 10.76.28.70 leaf1 <none> <none> |
| stratum-gh842 1/1 Running 0 6h31m 10.76.28.71 leaf2 <none> <none> |
| |
| 3 Atomix nodes and 3 ONOS nodes are needed for HA. `onos-config-loader` is equally important, because without ONOS |
| cannot be properly configured. The number of Stratum pods depend on the deployed topology. If the status of the pods |
| is not `Running` you can check the events published by k8s components to have a first idea of what is happening: |
| |
| .. code-block:: |
| |
| $ kubectl get events -n sdfabric --sort-by='.lastTimestamp' |
| LAST SEEN TYPE REASON OBJECT MESSAGE |
| 12m Normal Scheduled pod/telegraf-75b959574d-sl8qb Successfully assigned tost/telegraf-75b959574d-sl8qb to compute3 |
| 12m Normal SuccessfulCreate replicaset/telegraf-75b959574d Created pod: telegraf-75b959574d-sl8qb |
| 12m Normal ScalingReplicaSet deployment/telegraf Scaled up replica set telegraf-75b959574d to 1 |
| 12m Normal Pulled pod/telegraf-75b959574d-sl8qb Container image "telegraf:1.17" already present on machine |
| 12m Normal AddedInterface pod/telegraf-75b959574d-sl8qb Add eth0 [10.72.106.153/32] |
| 12m Normal Started pod/telegraf-75b959574d-sl8qb Started container telegraf |
| 12m Normal Created pod/telegraf-75b959574d-sl8qb Created container telegraf |
| ... |
| |
| The option ``--sort-by='.lastTimestamp'`` is typically used to get the events sorted by time. The previous command |
| will report all the events happened in the ``sdfabric`` namespace, if you want to have more insights on a specific |
| pod, it is possible to use the command ``kubectl describe pods``: |
| |
| .. code-block:: |
| |
| $ kubectl describe pods -n sdfabric onos-tost-onos-classic-0 |
| Name: onos-tost-onos-classic-0 |
| Namespace: sdfabric |
| Priority: 0 |
| Node: compute3/10.76.28.68 |
| Start Time: Mon, 11 Oct 2021 10:35:43 +0200 |
| ... |
| Events: |
| Type Reason Age From Message |
| ... |
| {"message":"pending"} |
| org.onosproject.segmentrouting is not yet ready |
| |
| The ``Events`` section provides typically useful information about the issues the pod is facing. |
| |
| Both ONOS and Atomix define readiness probes which will make sure that the pods are ready before any configuration |
| will take place. As consequence of this, if the probes fail for a given pod you will notice in the output of the command |
| ``kubectl get pods``` near its name ``0/1`` under the column ``READY``. We report in `ONOS pod not ready (1)`_ and |
| `ONOS pod not ready (2)`_ two scenarios frequently faced by the SD-Fabric developers. |
| |
| Logs of the SD-Fabric pods can be accessed by using ``kubectl logs`` command |
| |
| .. code-block:: |
| |
| $ kubectl -n sdfabric logs onos-tost-onos-classic-0 |
| 2021-10-12 04:46:17,955 INFO [EventAdminConfigurationNotifier] Sending Event Admin notification (configuration successful) to org/ops4j/pax/logging/Configuration |
| ... |
| 2021-10-12 04:46:18,991 INFO [FeaturesServiceImpl] Changes to perform: |
| 2021-10-12 04:46:18,991 INFO [FeaturesServiceImpl] Region: root |
| 2021-10-12 04:46:18,991 INFO [FeaturesServiceImpl] Bundles to install: |
| |
| |
| ONOS Troubleshooting |
| -------------------- |
| |
| You can get the ONOS CLI by establishing SSH connection to the port ``8101`` (default password is `karaf`): |
| |
| .. code-block:: |
| |
| $ 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. |
| RSA key fingerprint is SHA256:Mlaax9tHmIR6WwK0B3okC1O4mpAuoXjI7Z5+KKelxOo. |
| Are you sure you want to continue connecting (yes/no)? yes |
| Warning: Permanently added '[localhost]:8101' (RSA) to the list of known hosts. |
| Password authentication |
| Password: |
| Welcome to Open Network Operating System (ONOS)! |
| ____ _ ______ ____ |
| / __ \/ |/ / __ \/ __/ |
| / /_/ / / /_/ /\ \ |
| \____/_/|_/\____/___/ |
| |
| Documentation: wiki.onosproject.org |
| Tutorials: tutorials.onosproject.org |
| Mailing lists: lists.onosproject.org |
| |
| Come help out! Find out how at: contribute.onosproject.org |
| |
| Hit '<tab>' for a list of available commands |
| and '[cmd] --help' for help on a specific command. |
| Hit '<ctrl-d>' or type 'logout' to exit ONOS session. |
| |
| karaf@root > |
| |
| Alternatively, if this is not possible to establish an ssh connection with the ONOS pods, |
| it is possible to use ``kubectl exec`` command on the target pod: |
| |
| .. code-block:: |
| |
| $ kubectl -n sdfabric exec -it onos-tost-onos-classic-0 -- bash apache-karaf-4.2.14/bin/client |
| Welcome to Open Network Operating System (ONOS)! |
| ____ _ ______ ____ |
| / __ \/ |/ / __ \/ __/ |
| / /_/ / / /_/ /\ \ |
| \____/_/|_/\____/___/ |
| |
| Documentation: wiki.onosproject.org |
| Tutorials: tutorials.onosproject.org |
| Mailing lists: lists.onosproject.org |
| |
| Come help out! Find out how at: contribute.onosproject.org |
| |
| Hit '<tab>' for a list of available commands |
| and '[cmd] --help' for help on a specific command. |
| Hit '<ctrl-d>' or type 'logout' to exit ONOS session. |
| |
| karaf@root |
| |
| You can attach to the ONOS logs by using the ``log:tail`` command: |
| |
| .. code-block:: |
| |
| $ karaf@root > log:tail |
| 20:19:40.188 DEBUG [DefaultRoutingHandler] device:spine1 -> device:leaf1 |
| 20:19:40.188 DEBUG [DefaultRoutingHandler] device:spine2 -> device:leaf1 |
| 20:19:40.188 DEBUG [DefaultRoutingHandler] device:leaf1 -> device:spine1 |
| 20:19:40.188 DEBUG [DefaultRoutingHandler] device:leaf2 -> device:spine1 |
| |
| The command will display continuously the log entries - this is useful for a live debugging session. |
| Complete ONOS logs can be accessed by using ``kubectl logs`` command as explained in the previous section. |
| If anything can be figured out from the logs, you can access |
| 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 |
| ^^^^^^^^^^^^^^^^ |
| |
| In the case where you can't figure out what is going wrong, you can seek help on SD-Fabric developer mailing list |
| ``sdfabric-dev@opennetworking.org`` or you can reach out on the ``sdfabric-dev`` Slack channel. There are a few |
| things we would like you to attach: |
| |
| - **Issue description** |
| |
| - **Environment description**, such as SD-Fabric version, switch model and SDE version |
| version |
| |
| - **Steps of reproduction**, as detail as possible |
| |
| - **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. 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.14" |
| |
| 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.14 -s sdfabric onos-tost-onos-classic-0 onos-tost-onos-classic-1 onos-tost-onos-classic-2 |
| |
| UP4 Troubleshooting |
| ------------------- |
| |
| .. note:: |
| More information of UP4 troubleshoot is coming soon |
| |
| Common Issues |
| ------------- |
| |
| .. note:: |
| Here is a list of common issues. |
| More details of each case are coming soon |
| |
| ImagePullBackOff |
| ^^^^^^^^^^^^^^^^ |
| |
| ONOS pod not ready (1) |
| ^^^^^^^^^^^^^^^^^^^^^^ |
| |
| ONOS pod not ready (2) |
| ^^^^^^^^^^^^^^^^^^^^^^ |
| |
| ONOS pods not configured |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Packet-In not working |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| Device offline |
| ^^^^^^^^^^^^^^ |
| |
| Frequently Used Commands |
| ------------------------ |
| |
| In this subsection, we are going to introduce a few commands we frequently used when troubleshooting SD-Fabric. |
| |
| ONOS |
| ^^^^ |
| To execute following ONOS CLI commands, |
| |
| - 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 |
| """"""""""" |
| - ``flows``: List flow tables. `-s` for simplified output. |
| - ``groups``: List group tables. `-s` for simplified output. |
| - ``devices``: List device information. `-s` for simplified output. |
| - ``ports``: List port information. `-e` to list enabled ports only. |
| - ``links``: List discovered links |
| - ``hosts``: List discovered hosts. `-s` for simplified output. |
| - ``netcfg``: List network configuration |
| - ``interfaces``: List interface configuration |
| |
| trellis-control |
| """"""""""""""" |
| - ``sr-pr-list``: List current recovery phase of each device |
| - ``sr-device-subnets``: List device-subnet mapping |
| |
| fabric-tna |
| """""""""" |
| - ``slices``: List network slices |
| - ``tcs``: List traffic classes of given slice |
| |
| up4 |
| """ |
| - ``read-entities -a``: Print UPF entities installed in the UPF dataplane. |
| More options are available. See ``read-entities --help`` |
| |
| |
| Stratum |
| ^^^^^^^ |
| To execute following BF Shell commands, |
| |
| - Login to Stratum switch by `ssh root@<switch_ip>`. Default password is `onl` |
| - Attach to Stratum docker container by `docker attach \`docker ps | grep stratum-bfrt | awk \'{print $1}\'\`` |
| |
| - Hit `enter` for the prompt |
| - Use `<Ctrl-P><Ctrl-Q>` to exit the container. Do not use `<Ctrl-C>` since it will terminate the process. |
| |
| BF Shell |
| """""""" |
| - ``pm.show``: List port configurations. `-a` to list all ports. |