Revise README, Getting Started, and flow visibility documents #45

jianjuns · 2022-06-12T05:22:17Z

Add Theia overview, getting-started, contributing, community, and
license information to README.md.
Move Getting Started to a separate document, and add more information
about Theia features and usage.
section.
Rename theia.md to theia-cli.md.

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

jianjuns · 2022-06-12T05:24:59Z

README.md

-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


@salv-orlando : I believe you can write a better version. But could we start from the simple introduction?

I think we need to keep the readme simple, I think your intro is great.

I would just replace
"provide fine-grained visibility into the network communications in a Kubernetes cluster"

with

"provide fine-grained visibility into connections across pod and services in a Kubernetes cluster"

Unless you chose "network communications" for a specific reason

How about "provide fine-grained visibility into communications among Pods and Services in a Kubernetes cluster"? I feel people might think connections as TCP connections.

just propose "visibility on workload among Pods, Service and external network" as alternative.

ziyouw

Hi Jianjun,

Thanks for updating the docs! LGTM, I am just not sure about a few small parts.

ziyouw · 2022-06-13T05:03:06Z

README.md

+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


Right now, Theia only supports flow visibility and NP recommendation for a single cluster. Maybe we should highlight this before we can support more?

I feel no need to mention not implemented features in README (e.g. we can have a ROADMAP doc for that if we want). There are other K8s visibility solutions support a single cluster only too. Do not think multi-cluster support is a must.

I would not include "forward-looking" statements in the README files.
As @jianjuns mentioned, we can have them either in the roadmap doc, or maybe simply track them on Github!

ziyouw · 2022-06-13T05:06:10Z

docs/network-flow-visibility.md

-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


Not sure if "which is" is better than "that is" or we can split it as two simple sentences.

Sure. Let me think about how to rephrase.

heanlan

Thanks Jianjun for taking care of the doc.

In docs/network-flow-visibility.md L658, "the dashboards customization section for more", the link needs to be changed to #dashboard-customization

jianjuns · 2022-06-13T17:21:17Z

In docs/network-flow-visibility.md L658, "the dashboards customization section for more", the link needs to be changed to #dashboard-customization

Thanks! Fixed.

heanlan · 2022-06-13T17:26:58Z

README.md

+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).


Took a look at the workflow failure, it seems the CODE_OF_CONDUCT.md is not added? Or shall we pointing to the file in Antrea repo?

It will be added in #40

dreamtalen

Thanks Jianjun working on this.

dreamtalen · 2022-06-13T17:27:16Z

docs/network-flow-visibility.md

@@ -1,4 +1,4 @@
-# Theia: Network Flow Visibility for Antrea
+# Theia - Network Observability and Analytics for Antrea


Do we also need to change the title of this markdown file accordingly?

Sorry, what title you mean?

Oops, I was about to say is the 'filename' of this .md

Ah. I was thinking about a new name too, but failed to come up with a good one. Let me know if you have an idea.

Naming things is truly hard, I have some ideas for your reference:
observing-flows-with-theia.md
observing-and-analyzing-network-flows-with-theia.md
network-flow-observability-and-analytics.md

Yes, probably let us see if others have some ideas too and decide later. I feel the file name should not be too long.

Got inspired by Antrea doc directory arch. A wild idea came to me:

Can we split the "Grafana Flow Collector" whole section out to a separate file? parallel to networkpolicy-recommendation.md. So that for the current network-flow-visibility.md will only contains:

Overview
Getting Started
Prerequisites
Theia Installation
Features

Grafana Flow Collector

NetworkPolicy Recommendation

Additional Information

And we can name it by overview.md/getting-started.md etc, a shorter name. But it may requires a bigger change, not sure if we want to make it before this release.

@heanlan Yes, it makes sense to me. Originally I hoped to avoid bigger changes to catch v0.1.0. But sure, let me try revising as you suggested.

Made an update. Check.

README.md

docs/network-flow-visibility.md

yanjunz97

Thanks Jianjun for working on this!

yanjunz97 · 2022-06-13T17:36:06Z

docs/network-flow-visibility.md

@@ -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:


Not introduced by this PR, could you change the order "Theia and Flow Aggregator" to "Flow Aggregator and Theia". I forgot to change it when changing the installation order. And the same for Line 77. Thanks!

Sure. Changed.

yanjunz97 · 2022-06-13T17:38:16Z

docs/network-flow-visibility.md

-### Additional information
+### Grafana Dashboard Access
+
+After the installation, you can run the following command to get the Grafana


command -> commands?

yanjunz97 · 2022-06-13T17:40:19Z

docs/network-flow-visibility.md

+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)


