Revise README and user documents

Add Theia overview, getting-started, contributting, community, and
license information to README.md.
Revise the Theia introduction, and add more information about Theia
features and usage in network-flow-visibility.md and the Getting Started
section.
Rename theia.md to theia-cli.md.

Signed-off-by: Jianjun Shen <shenj@vmware.com>

README.md

@@ -1,10 +1,45 @@
 # Theia
 
-Theia contains Network Flow Visibility functions which are exacted from the
-[Antrea main repo](https://github.com/antrea-io/antrea). While flow exporter and
-flow aggregator are kept in the Antrea repo, other flow visibility modules, such
-as ClickHouse and Grafana related ones, will be moved to this new repo.
-
-During the code migration period, we will still keep related functions available
-and stable in the Antrea repo, and the functions in this new repo won't be ready
-until we announce the migration is completed.
+Theia is a network observability and analytics platform for Kubernetes. It is
+built on top of [Antrea](https://github.com/antrea-io/antrea), and consumes
+[network flows exported by Antrea](https://github.com/antrea-io/antrea/blob/main/docs/network-flow-visibility.md)
+to provide fine-grained visibility into the network communications in a
+Kubernetes cluster.
+
+## Getting Started
+
+Getting started with Theia is simple. You can follow the [Getting Started](docs/network-flow-visibility.md#getting-started)
+guide to install Theia and start rocking!
+
+Theia supports network flow visualization and monitoring with Grafana. Check the
+[Grafana Flow Collector](docs/network-flow-visibility.md#grafana-flow-collector)
+document to learn more.
+
+Based on the collected network flow information, Theia can recommend appropriate
+NetworkPolicy configuration to secure Kubernetes network and applications.
+Please refer to the [NetworkPolicy Recommendation](docs/networkpolicy-recommendation.md)
+user guide to learn more.
+
+## Contributing
+
+The Antrea community welcomes new contributors. We are waiting for your PRs!
+
+* Before contributing, please get familiar with our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+* Check out the Antrea [Contributor Guide](CONTRIBUTING.md) for information
+about setting up your development environment and our contribution workflow.
+* Learn about Antrea's [Architecture and Design](https://github.com/antrea-io/antrea/blob/main/docs/design/architecture.md).
+Your feedback is more than welcome!
+* Check out [Open Issues](https://github.com/antrea-io/theia/issues).
+* Join the Antrea [community](#community) and ask us any question you may have.
+
+## Community
+
+Please refer to the [Antrea community](https://github.com/antrea-io/antrea/blob/main/README.md#community)
+information.
+
+## License
+
+Antrea is licensed under the [Apache License, version 2.0](LICENSE)
+
+[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fantrea-io%2Fantrea.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fantrea-io%2Fantrea?ref=badge_large)

docs/network-flow-visibility.md

@@ -1,4 +1,4 @@
-# Theia: Network Flow Visibility for Antrea
+# Theia - Network Observability and Analytics for Antrea
 
 ## Table of Contents
 
@@ -7,7 +7,9 @@
 - [Getting Started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Theia Installation](#theia-installation)
-  - [Additional information](#additional-information)
+  - [Grafana Dashboard Access](#grafana-dashboard-access)
+  - [NetworkPolicy Recommendation](#networkpolicy-recommendation)
+  - [Additional Information](#additional-information)
 - [Grafana Flow Collector](#grafana-flow-collector)
   - [Purpose](#purpose)
   - [About Grafana and ClickHouse](#about-grafana-and-clickhouse)
@@ -23,29 +25,29 @@
         - [Service Customization](#service-customization-1)
         - [Performance Configuration](#performance-configuration)
       - [Persistent Volumes](#persistent-volumes)
-  - [Pre-built Dashboards](#pre-built-dashboards)
+  - [Pre-built Grafana Dashboards](#pre-built-grafana-dashboards)
     - [Flow Records Dashboard](#flow-records-dashboard)
     - [Pod-to-Pod Flows Dashboard](#pod-to-pod-flows-dashboard)
     - [Pod-to-External Flows Dashboard](#pod-to-external-flows-dashboard)
     - [Pod-to-Service Flows Dashboard](#pod-to-service-flows-dashboard)
     - [Node-to-Node Flows Dashboard](#node-to-node-flows-dashboard)
     - [Network-Policy Flows Dashboard](#network-policy-flows-dashboard)
-  - [Dashboards Customization](#dashboards-customization)
+  - [Dashboard Customization](#dashboard-customization)
 <!-- /toc -->
 
 ## Overview
 
-[Antrea](https://github.com/antrea-io/antrea/blob/main/docs/design/architecture.md)
-is a Kubernetes network plugin that provides network connectivity and security
-features for Pod workloads. Considering the scale and dynamism of Kubernetes
-workloads in a cluster, Network Flow Visibility helps in the management and
-configuration of Kubernetes resources such as Network Policy, Services, Pods
-etc., and thereby provides opportunities to enhance the performance and security
-aspects of Pod workloads.
+Theia is a network observability and analytics platform for Kubernetes, that is
+built on top of [Antrea](https://github.com/antrea-io/antrea). Theia consumes
+[network flows exported by Antrea](https://github.com/antrea-io/antrea/blob/main/docs/network-flow-visibility.md)
+to provide fine-grained visibility into the network communications in a
+Kubernetes cluster.
 
-For visualizing the network flows, Antrea monitors the flows in Linux conntrack
-module. These flows are converted to flow records, and then flow records are post-processed
-before they are sent to the configured external flow collector.
+Theia supports network flow visualization and monitoring with Grafana, and can
+recommend appropriate NetworkPolicy configuration to secure Kubernetes network
+and applications. This guide describes how to install and get started with
+Theia, as well as the Grafana Flow Collector and network flow visualization
+with Theia.
 
 ## Getting Started
 
@@ -64,7 +66,7 @@ manifest, in the following way:
 
 ### Theia Installation
 
-To enable both Grafana Flow Collector and
+To enable both [Grafana Flow Collector](#grafana-flow-collector) and
 [NetworkPolicy Recommendation](networkpolicy-recommendation.md), please install
 Theia and Flow Aggregator by runnning the following commands:
 
@@ -83,13 +85,38 @@ helm install flow-aggregator theia/build/charts/flow-aggregator --set clickHouse
 helm install theia theia/build/charts/theia -n flow-visibility --create-namespace
 ```
 
-### Additional information
+### Grafana Dashboard Access
+
+After the installation, you can run the following command to get the Grafana
+Service address:
+
+```bash
+NODE_NAME=$(kubectl get pod -l app=grafana -n flow-visibility -o jsonpath='{.items[0].spec.nodeName}')
+NODE_IP=$(kubectl get nodes ${NODE_NAME} -o jsonpath='{.status.addresses[0].address}')
+GRAFANA_NODEPORT=$(kubectl get svc grafana -n flow-visibility -o jsonpath='{.spec.ports[*].nodePort}')
+echo "=== Grafana Service is listening on ${NODE_IP}:${GRAFANA_NODEPORT} ==="
+```
+
+You can now access Grafana in your browser at: `http://[NodeIP]:[NodePort]`,
+and log in with username: `admin` and password: `admin`. You can view the
+network flows in the Kubernetes cluster on the [Theia dashboards](#pre-built-grafana-dashboards).
+
+### NetworkPolicy Recommendation
+
+Please follow the instructions in the [NetworkPolicy Recommendation](networkpolicy-recommendation.md)
+user guide.
+
+### Additional Information
 
 Refer to Antrea documentation to learn more about
 [Flow Exporter](https://github.com/antrea-io/antrea/blob/main/docs/network-flow-visibility.md#flow-exporter),
 [Flow Aggregator](https://github.com/antrea-io/antrea/blob/main/docs/network-flow-visibility.md#flow-aggregator)
 and their advanced configurations.
 
+For more information about Grafana Flow Collector installation and
+customization, please refer to Grafana Flow Collector [Deployment Steps](#deployment-steps),
+and [Configuration](#configuration).
+
 ## Grafana Flow Collector
 
 ### Purpose
@@ -112,6 +139,10 @@ ClickHouse as the data storage, and use Grafana as the data visualization and mo
 
 ### Deployment Steps
 
+This section talks about detailed steps to deploy the Grafana Flow Collector
+using Helm charts or YAML manifests. For quick steps of installing Theia
+including the Grafana Flow Collector, please refer to [Getting Started](#getting-started).
+
 We support deploying the Grafana Flow Collector with Helm. Here is the
 [Helm chart](../build/charts/theia/) for the Grafana Flow Collector. Please follow
 the instructions from the Helm chart [README](../build/charts/theia/README.md)
@@ -217,6 +248,10 @@ kubectl delete -f https://raw.githubusercontent.com/antrea-io/theia/main/build/c
 
 ### Configuration
 
+So far, we went through Grafana Flow Collector deployment with the default
+configuration. The Grafana Flow Collector also exposes a few configuration
+parameters for you to customize the deployment. Read this section to learn more.
+
 #### With Helm
 
 If you install the Grafana Flow Collector using the Helm command, please refer
@@ -594,9 +629,9 @@ should be set to your storage size.
       name: clickhouse-storage-volume
     ```
 
-### Pre-built Dashboards
+### Pre-built Grafana Dashboards
 
-The following dashboards are pre-built and are recommended for Antrea flow
+The following dashboards are pre-built and are recommended for Theia flow
 visualization. They can be found in the Home page of Grafana, by clicking
 the Magnifier button on the left menu bar.
 <img src="https://downloads.antrea.io/static/02152022/flow-visibility-grafana-intro-1.png" width="900" alt="Grafana Search Dashboards Guide">
@@ -728,7 +763,7 @@ Mouse out or click on the background will bring all the traffic back.
 
 <img src="https://downloads.antrea.io/static/05232022/flow-visibility-np-3.png" width="900" alt="Network-Policy Flows Dashboard">
 
-### Dashboards Customization
+### Dashboard Customization
 
 If you would like to make any changes to any of the pre-built dashboards, or build
 a new dashboard, please follow this [doc](https://grafana.com/docs/grafana/latest/dashboards/)

docs/networkpolicy-recommendation.md

@@ -34,7 +34,7 @@ install Antrea Flow Aggregator and Theia.
 Users can leverage Theia's NetworkPolicy Recommendation feature through `theia`
 CLI. `theia` is the command-line tool which provides access to Theia network
 flow visibility capabilities. To get more information about `theia`, please
-refer to this [doc](theia.md).
+refer to its [user guide](theia-cli.md).
 
 There are 3 `theia` commands for the NetworkPolicy Recommendation feature: