Add Traceflow User Guide

Add document to guide users how to
use Traceflow via Antrea UI and Kubectl.

Related: #901

docs/octant-plugin-installation.md

@@ -10,13 +10,13 @@ There are two ways to deploy Octant and antrea-octant-plugin.
 
 
 ### Prerequisites
-antrea-octant-plugin depends on the Antrea monitoring CRDs, AntreaControllerInfo and AntreaAgentInfo.
+antrea-octant-plugin depends on the Antrea monitoring CRDs (AntreaControllerInfo and AntreaAgentInfo) and Traceflow CRD (Traceflow).
 
-To run Octant together with antrea-octant-plugin, please make sure you have these two CRDs defined in you K8s cluster.
+To run Octant together with antrea-octant-plugin, please make sure you have these CRDs defined in you K8s cluster.
 
-If Antrea is deployed before antrea-octant-plugin starts by using the standard deployment yaml, Antrea monitoring
+If Antrea is deployed before antrea-octant-plugin starts by using the standard deployment yaml, these
 CRDs should already be added. If not, please refer to [antrea.yaml](/build/yamls/antrea.yml) to
-create these two CRDs first.
+create these CRDs first.
 
 ### Deploy Octant and antrea-octant-plugin as a Pod
 
@@ -55,11 +55,16 @@ downloaded which may be due to network issues, you can run command `make
 octant-antrea-ubuntu` to build the image locally. If it is the case, you need
 to make sure that the image exists on all the K8s Nodes since the antrea-octant
 Pod may run on any of them.
-2. If the Pod is running without any explicit issue but you can not access the
+2. In Antrea v0.8.2, the Traceflow UI is a separate Octant plugin called antrea-traceflow-plugin,
+but it has been merged into antrea-octant-plugin on the master branch since then.
+To get the latest version of Traceflow UI, please build image
+antrea/octant-antrea-ubuntu via command `make octant-antrea-ubuntu` and use the image antrea/octant-antrea-ubuntu:latest
+for deploying UI as a Pod.
+3. If the Pod is running without any explicit issue but you can not access the
 URL, please take a further look at the network configurations in your
 environment. It may be due to the network policies or other security rules
 configured on your hosts.
-3. To deploy a released version of the plugin, you can download
+4. To deploy a released version of the plugin, you can download
 `https://github.com/vmware-tanzu/antrea/releases/download/<TAG>/antrea-octant.yml`,
 where `<TAG>` (e.g. `v0.3.0`) is the desired version (should match the version
 of Antrea you are using). After making the necessary edits, you can apply the
@@ -97,7 +102,7 @@ based on your environment and move the binary to OCTANT_PLUGIN_PATH.
     For example, you can get antrea-octant-plugin-linux-x86_64 if it matches your operating system and architecture.
 
     ```bash
-    wget -O antrea-octant-plugin https://github.com/vmware-tanzu/antrea/releases/download/v0.8.1/antrea-octant-plugin-linux-x86_64
+    wget -O antrea-octant-plugin https://github.com/vmware-tanzu/antrea/releases/download/<TAG>/antrea-octant-plugin-linux-x86_64
     # Make sure antrea-octant-plugin is executable, otherwise Octant cannot find it.
     chmod a+x antrea-octant-plugin
     # If you did not change OCTANT_PLUGIN_PATH, the default folder should be $HOME/.config/octant/plugins.
@@ -114,15 +119,12 @@ based on your environment and move the binary to OCTANT_PLUGIN_PATH.
 Now, you are supposed to see Octant is running together with antrea-octant-plugin via URL http://(IP or $HOSTNAME):80.
 
 Note:
-1. In Antrea v0.8.1, the Traceflow UI is a separate Octant plugin called antrea-traceflow-plugin.
-Starting with v0.9.0, the Traceflow UI will be merged into antrea-octant-plugin. When deploying Octant as a Pod using
-image antrea/octant-antrea-ubuntu:v0.8.1, you already have access to the alpha version of the Traceflow UI.
-2. If you deploy Octant and the Antrea UI as a process, you cannot access the Traceflow UI for now when following the
+1.  If you deploy Octant and the Antrea UI as a process, you cannot access the Traceflow UI for now when following the
 steps listed above (at least until the v0.9.0 release). However, you can still build the binary yourself with
 the command below, with the remaining steps being almost the same as the ones above.
 
     ```bash
     # You will find the compliled binary under folder antrea/plugins/octant/bin.
     cd plugins/octant
