Improve the Kubernetes deployment documentation (#10662)
* Update k8s deployment instructions * More tweaks * Change claiming instructions, restore old guide to separate work * Remove beta * Remove data collect from parent config * Remove dbengine override * Tweaks * Add notice about history setting
Joel Hans committed
Feb 24, 2021 at 13:49 UTC
1345d39f75f20692c2e4bd5aa01388b406eabd05
1 file changed
+104
-126
packaging/installer/methods/kubernetes.md
+104
-126
@@ -1,25 +1,21 @@
1
<!--
2
-title: "Install Netdata on a Kubernetes cluster"
3
-description: "Use Netdata's Helm chart to bootstrap a Netdata monitoring and troubleshooting toolkit on your Kubernetes (k8s) cluster."
2
+title: "Deploy Kubernetes monitoring with Netdata"
3
+description: "Deploy Netdata to monitor a Kubernetes cluster to monitor the health, performance, resource utilization, and application metrics of a Kubernetes cluster in real time."
4
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/kubernetes.md
5
-->
6
7
-# Install Netdata on a Kubernetes cluster
7
+# Deploy Kubernetes monitoring with Netdata
8
9
This document details how to install Netdata on an existing Kubernetes (k8s) cluster. By following these directions, you
10
-will use Netdata's [Helm chart](https://github.com/netdata/helmchart) to bootstrap a Netdata deployment on your cluster.
11
-The Helm chart installs one parent pod for storing metrics and managing alarm notifications plus an additional child pod
12
-for every node in the cluster.
10
+will use Netdata's [Helm chart](https://github.com/netdata/helmchart) to create a Kubernetes monitoring deployment on
11
+your cluster.
12
14
-Each child pod will collect metrics from the node it runs on, in addition to [compatible
15
-applications](https://github.com/netdata/helmchart#service-discovery-and-supported-services), plus any endpoints covered
16
-by our [generic Prometheus collector](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/prometheus),
17
-via [service discovery](https://github.com/netdata/agent-service-discovery/). Each child pod will also collect
18
-[cgroups](/collectors/cgroups.plugin/README.md),
19
-[Kubelet](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/k8s_kubelet), and
20
-[kube-proxy](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/k8s_kubeproxy) metrics from its node.
13
+The Helm chart installs one `parent` pod for storing metrics and managing alarm notifications, plus an additional
14
+`child` pod for every node in the cluster, responsible for collecting metrics from the node, Kubernetes control planes,
15
+pods/containers, and [supported application-specific
16
+metrics](https://github.com/netdata/helmchart#service-discovery-and-supported-services).
17
22
-To install Netdata on a Kubernetes cluster, you need:
18
+To deploy Kubernetes monitoring with Netdata, you need:
19
20
- A working cluster running Kubernetes v1.9 or newer.
21
- The [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) command line tool, within [one minor version
@@ -27,12 +23,6 @@ To install Netdata on a Kubernetes cluster, you need:
23
administrative system.
24
- The [Helm package manager](https://helm.sh/) v3.0.0 or newer on the same administrative system.
25
30
-The default configuration creates one `parent` pod, installed on one of your cluster's nodes, and a DaemonSet for
31
-additional `child` pods. This DaemonSet ensures that every node in your k8s cluster also runs a `child` pod, including
32
-the node that also runs `parent`. The `child` pods collect metrics and stream the information to the `parent` pod, which
33
-uses two persistent volumes to store metrics and alarms. The `parent` pod also handles alarm notifications and enables
34
-the Netdata dashboard using an ingress controller.
35
-
26
## Install the Netdata Helm chart
27
28
We recommend you install the Helm chart using our Helm repository. In the `helm install` command, replace `netdata` with
@@ -43,147 +33,125 @@ helm repo add netdata https://netdata.github.io/helmchart/
33
helm install netdata netdata/netdata
34
```
35
46
-> You can also install the Netdata Helm chart by cloning the
47
-> [repository](https://artifacthub.io/packages/helm/netdata/netdata#install-by-cloning-the-repository) and manually
48
-> running Helm against the included chart.
49
-
50
-### Post-installation
51
-
36
Run `kubectl get services` and `kubectl get pods` to confirm that your cluster now runs a `netdata` service, one
53
-`parent` pod, and three `child` pods.
37
+parent pod, and multiple child pods.
38
55
-You've now installed Netdata on your Kubernetes cluster. See how to [access the Netdata
56
-dashboard](#access-the-netdata-dashboard) to confirm it's working as expected, or see the next section to [configure the
57
-Helm chart](#configure-the-netdata-helm-chart) to suit your cluster's particular setup.
39
+You've now installed Netdata on your Kubernetes cluster. Next, it's time to opt-in and enable the powerful Kubernetes
40
+dashboards available in Netdata Cloud.
41
59
-## Configure the Netdata Helm chart
42
+## Claim your Kubernetes cluster to Netdata Cloud
43
61
-Read up on the various configuration options in the [Helm chart
62
-documentation](https://github.com/netdata/helmchart#configuration) to see if you need to change any of the options based
63
-on your cluster's setup.
44
+To start [Kubernetes monitoring](https://learn.netdata.cloud/docs/cloud/visualizations/kubernetes/), you must first
45
+[claim](/claim/README.md) your Kubernetes cluster to [Netdata Cloud](https://app.netdata.cloud). Claiming securely
46
+connects your Kubernetes cluster to stream metrics data to Netdata Cloud, enabling Kubernetes-specific visualizations
47
+like the health map and time-series composite charts.
48
65
-To change a setting, use the `--set` or `--values` arguments with `helm install`, for the initial deployment, or `helm upgrade` to upgrade an existing deployment.
49
+First, find your claiming script in Netdata Cloud by clicking on your Space's dropdown, then **Manage your Space**.
50
+Click the **Nodes** tab to reveal the `netdata-claim.sh` script for your Space in Netdata Cloud. You need the `TOKEN`
51
+and `ROOM` values.
52
67
-```bash
68
-helm install --set a.b.c=xyz netdata netdata/netdata
69
-helm upgrade --set a.b.c=xyz netdata netdata/netdata
70
-```
71
-
72
-For example, to change the size of the persistent metrics volume on the parent node:
53
+Next, create a file called `override.yml`.
54
55
```bash
75
-helm install --set parent.database.volumesize=4Gi netdata netdata/netdata
76
-helm upgrade --set parent.database.volumesize=4Gi netdata netdata/netdata
56
+touch override.yml
57
```
58
79
-### Configure service discovery
80
-
81
-As mentioned in the introduction, Netdata has a [service discovery
82
-plugin](https://github.com/netdata/agent-service-discovery/#service-discovery) to identify compatible pods and collect
83
-metrics from the service they run. The Netdata Helm chart installs this service discovery plugin into your k8s cluster.
84
-
85
-Service discovery scans your cluster for pods exposed on certain ports and with certain image names. By default, it
86
-looks for its supported services on the ports they most commonly listen on, and using default image names. Service
87
-discovery currently supports [popular
88
-applications](https://github.com/netdata/helmchart#service-discovery-and-supported-services), plus any endpoints covered
89
-by our [generic Prometheus collector](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/prometheus).
90
-
91
-If you haven't changed listening ports, image names, or other defaults, service discovery should find your pods, create
92
-the proper configurations based on the service that pod runs, and begin monitoring them immediately after deployment.
59
+Paste the following into your `override.yml` file, replacing instances of `ROOM` and `TOKEN` with those from the
60
+claiming script from Netdata Cloud. These settings claim your `parent`/`child` nodes to Netdata Cloud and store more
61
+metrics in the nodes' time-series databases.
62
+
63
+```yaml
64
+parent:
65
+ claiming:
66
+ enabled: true
67
+ token: "TOKEN"
68
+ rooms: "ROOM"
69
+
70
+child:
71
+ claiming:
72
+ enabled: true
73
+ token: "TOKEN"
74
+ rooms: "ROOM"
75
+ configs:
76
+ netdata:
77
+ data: |
78
+ [global]
79
+ memory mode = ram
80
+ history = 3600
81
+ [health]
82
+ enabled = no
83
+```
84
94
-However, if you have changed some of these defaults, you need to copy a file from the Netdata Helm chart repository,
95
-make your edits, and pass the changed file to `helm install`/`helm upgrade`.
85
+> ❗ These override settings, along with the Helm chart's defaults, will retain an hour's worth of metrics (`history =
86
+> 3600`, or `3600 seconds`) on each child node. Based on your metrics retention needs, and the resources available on
87
+> your cluster, you may want to increase the `history` setting.
88
97
-First, copy the file to your administrative system.
89
+Apply these new settings:
90
91
```bash
100
-curl https://raw.githubusercontent.com/netdata/helmchart/master/charts/netdata/sdconfig/child.yml -o child.yml
92
+helm upgrade -f override.yml netdata netdata/netdata
93
```
94
103
-Edit the new `child.yml` file according to your needs. See the [Helm chart
104
-configuration](https://github.com/netdata/helmchart#configuration) and the file itself for details.
95
+The cluster terminates the old pods and creates new ones with the proper persistence and claiming configuration. You'll
96
+see your nodes, containers, and pods appear in Netdata Cloud in a few seconds.
97
106
-You can then run `helm install`/`helm upgrade` with the `--set-file` argument to use your configured `child.yml` file
107
-instead of the default, changing the path if you copied it elsewhere.
98
+
100
109
-```bash
110
-helm install --set-file sd.child.configmap.from.value=./child.yml netdata netdata/netdata
111
-helm upgrade --set-file sd.child.configmap.from.value=./child.yml netdata netdata/netdata
112
-```
101
+If you don't need to configure your Netdata deployment, [skip down](#whats-next) to see how Kubernetes monitoring works
102
+in Netdata, in addition to more guides and resources.
103
114
-Your configured service discovery is now pushed to your cluster.
104
+## Configure your Netdata monitoring deployment
105
116
-## Access the Netdata dashboard
106
+Read up on the various configuration options in the [Helm chart
107
+documentation](https://github.com/netdata/helmchart#configuration) if you need to tweak your Kubernetes monitoring.
108
118
-Accessing the Netdata dashboard itself depends on how you set up your k8s cluster and the Netdata Helm chart. If you
119
-installed the Helm chart with the default `service.type=ClusterIP`, you will need to forward a port to the parent pod.
109
+Your first option is to create an `override.yml` file, if you haven't created one already for
110
+[claim](#claim-your-kubernetes-cluster-to-netdata-cloud), then apply the new configuration to your cluster with `helm
111
+upgrade`.
112
113
```bash
122
-kubectl port-forward netdata-parent-0 19999:19999
114
+helm upgrade -f override.yml netdata netdata/netdata
115
```
116
125
-You can now access the dashboard at `http://CLUSTER:19999`, replacing `CLUSTER` with the IP address or hostname of your
126
-k8s cluster.
127
-
128
-If you set up the Netdata Helm chart with `service.type=LoadBalancer`, you can find the external IP for the load
129
-balancer with `kubectl get services`, under the `EXTERNAL-IP` column.
117
+If you want to change only a single setting, use the `--set` argument with `helm upgrade`. For example, to change the
118
+size of the persistent metrics volume on the parent node:
119
120
```bash
132
-kubectl get services
133
-NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
134
-cockroachdb ClusterIP None <none> 26257/TCP,8080/TCP 46h
135
-cockroachdb-public ClusterIP 10.245.148.233 <none> 26257/TCP,8080/TCP 46h
136
-kubernetes ClusterIP 10.245.0.1 <none> 443/TCP 47h
137
-netdata LoadBalancer 10.245.160.131 203.0.113.0 19999:32231/TCP 74m
121
+helm upgrade --set parent.database.volumesize=4Gi netdata netdata/netdata
122
```
123
140
-In the above example, access the dashboard by navigating to `http://203.0.113.0:19999`.
141
-
142
-## Claim a Kubernetes cluster's parent pod
143
-
144
-You can [claim](/claim/README.md) a cluster's parent Netdata pod to see its real-time metrics alongside any other nodes
145
-you monitor using [Netdata Cloud](https://app.netdata.cloud).
124
+### Configure service discovery
125
147
-> Netdata Cloud does not currently support claiming child nodes because the Helm chart does not allocate a persistent
148
-> volume for them.
126
+Netdata's [service discovery](https://github.com/netdata/agent-service-discovery/#service-discovery), which is
127
+installed as part of the Helm chart installation, finds what services are running on a cluster's pods, converts that
128
+into configuration files, and exports them so they can be monitored.
129
150
-Ensure persistence is enabled on the parent pod by running the following `helm upgrade` command.
130
+Service discovery supports [popular applications](https://github.com/netdata/helmchart#applications) and [Prometheus
131
+endpoints](https://github.com/netdata/helmchart#prometheus-endpoints).
132
152
-```bash
153
-helm upgrade \
154
- --set parent.database.persistence=true \
155
- --set parent.alarms.persistence=true \
156
- netdata netdata/netdata
157
-```
133
+If your cluster runs services on non-default ports or uses non-default names, you may need to configure service
134
+discovery to start collecting metrics from your services. You have to edit the default ConfigMap that is shipped with
135
+the Helmchart and deploy that to your cluster.
136
159
-Next, find your claiming script in Netdata Cloud by clicking on your Space's dropdown, then **Manage your Space**. Click
160
-the **Nodes** tab. Netdata Cloud shows a script similar to the following:
137
+First, copy the default file to your administrative system.
138
139
```bash
163
-sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
140
+curl https://raw.githubusercontent.com/netdata/helmchart/master/charts/netdata/sdconfig/child.yml -o child.yml
141
```
142
166
-You will need the values of `TOKEN` and `ROOM1,ROOM2` for the command, which sets `parent.claiming.enabled`,
167
-`parent.claiming.token`, and `parent.claiming.rooms` to complete the parent pod claiming process.
143
+Edit the new `child.yml` file according to your needs. See the [Helm chart
144
+configuration](https://github.com/netdata/helmchart#configuration) and the file itself for details.
145
169
-Run the following `helm upgrade` command after replacing `TOKEN` and `ROOM1,ROOM2` with the values found in the claiming
170
-script from Netdata Cloud. The quotations are required.
146
+You can then run `helm upgrade` with the `--set-file` argument to use your configured `child.yml` file instead of the
147
+default, changing the path if you copied it elsewhere.
148
149
```bash
173
-helm upgrade \
174
- --set parent.claiming.enabled=true \
175
- --set parent.claiming.token="TOKEN" \
176
- --set parent.claiming.rooms="ROOM1,ROOM2" \
177
- netdata netdata/netdata
150
+helm upgrade --set-file sd.child.configmap.from.value=./child.yml netdata netdata/netdata
151
```
152
180
-The cluster terminates the old parent pod and creates a new one with the proper claiming configuration. You can see your
181
-parent pod in Netdata Cloud after a few moments. You can now [build new
182
-dashboards](https://learn.netdata.cloud/docs/cloud/visualize/dashboards) using the parent pod's metrics or run [Metric
183
-Correlations](https://learn.netdata.cloud/docs/cloud/insights/metric-correlations) to troubleshoot anomalies.
184
-
185
-
153
+Now that you pushed an edited ConfigMap to your cluster, service discovery should find and set up metrics collection
154
+from your non-default service.
155
156
## Update/reinstall the Netdata Helm chart
157
@@ -194,16 +162,26 @@ with the name of the release, if you changed it upon installation:
162
helm upgrade netdata netdata/netdata
163
```
164
165
+To update Netdata's Helm chart to the latest version, run `helm repo update`, then deploy `upgrade` it`:
166
+
167
+```bash
168
+helm repo update
169
+helm upgrade netdata netdata/netdata
170
+```
171
+
172
## What's next?
173
199
-Read the [monitoring a Kubernetes cluster guide](/docs/guides/monitor/kubernetes-k8s-netdata.md) for details on the
200
-various metrics and charts created by the Helm chart and some best practices on real-time troubleshooting using Netdata.
174
+[Start Kubernetes monitoring](https://learn.netdata.cloud/docs/cloud/visualizations/kubernetes/) in Netdata Cloud, which
175
+comes with meaningful visualizations out of the box.
176
+
177
+Read our guide, [_Kubernetes monitoring with Netdata_](/docs/guides/monitor/kubernetes-k8s-netdata.md), for a complete
178
+walkthrough of Netdata's Kubernetes monitoring capabilities, including a health map of every container in your
179
+infrastructure, aggregated resource utilization metrics, and application metrics.
180
202
-Check out our [infrastructure](/docs/quickstart/infrastructure.md) for details about additional k8s monitoring features,
203
-and learn more about [configuring the Netdata Agent](/docs/configure/nodes.md) to better understand the settings you
204
-might be interested in changing.
181
+### Related reference documentation
182
206
-To further configure Netdata for your cluster, see our [Helm chart repository](https://github.com/netdata/helmchart) and
207
-the [service discovery repository](https://github.com/netdata/agent-service-discovery/).
183
+- [Netdata Cloud · Kubernetes monitoring](https://learn.netdata.cloud/docs/cloud/visualizations/kubernetes/)
184
+- [Netdata Helm chart](https://github.com/netdata/helmchart)
185
+- [Netdata service discovery](https://github.com/netdata/agent-service-discovery/)
186
187
[](<>)