Refactor Grafana and ClickHouse deployment configuration instructions #3525

heanlan · 2022-03-25T19:05:24Z

Signed-off-by: heanlan hanlan@vmware.com

dreamtalen · 2022-03-25T20:18:16Z

docs/network-flow-visibility.md

-ClickHouse credentials are also specified in [flow-aggregator.yml][flow_aggregator_manifest_yaml]
-as a resource of kind: a Secret. Please also make the corresponding changes.
+ClickHouse credentials are also specified in `flow-aggregator.yml` as a resource
+of name: `clickhouse-secret`. Please also make the corresponding changes.


It will be nice to show these lines of code to help users locate where to change these secrets in flow-aggregator.yml
https://github.com/antrea-io/antrea/blob/main/build/yamls/flow-aggregator.yml#L240-L251

dreamtalen · 2022-03-25T20:18:55Z

docs/network-flow-visibility.md

-Grafana login credentials are specified in [grafana.yml][grafana_manifest_yaml] as
-resource of kind: a Secret.
+Grafana login credentials are specified in `flow-visibility.yml` as a resource of
+name: `grafana-secret`.


Same suggestion for grafana-secret.

heanlan · 2022-03-25T21:31:09Z

Changed grafana Service type from LoadBalancer to NodePort in the latest commit, as currently there is no production level requirement asking for a LoadBalancer Service, and it requires cluster networking support. Would like to hear from the team for opinions.

codecov-commenter · 2022-03-25T21:34:16Z

Codecov Report

Merging #3525 (478d75d) into main (a539b78) will decrease coverage by 1.52%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #3525      +/-   ##
==========================================
- Coverage   65.46%   63.93%   -1.53%     
==========================================
  Files         278      278              
  Lines       27771    27825      +54     
==========================================
- Hits        18179    17789     -390     
- Misses       7666     8124     +458     
+ Partials     1926     1912      -14