[network [flows exported by Antrea] -> [network flows exported by Antrea]

docs/getting-started.md

dreamtalen · 2022-06-13T20:12:22Z

docs/network-flow-visibility.md

@@ -112,6 +61,11 @@ 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 the [Getting Started](getting-started.md)


Getting Started link needs to be updated in networkpolicy-recommendation.md L29 too.

Updated it.

heanlan

LGTM

yanjunz97 · 2022-06-13T21:15:55Z

docs/network-flow-visibility.md

@@ -23,72 +19,25 @@
        - [Service Customization](#service-customization-1)
        - [Performance Configuration](#performance-configuration)
      - [Persistent Volumes](#persistent-volumes)


Again not introduced by this PR, could you help put Persistent Volumes section under ClickHouse Configuration instead of parallel to it, as this section is about creating Persistent Volumes for ClickHouse. Thanks a lot!

salv-orlando · 2022-06-14T15:08:01Z

README.md

+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


I would not include "forward-looking" statements in the README files.
As @jianjuns mentioned, we can have them either in the roadmap doc, or maybe simply track them on Github!

salv-orlando · 2022-06-14T15:12:29Z

README.md

-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


I think we need to keep the readme simple, I think your intro is great.

I would just replace
"provide fine-grained visibility into the network communications in a Kubernetes cluster"

with

"provide fine-grained visibility into connections across pod and services in a Kubernetes cluster"

Unless you chose "network communications" for a specific reason

salv-orlando · 2022-06-14T15:17:18Z

README.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!


This is not about this PR, but we also need an arch doc for Theia to integrate Antrea's one.

salv-orlando · 2022-06-14T15:18:08Z

README.md

+
+## License
+
+Antrea is licensed under the [Apache License, version 2.0](LICENSE)


Mabe we should mention Theia here rather than Antrea - this is because the README refers to the specific repo, not the whole org.

Yes. I missed it.

salv-orlando · 2022-06-14T15:20:00Z

docs/getting-started.md

+
+## Overview
+
+Theia is a network observability and analytics platform for Kubernetes, bulit


typo: s/bulit/built

Add Theia overview, getting-started, contributing, community, and license information to README.md. Move Getting Started to a separate document, and add more information about Theia features and usage. section. Rename theia.md to theia-cli.md. Signed-off-by: Jianjun Shen <shenj@vmware.com>

salv-orlando

LGMT!

jianjuns added the documentation Improvements or additions to documentation label Jun 12, 2022

jianjuns requested review from salv-orlando, dreamtalen, ziyouw, yanjunz97 and heanlan June 12, 2022 05:22

jianjuns commented Jun 12, 2022

View reviewed changes

jianjuns force-pushed the theia-doc branch 4 times, most recently from 046db81 to c0421c6 Compare June 12, 2022 17:57

ziyouw reviewed Jun 13, 2022

View reviewed changes

jianjuns force-pushed the theia-doc branch from c0421c6 to 8335078 Compare June 13, 2022 17:04

heanlan reviewed Jun 13, 2022

View reviewed changes

jianjuns force-pushed the theia-doc branch from 8335078 to c30d3ad Compare June 13, 2022 17:20

heanlan reviewed Jun 13, 2022

View reviewed changes

dreamtalen reviewed Jun 13, 2022

View reviewed changes

yanjunz97 reviewed Jun 13, 2022

View reviewed changes

jianjuns force-pushed the theia-doc branch from c30d3ad to 1e000c7 Compare June 13, 2022 17:50

jianjuns requested a review from yuntanghsu June 13, 2022 17:53

jianjuns force-pushed the theia-doc branch from 1e000c7 to 740c319 Compare June 13, 2022 19:41

heanlan reviewed Jun 13, 2022

View reviewed changes

docs/getting-started.md Show resolved Hide resolved

dreamtalen reviewed Jun 13, 2022

View reviewed changes

jianjuns force-pushed the theia-doc branch 2 times, most recently from 7301d74 to ce983d4 Compare June 13, 2022 20:52

heanlan approved these changes Jun 13, 2022

View reviewed changes

yanjunz97 reviewed Jun 13, 2022

View reviewed changes

jianjuns force-pushed the theia-doc branch 2 times, most recently from 56a770c to e3ee3de Compare June 13, 2022 21:58

jianjuns changed the title ~~Revise README and user documents~~ Revise README, Getting Started, and flow visibility documents Jun 13, 2022

jianjuns force-pushed the theia-doc branch from e3ee3de to 2f4d4f8 Compare June 13, 2022 21:59

jianjuns added this to the 0.1 milestone Jun 14, 2022

jianjuns force-pushed the theia-doc branch from 2f4d4f8 to f146e4b Compare June 14, 2022 00:17

salv-orlando reviewed Jun 14, 2022

View reviewed changes

jianjuns force-pushed the theia-doc branch from f146e4b to 527594e Compare June 14, 2022 16:26

jianjuns force-pushed the theia-doc branch from 527594e to 479d146 Compare June 14, 2022 21:53

salv-orlando approved these changes Jun 15, 2022

View reviewed changes

jianjuns merged commit 3b9cec4 into main Jun 15, 2022

jianjuns deleted the theia-doc branch June 15, 2022 16:18

heanlan mentioned this pull request Jun 15, 2022

Update CHANGELOG and VERSION for v0.1.0 release #48

Merged

		@@ -1,4 +1,4 @@
		# Theia: Network Flow Visibility for Antrea
		# Theia - Network Observability and Analytics for Antrea

		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)


		## License

		Antrea is licensed under the [Apache License, version 2.0](LICENSE)


		## Overview

		Theia is a network observability and analytics platform for Kubernetes, bulit

Revise README, Getting Started, and flow visibility documents #45

Revise README, Getting Started, and flow visibility documents #45

Conversation

jianjuns commented Jun 12, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ziyouw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heanlan left a comment

Choose a reason for hiding this comment

jianjuns commented Jun 13, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dreamtalen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yanjunz97 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dreamtalen Jun 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heanlan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

salv-orlando left a comment

Choose a reason for hiding this comment

jianjuns commented Jun 12, 2022 •

edited

Loading

dreamtalen Jun 13, 2022 •

edited

Loading