Add documentation for installing Netdata on k8s clusters (#9364)
* Init install doc * Finish draft * Fixes for Mansour * Revert-ish for Mansour * Fix for Ilya * Clarify sdconfig * Test and finalize set-file instructions
Joel Hans committed
Jul 1, 2020 at 16:25 UTC
6f3d87b2dd57a1511a91821ed0569a2f337d20fd
2 files changed
+159
-4
packaging/installer/README.md
+1
-4
@@ -1,8 +1,6 @@
1
<!--
2
----
2
title: "Installation guide"
3
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/README.md
5
----
4
-->
5
6
# Installation guide
@@ -83,8 +81,7 @@ Netdata on Docker](/packaging/docker/README.md)
81
82
[ Install
86
-Netdata on Kubernetes with a Helm
87
-chart](https://github.com/netdata/helmchart#netdata-helm-chart-for-kubernetes-deployments)
84
+Netdata on a Kubernetes cluster](/packaging/installer/methods/kubernetes.md)
85
86
[
packaging/installer/methods/kubernetes.md
new
+158
@@ -0,0 +1,158 @@
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."
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
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.
13
+
14
+Each child pod will collect metrics from the node it runs on in addition to [22 supported
15
+services](https://github.com/netdata/helmchart#service-discovery-and-supported-services) via [service
16
+discovery](https://github.com/netdata/agent-service-discovery/). Each child pod will also collect
17
+[cgroups](/collectors/cgroups.plugin/README.md),
18
+[Kubelet](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/k8s_kubelet), and
19
+[kube-proxy](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/k8s_kubeproxy) metrics from its node.
20
+
21
+To install Netdata on a Kubernetes cluster, you need:
22
+
23
+- A working cluster running Kubernetes v1.9 or newer.
24
+- The [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) command line tool, within [one minor version
25
+ difference](https://kubernetes.io/docs/tasks/tools/install-kubectl/#before-you-begin) of your cluster, on an
26
+ administrative system.
27
+- The [Helm package manager](https://helm.sh/) v3.0.0 or newer on the same administrative system.
28
+
29
+The default configuration creates one `parent` pod, installed on one of your cluster's nodes, and a DaemonSet for
30
+additional `child` pods. This DaemonSet ensures that every node in your k8s cluster also runs a `child` pod, including
31
+the node that also runs `parent`. The `child` pods collect metrics and stream the information to the `parent` pod, which
32
+uses two persistent volumes to store metrics and alarms. The `parent` pod also handles alarm notifications and enables
33
+the Netdata dashboard using an ingress controller.
34
+
35
+## Install the Netdata Helm chart
36
+
37
+Download the [Netdata Helm chart](https://github.com/netdata/helmchart) on the administative system where you have the
38
+`helm` binary installed.
39
+
40
+```bash
41
+git clone https://github.com/netdata/helmchart.git netdata-helmchart
42
+```
43
+
44
+> You may not need to configure the Helm chart to get a functioning service on your cluster, but you should read the
45
+> sections on [configuring the Helm chart](#configure-the-netdata-helm-chart) and [configuring service
46
+> discovery](#configure-service-discovery) for details.
47
+
48
+Install the Helm chart to your cluster with `helm install`:
49
+
50
+```bash
51
+helm install netdata ./netdata-helmchart
52
+```
53
+
54
+Run `kubectl get services` and `kubectl get pods` to confirm that your cluster now runs a `netdata` service, one
55
+`parent` pod, and three `child` pods.
56
+
57
+You've now installed Netdata on your Kubernetes cluster. See how to [access the Netdata
58
+dashboard](#access-the-netdata-dashboard) to confirm it's working as expected, or see the next section to [configure the
59
+Helm chart](#configure-the-netdata-helm-chart) to suit your cluster's particular setup.
60
+
61
+## Configure the Netdata Helm chart
62
+
63
+Read up on the various configuration options in the [Helm chart
64
+documentation](https://github.com/netdata/helmchart#configuration) to see if you need to change any of the options based
65
+on your cluster's setup.
66
+
67
+To change a setting, use the `--set` or `--values` arguments along with `helm install`:
68
+
69
+```bash
70
+helm install --set a.b.c=xyz netdata ./netdata-helmchart
71
+```
72
+
73
+For example, to change the size of the persistent metrics volume, you would run the following:
74
+
75
+```bash
76
+helm install --set parent.database.volumesize=4Gi ./netdata-helmchart
77
+```
78
+
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 [22 popular
88
+services](https://github.com/netdata/helmchart#service-discovery-and-supported-services).
89
+
90
+If you haven't changed listening ports or other defaults, service discovery should find your pods, create the proper
91
+configurations based on the service that pod runs, and begin monitoring them immediately after depolyment.
92
+
93
+However, if you have changed some of these defaults, you'll need to copy the `netdata-helmchart/sdconfig/child.yml`
94
+file, edit it, and pass the changed file to `helm install`/`helm upgrade`.
95
+
96
+First, copy the file to a new location outside the `netdata-helmchart` directory. The destination can be anywhere you
97
+like, but the following examples assume it resides next to the `netdata-helmchart` directory.
98
+
99
+```bash
100
+cp netdata-helmchart/sdconfig/child.yml .
101
+```
102
+
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. You can then run
105
+`helm install`/`helm upgrade` with the `--set-file` argument to use your configured `child.yml` file instead of the
106
+default, changing the path if you copied it elsewhere.
107
+
108
+```bash
109
+helm install --set-file sd.child.configmap.from.value=./child.yml netdata ./netdata-helmchart
110
+helm upgrade --set-file sd.child.configmap.from.value=./child.yml netdata ./netdata-helmchart
111
+```
112
+
113
+Your configured service discovery is now pushed to your cluster.
114
+
115
+## Access the Netdata dashboard
116
+
117
+Accessing the Netdata dashboard itself depends on how you set up your k8s cluster and the Netdata Helm chart. If you
118
+installed the Helm chart with the default `service.type=ClusterIP`, you will need to forward a port to the parent pod.
119
+
120
+```bash
121
+kubectl port-forward netdata-parent-0 19999:19999
122
+```
123
+
124
+You can now access the dashboard at `http://CLUSTER:19999`, replacing `CLUSTER` with the IP address or hostname of your
125
+k8s cluster.
126
+
127
+If you set up the Netdata Helm chart with `service.type=LoadBalancer`, you can find the external IP for the load
128
+balancer with `kubectl get services`, under the `EXTERNAL-IP` column.
129
+
130
+```bash
131
+kubectl get services
132
+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
133
+cockroachdb ClusterIP None <none> 26257/TCP,8080/TCP 46h
134
+cockroachdb-public ClusterIP 10.245.148.233 <none> 26257/TCP,8080/TCP 46h
135
+kubernetes ClusterIP 10.245.0.1 <none> 443/TCP 47h
136
+netdata LoadBalancer 10.245.160.131 203.0.113.0 19999:32231/TCP 74m
137
+```
138
+
139
+In the above example, access the dashboard by navigating to `http://203.0.113.0:19999`.
140
+
141
+## Update/reinstall the Netdata Helm chart
142
+
143
+If you update the Helm chart's configuration, run `helm upgrade` to redeploy your Netdata service, replacing `netdata`
144
+with the name of the release if you changed it upon installtion:
145
+
146
+```bash
147
+helm upgrade netdata ./netdata-helmchart
148
+```
149
+
150
+## What's next?
151
+
152
+Check out our [Agent's getting started guide](/docs/getting-started.md) for a quick overview of Netdata's capabilities,
153
+especially if you want to change any of the configuration settings for either the parent or child nodes.
154
+
155
+To futher configure Netdata for your cluster, see our [Helm chart repository](https://github.com/netdata/helmchart) and
156
+the [service discovery repository](https://github.com/netdata/agent-service-discovery/).
157
+
158
+[](<>)