Flag	Coverage Δ
kind-e2e-tests	`50.93% <ø> (-4.26%)`	⬇️
unit-tests	`43.39% <ø> (+0.05%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
pkg/apis/controlplane/types.go	`0.00% <0.00%> (-100.00%)`	⬇️
pkg/controller/networkpolicy/store/group.go	`5.00% <0.00%> (-70.00%)`	⬇️
pkg/apis/controlplane/helper.go	`33.33% <0.00%> (-66.67%)`	⬇️
pkg/controller/networkpolicy/convert.go	`0.00% <0.00%> (-64.52%)`	⬇️
pkg/controller/egress/store/egressgroup.go	`1.38% <0.00%> (-58.34%)`	⬇️
pkg/controller/networkpolicy/tier.go	`12.50% <0.00%> (-40.00%)`	⬇️
pkg/apiserver/handlers/webhook/convert_crd.go	`2.56% <0.00%> (-32.48%)`	⬇️
pkg/controller/types/group.go	`53.57% <0.00%> (-32.15%)`	⬇️
pkg/controller/networkpolicy/validate.go	`48.07% <0.00%> (-32.14%)`	⬇️
pkg/controller/networkpolicy/status_controller.go	`69.94% <0.00%> (-13.30%)`	⬇️
... and 32 more

antoninbas · 2022-03-25T22:00:34Z

build/yamls/flow-visibility/base/grafana.yml

@@ -193,4 +193,4 @@ spec:
  selector:
    app: grafana
  sessionAffinity: None
-  type: LoadBalancer


I agree with this change, but I think we should also mention in the documentation that users can change this Service type to LoadBalancer in the downloaded YAML, if their K8s cluster supports LoadBalancer Services

When we provide a Helm chart, this can be parameterized

antoninbas · 2022-03-25T22:01:18Z

docs/network-flow-visibility.md

@@ -659,8 +659,22 @@ kubectl delete -f https://raw.githubusercontent.com/Altinity/clickhouse-operator

 ##### Credentials Configuration

-ClickHouse credentials are specified in [clickhouse.yml][clickhouse_manifest_yaml] as
-a resource of kind: a Secret. If the username `clickhouse_operator` has changed, please
+ClickHouse credentials are specified in `flow-visibility.yml` as a resource of name:


as a Secret named clickhouse-secret

same below

antoninbas · 2022-03-25T22:02:52Z

docs/network-flow-visibility.md

+- If you have changed the HTTP port, please update the `url` of a resource of name `grafana-datasource-provider` in `flow-visibility.yml`.
+
+- If you have changed the TCP port, please update the `databaseURL` following [Flow Aggregator Configuration](#configuration-1),
+and also update the `jsonData.port` of the `grafana-datasource-provider` resource.


line wrapping

antoninbas · 2022-03-25T22:04:54Z

docs/network-flow-visibility.md

+for dashboard JSON files export and manual import.
+
+To generate a deployment manifest with the changes, please follow the following steps:


maybe emphasize that there are 2 ways of adding dashboards:

in the UI or by importing a JSON at runtime (I don't know how these are persisted to Grafana, they may be lost in case of a Pod restart?)

by generating a new manifest and (re)deploying, as described below

yes, the changes will be lost after a Pod restart. They won't be automatically saved to the source.
I have added the 2 ways, could you help check if the wordings make sense to you? Thanks

yanjunz97 · 2022-03-25T21:59:56Z

docs/network-flow-visibility.md

-specified in [clickhouse.yml][clickhouse_manifest_yaml] as `serviceTemplates`.
-To use other ports, please update the following section accordingly.
+specified in `flow-visibility.yml` as `serviceTemplates` of a resource of kind:
+a `ClickHouseInstallation`. To use other ports, please update the following section.


kind: a ClickHouseInstallation -> kind: ClickHouseInstallation?

yanjunz97 · 2022-03-25T22:10:38Z

docs/network-flow-visibility.md

-and `databaseURL` in the [Flow Aggregator Configuration](#configuration-1).
+This service is used by the Flow Aggregator and Grafana.
+
+- If you have changed the HTTP port, please update the `url` of a resource of name `grafana-datasource-provider` in `flow-visibility.yml`.


Maybe we need to keep consistency in whether we need a colon after "a resource of name"?

I will also join the chorus and ask to change 'resource of name' to 'ConfigMap named' at lines 750 and 753

wsquan171 · 2022-03-25T22:28:44Z

docs/network-flow-visibility.md


 The ClickHouse throughput depends on two factors - the storage size of the ClickHouse
 and the time interval between the batch commits to the ClickHouse. Larger storage
 size and longer commit interval provide higher throughput.

 Grafana flow collector supports the ClickHouse in-memory deployment with limited
-storage size. This is specified in [clickhouse.yml][clickhouse_manifest_yaml].
-The default value of storage size for the ClickHouse server is 8 GiB. Users
+storage size. This is specified in `flow-visibility.yml` under the `ClickHouseInstallation`


This a bit pedant, but maybe you can consider writing:

[...] under the clickhouse resource of kind ClickHouseInstallation. The default value [...]

wsquan171 · 2022-03-25T22:29:44Z

docs/network-flow-visibility.md

-storage size. This is specified in [clickhouse.yml][clickhouse_manifest_yaml].
-The default value of storage size for the ClickHouse server is 8 GiB. Users
+storage size. This is specified in `flow-visibility.yml` under the `ClickHouseInstallation`
+resource. The default value of storage size for the ClickHouse server is 8 GiB. Users
 can expect a linear growth in the ClickHouse throughput when they enlarge the
 storage size. For development or testing environment, you can decrease the storage
 size to 2GB. To deploy the ClickHouse with a different storage size, please


Suggested change

size to 2GB. To deploy the ClickHouse with a different storage size, please

size to 2GiB. To deploy the ClickHouse with a different storage size, please

antoninbas · 2022-03-26T01:33:33Z

docs/network-flow-visibility.md

@@ -602,6 +602,27 @@ use the checked-in [deployment yaml](/build/yamls/flow-visibility.yml):
 kubectl apply -f https://raw.githubusercontent.com/antrea-io/antrea/main/build/yamls/flow-visibility.yml
 ```

+To be noticed, Grafana is exposed as a NodePort Service by default in `flow-visibility.yml`.


I think you mean "To be accessible"

I guess just remove "To be noticed"

exposed through a NodePort Service

antoninbas · 2022-03-26T01:33:39Z

docs/network-flow-visibility.md