-    make antrea-traceflow-plugin
+    make antrea-octant-plugin
     ```

docs/traceflow-guide.md

@@ -0,0 +1,103 @@
+# Traceflow User Guide
+
+Antrea supports using Traceflow for network diagnosis: it generates tracing requests for traffic going through
+Antrea-managed Pod network. Creating a new Traceflow CRD triggers the Traceflow module to inject packet into OVS,
+provide various observation points along the packet's path and populate these observations into status of Traceflow CRD.
+Users can start a new trace simply from either Kubectl or Antrea-Octant-Plugin and view Traceflow result via CRD or UI graph.
+We will also provide corresponding Antctl to start a new trace in the near future.
+
+## Table of Contents
+
+- [Prerequisites](#Prerequisites)
+- [Start a New Trace](#Start-a-New-Trace)
+  - [Using kubectl and YAML file](#using-kubectl-and-YAML-file)
+  - [Using Octant with antrea-octant-plugin](#Using-Octant-with-antrea-octant-plugin)
+- [View Traceflow Result and Graph](#View-Traceflow-Result-and-Graph)
+- [View Traceflow CRDs](#View-Traceflow-CRDs)
+
+## Prerequisites
+You need to switch on traceflow from featureGates defined in antrea.yml for both Controller and Agent.
+```yaml
+  antrea-controller.conf: |
+    featureGates:
+    # Enable traceflow which provides packet tracing feature to diagnose network issue.
+      Traceflow: true
+  antrea-agent.conf: |
+    featureGates:
+    # Enable traceflow which provides packet tracing feature to diagnose network issue.
+      Traceflow: true
+```
+For antrea-octant-plugin installation, please refer to [antrea-octant-installation](/docs/octant-plugin-installation.md).
+
+## Start a New Trace
+You can choose to use either Kubectl together with YAML file or Octant UI to start a new trace.
+If you use Kubectl to start a new trace, we now support traceflow from Pod to either Pod or IP and
+you can also mark the protocol(TCP/UDP/ICMP) and desired ports of the trace. 
+If you use UI to start a new trace, we currently only supports destination to be Pod, but will support
+destination to be IP or Service soon.
+
+### Using kubectl and YAML file
+You can start a new trace by creating Traceflow CRD via Kubectl and a YAML file which contains the essential
+configuration of Traceflow CRD. An example YAML file of Traceflow CRD might look like this:
+```yaml
+apiVersion: ops.antrea.tanzu.vmware.com/v1alpha1
+kind: Traceflow
+metadata:
+  name: tf-test
+spec:
+  source:
+    namespace: default
+    pod: tcp-sts-0
+  destination:
+    namespace: default
+    pod: tcp-sts-2
+#   ip: IP can also be marked as destination, but namespace/pod and ip are mutually exclusive.
+  packet:
+    ipHeader:
+      protocol: 6 # Protocol here can be 6 (TCP), 17 (UDP) or 1 (ICMP), default value is 1 (ICMP)
+    transportHeader:
+      tcp:
+        srcPort: 10000 # Source port needs to be set when Protocol is TCP/UDP.
+        dstPort: 80 # Destination port needs to be set when Protocol is TCP/UDP.
+```
+The CRD above starts a new trace from port 10000 of source Pod named tcp-sts-0 to port 80
+of destination Pod named tcp-sts-2 using TCP protocol.
+
+### Using Octant with antrea-octant-plugin
+
+<img src="https://s3-us-west-2.amazonaws.com/downloads.antrea.io/static/tf_create.png" width="600" alt="Start a New Trace">
+
+From Octant dashboard, you need to click on left navigation bar named "Antrea" and then
+choose category named "Traceflow Info" to lead you to the Traceflow UI displayed on the right side.
+
+Now, you can start a new trace by clicking on the button named "Start New Trace" and submit the form with trace details.
+It helps you create a Traceflow CRD and generate a corresponding Traceflow Graph.
+
+## View Traceflow Result and Graph
+
+You can always view Traceflow result directly via Traceflow CRD status and see if the packet is successfully delivered
+or somehow dropped by certain component. Antrea also provides a more user-friendly way by showing the Traceflow result via a
+trace graph on UI.
+
+<img src="https://s3-us-west-2.amazonaws.com/downloads.antrea.io/static/tf_graph_success.png" width="600" alt="Show Successful Trace">
+
+From the graph above, we can see the inter-node traffic between two Pods has been successfully delivered.
+Sometimes the traffic may not be successfully delivered and we can always easily identify where the traffic is dropped
+via a trace graph like below.
+
+<img src="https://s3-us-west-2.amazonaws.com/downloads.antrea.io/static/tf_graph_failure.png" width="600" alt="Show Failing Trace">
+
+You can also generate a historical trace graph by providing a specific Traceflow CRD name (assuming the CRD has not been deleted yet)
+as shown below.
+
+<img src="https://s3-us-west-2.amazonaws.com/downloads.antrea.io/static/tf_historical_graph.png" width="600" alt="Generate Historical Trace">
+
+## View Traceflow CRDs
+
+<img src="https://s3-us-west-2.amazonaws.com/downloads.antrea.io/static/tf_overview.png" width="600" alt="Antrea Overview">
+
+As shown above, you can check the existing Traceflow CRDs in the "Traceflow Info" table of the Antrea Overview web page
+in the Octant UI. You can generate a trace graph for any of these CRDs, as explained in the previous section.
+Also, you can view all the traceflow CRDs from the Tracflow page by clicking the right tab named "Traceflow Info" like below.
+
+<img src="https://s3-us-west-2.amazonaws.com/downloads.antrea.io/static/tf_table.png" width="600" alt="Traceflow CRDs">