Revise README, Getting Started, and flow visibility documents #45
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,45 @@ | ||
| # Theia | ||
|
|
||
| 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 communication and NetworkPolicies | ||
| among Pods and Services in a Kubernetes cluster. | ||
|
|
||
| ## Getting Started | ||
|
|
||
| Getting started with Theia is simple. You can follow the [Getting Started](docs/getting-started.md) | ||
| guide to install Theia and start rocking! | ||
|
|
||
| Theia supports network flow visualization and monitoring with Grafana. Check the | ||
|
There was a problem hiding this comment. Right now, Theia only supports flow visibility and NP recommendation for a single cluster. Maybe we should highlight this before we can support more? There was a problem hiding this comment. 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. There was a problem hiding this comment. I would not include "forward-looking" statements in the README files. |
||
| [Network Flow Visibility](docs/network-flow-visibility.md) 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). | ||
|
There was a problem hiding this comment. Took a look at the workflow failure, it seems the There was a problem hiding this comment. It will be added in #40 |
||
| * 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! | ||
|
There was a problem hiding this comment. This is not about this PR, but we also need an arch doc for Theia to integrate Antrea's one. |
||
| * Check out [Open Issues](https://github.com/antrea-io/theia/issues). | ||
| * Join the Antrea [community](#community) and ask us any question you may have. | ||
dreamtalen marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Community | ||
|
|
||
| Please refer to the [Antrea community](https://github.com/antrea-io/antrea/blob/main/README.md#community) | ||
| information. | ||
|
|
||
| ## License | ||
|
|
||
| Theia is licensed under the [Apache License, version 2.0](LICENSE) | ||
|
|
||
| [](https://app.fossa.com/projects/git%2Bgithub.com%2Fantrea-io%2Fantrea?ref=badge_large) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| # Getting Started with Theia | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| <!-- toc --> | ||
| - [Overview](#overview) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Theia Installation](#theia-installation) | ||
| - [Features](#features) | ||
| - [Network Flow Visualization and Monitoring](#network-flow-visualization-and-monitoring) | ||
| - [NetworkPolicy Recommendation](#networkpolicy-recommendation) | ||
| - [Additional Information](#additional-information) | ||
| <!-- /toc --> | ||
|
|
||
| ## Overview | ||
|
|
||
| Theia is a network observability and analytics platform for Kubernetes, 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 communication and NetworkPolicies | ||
| among Pods and Services in a Kubernetes cluster. | ||
|
|
||
| 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. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| Theia requires that Antrea v1.7.0 or later is installed in the Kubernetes | ||
| cluster. Ensure the Flow Exporter feature of Antrea Agent is enabled in the | ||
| Antrea deployment manifest: | ||
|
|
||
| ```yaml | ||
| antrea-agent.conf: | | ||
| ... | ||
| featureGates: | ||
| ... | ||
| FlowExporter: true | ||
| ``` | ||
|
|
||
| ## Theia Installation | ||
|
|
||
| To enable both [Grafana Flow Collector](network-flow-visibility.md) and | ||
| [NetworkPolicy Recommendation](networkpolicy-recommendation.md), please install | ||
| Flow Aggregator and Theia by runnning the following commands: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/antrea-io/theia.git | ||
| helm install flow-aggregator theia/build/charts/flow-aggregator --set clickHouse.enable=true,recordContents.podLabels=true -n flow-aggregator --create-namespace | ||
| helm install theia theia/build/charts/theia --set sparkOperator.enable=true -n flow-visibility --create-namespace | ||
| ``` | ||
|
|
||
| To enable only Grafana Flow Collector, please install Flow Aggregator and Theia | ||
| by runnning the following commands: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/antrea-io/theia.git | ||
| helm install flow-aggregator theia/build/charts/flow-aggregator --set clickHouse.enable=true -n flow-aggregator --create-namespace | ||
| helm install theia theia/build/charts/theia -n flow-visibility --create-namespace | ||
| ``` | ||
|
|
||
| ## Features | ||
|
|
||
| ### Network Flow Visualization and Monitoring | ||
|
|
||
| Theia uses Grafana to visualize network flows in the Kubernetes cluster. After | ||
heanlan marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| the installation, you can run the following commands 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 access Grafana in your browser at: `http://[NodeIP]:[NodePort]`, and log | ||
| in with username: `admin` and password: `admin`. Navigate to the [Theia | ||
| dashboards](network-flow-visibility.md#grafana-dashboards) to view the network | ||
| flows in the cluster. | ||
|
|
||
| ### 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](network-flow-visibility.md#deployment-steps), | ||
| and [Configuration](network-flow-visibility.md#configuration). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@salv-orlando : I believe you can write a better version. But could we start from the simple introduction?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
just propose "visibility on workload among Pods, Service and external network" as alternative.