@@ -602,6 +602,27 @@ use the checked-in [deployment yaml](/build/yamls/flow-visibility.yml):
 kubectl apply -f https://raw.githubusercontent.com/antrea-io/antrea/main/build/yamls/flow-visibility.yml
 ```

+To be noticed, Grafana is exposed as a NodePort Service by default in `flow-visibility.yml`.
+If the given K8s cluster support LoadBalancer Services, Grafana can be changed to a


s/support/supports

"Grafana can be exposed through a LoadBalancer Service..."?

antoninbas · 2022-03-26T01:35:17Z

docs/network-flow-visibility.md

+a new dashboard, please follow this [doc](https://grafana.com/docs/grafana/latest/dashboards/)
+on how to build a dashboard.
+
+By saving dashboards in the Grafana UI, these changes will be persisted in Grafana


Maybe "By configuring dashboards"?

antoninbas · 2022-03-26T01:35:40Z

docs/network-flow-visibility.md

+a new dashboard, please follow this [doc](https://grafana.com/docs/grafana/latest/dashboards/)
+on how to build a dashboard.
+
+By saving dashboards in the Grafana UI, these changes will be persisted in Grafana


in the Grafana database

antoninbas · 2022-03-26T01:35:59Z

docs/network-flow-visibility.md

+
+By saving dashboards in the Grafana UI, these changes will be persisted in Grafana
+database at runtime, but they will be lost after restarting the Grafana deployment.
+To keep those changes for a restart, as the first step, you will need to export the


To restore those changes after a restart

antoninbas · 2022-03-26T01:36:22Z

docs/network-flow-visibility.md

+By saving dashboards in the Grafana UI, these changes will be persisted in Grafana
+database at runtime, but they will be lost after restarting the Grafana deployment.
+To keep those changes for a restart, as the first step, you will need to export the
+dashboard JSON file following the [doc](https://grafana.com/docs/grafana/latest/dashboards/export-import/), then there are two ways to import the dashboard depending on your needs.


line wrap

also end the sentence with a : and not a .

antoninbas · 2022-03-26T01:36:52Z

docs/network-flow-visibility.md

+dashboard JSON file following the [doc](https://grafana.com/docs/grafana/latest/dashboards/export-import/), then there are two ways to import the dashboard depending on your needs.
+
+- In the running Grafana UI, manually import the dashboard JSON files.
+- If you want the changed dashboards to be automatically provisioned to Grafana


s/provisioned to Grafana/provisioned in Grafana

antoninbas · 2022-03-26T01:36:58Z

docs/network-flow-visibility.md

+- In the running Grafana UI, manually import the dashboard JSON files.
+- If you want the changed dashboards to be automatically provisioned to Grafana
+like our pre-built dashboards, generate a deployment manifest with the changes by
+following the steps as below:


the steps below

jianjuns · 2022-03-28T03:20:42Z

docs/network-flow-visibility.md

@@ -602,6 +602,27 @@ use the checked-in [deployment yaml](/build/yamls/flow-visibility.yml):
 kubectl apply -f https://raw.githubusercontent.com/antrea-io/antrea/main/build/yamls/flow-visibility.yml
 ```

+To be noticed, Grafana is exposed as a NodePort Service by default in `flow-visibility.yml`.


I guess just remove "To be noticed"

jianjuns · 2022-03-28T03:22:14Z

docs/network-flow-visibility.md

@@ -602,6 +602,27 @@ use the checked-in [deployment yaml](/build/yamls/flow-visibility.yml):
 kubectl apply -f https://raw.githubusercontent.com/antrea-io/antrea/main/build/yamls/flow-visibility.yml
 ```

+To be noticed, Grafana is exposed as a NodePort Service by default in `flow-visibility.yml`.
+If the given K8s cluster support LoadBalancer Services, Grafana can be changed to a


"Grafana can be exposed through a LoadBalancer Service..."?

jianjuns · 2022-03-28T03:23:09Z

docs/network-flow-visibility.md

@@ -602,6 +602,27 @@ use the checked-in [deployment yaml](/build/yamls/flow-visibility.yml):
 kubectl apply -f https://raw.githubusercontent.com/antrea-io/antrea/main/build/yamls/flow-visibility.yml
 ```

+To be noticed, Grafana is exposed as a NodePort Service by default in `flow-visibility.yml`.


exposed through a NodePort Service

jianjuns · 2022-03-28T03:25:29Z

docs/network-flow-visibility.md

 ```

+We recommend changing all the credentials above if you are going to run the Flow
+Collector in production.
+
 ##### ClickHouse Configuration

 The ClickHouse database can be accessed through the service `clickhouse-clickhouse`.
 The pod exposes HTTP port at 8123 and TCP port at 9000 by default. The ports are


jianjuns · 2022-03-28T03:27:37Z

docs/network-flow-visibility.md

 ```

+We recommend changing all the credentials above if you are going to run the Flow
+Collector in production.
+
 ##### ClickHouse Configuration

 The ClickHouse database can be accessed through the service `clickhouse-clickhouse`.


"service" refers to K8 Service? If so, use "Service" and change other occurrences.

salv-orlando · 2022-03-28T07:42:09Z

docs/network-flow-visibility.md

-and `databaseURL` in the [Flow Aggregator Configuration](#configuration-1).
+This service is used by the Flow Aggregator and Grafana.
+
+- If you have changed the HTTP port, please update the `url` of a resource of name `grafana-datasource-provider` in `flow-visibility.yml`.


I will also join the chorus and ask to change 'resource of name' to 'ConfigMap named' at lines 750 and 753

salv-orlando · 2022-03-28T07:44:45Z

docs/network-flow-visibility.md


 The ClickHouse throughput depends on two factors - the storage size of the ClickHouse
 and the time interval between the batch commits to the ClickHouse. Larger storage
 size and longer commit interval provide higher throughput.

 Grafana flow collector supports the ClickHouse in-memory deployment with limited
-storage size. This is specified in [clickhouse.yml][clickhouse_manifest_yaml].
-The default value of storage size for the ClickHouse server is 8 GiB. Users
+storage size. This is specified in `flow-visibility.yml` under the `ClickHouseInstallation`


This a bit pedant, but maybe you can consider writing:

[...] under the clickhouse resource of kind ClickHouseInstallation. The default value [...]

docs/network-flow-visibility.md

heanlan · 2022-03-28T16:44:53Z

Resolved all the comments and squashed the the commits. May I ask for another round of review? @antoninbas @jianjuns @salv-orlando

jianjuns

Just a nit.

jianjuns · 2022-03-28T17:03:49Z

docs/network-flow-visibility.md

-To use other ports, please update the following section accordingly.
+The ClickHouse database can be accessed through the Service `clickhouse-clickhouse`.
+The Pod exposes HTTP port at 8123 and TCP port at 9000 by default. The ports are
+specified in `flow-visibility.yml` as `serviceTemplates` of a resource of kind:


I could not understand this sentence. I apologize if it is that I missed something obvious.

Do you mean "as serviceTemplates of a ClickHouseInstallation resource"?

yes, that's what I was trying to say. Rephrased as suggested. Thanks.

salv-orlando

LGTM, pending feedback from @jianjuns

Signed-off-by: heanlan <hanlan@vmware.com> Change grafana Service to NodePort Signed-off-by: heanlan <hanlan@vmware.com>

antoninbas · 2022-03-28T18:16:04Z

/skip-all

heanlan · 2022-03-28T21:30:15Z

@antoninbas shall we merge it now?

heanlan force-pushed the doc-refactor branch from 39aea91 to 08d1ab0 Compare March 25, 2022 19:09

heanlan requested review from yanjunz97, antoninbas, salv-orlando, dreamtalen and wsquan171 March 25, 2022 19:10

heanlan added this to the Antrea v1.6 release milestone Mar 25, 2022

dreamtalen reviewed Mar 25, 2022

View reviewed changes

heanlan force-pushed the doc-refactor branch from 08d1ab0 to 40ce85c Compare March 25, 2022 20:32

antoninbas reviewed Mar 25, 2022

View reviewed changes

yanjunz97 reviewed Mar 25, 2022

View reviewed changes

wsquan171 reviewed Mar 25, 2022

View reviewed changes

antoninbas reviewed Mar 26, 2022

View reviewed changes

jianjuns reviewed Mar 28, 2022

View reviewed changes

salv-orlando reviewed Mar 28, 2022

View reviewed changes

heanlan force-pushed the doc-refactor branch from 13bd9c8 to 099e8dd Compare March 28, 2022 16:43

jianjuns reviewed Mar 28, 2022

View reviewed changes

salv-orlando reviewed Mar 28, 2022

View reviewed changes

Refactor Grafana and ClickHouse deployment configuration instructions

478d75d

Signed-off-by: heanlan <hanlan@vmware.com> Change grafana Service to NodePort Signed-off-by: heanlan <hanlan@vmware.com>

heanlan force-pushed the doc-refactor branch from 099e8dd to 478d75d Compare March 28, 2022 17:53

dreamtalen mentioned this pull request Mar 28, 2022

Release 1.6.0 #3531

Merged

antoninbas approved these changes Mar 28, 2022

View reviewed changes

antoninbas merged commit 245ac54 into antrea-io:main Mar 28, 2022

		for dashboard JSON files export and manual import.

		To generate a deployment manifest with the changes, please follow the following steps:

	size to 2GB. To deploy the ClickHouse with a different storage size, please
	size to 2GiB. To deploy the ClickHouse with a different storage size, please

Refactor Grafana and ClickHouse deployment configuration instructions #3525

Refactor Grafana and ClickHouse deployment configuration instructions #3525

Conversation

heanlan commented Mar 25, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heanlan commented Mar 25, 2022 • edited

codecov-commenter commented Mar 25, 2022 • edited

Codecov Report

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

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

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

heanlan commented Mar 28, 2022

jianjuns left a 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

antoninbas commented Mar 28, 2022

heanlan commented Mar 28, 2022

heanlan commented Mar 25, 2022 •

edited

codecov-commenter commented Mar 25, 2022 •

edited