1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
# Deployment strategies
Netdata can be used to monitor all kinds of infrastructure, from stand-alone tiny IoT devices to complex hybrid setups
combining on-premise and cloud infrastructure, mixing bare-metal servers, virtual machines and containers.
There are 3 components to structure your Netdata ecosystem:
1. **Netdata Agents**
To monitor the physical or virtual nodes of your infrastructure, including all applications and containers running on them.
Netdata Agents are Open-Source, licensed under GPL v3+.
2. **Netdata Parents**
To create data centralization points within your infrastructure, to offload Netdata Agents functions from your production
systems, to provide high-availability of your data, increased data retention and isolation of your nodes.
Netdata Parents are implemented using the Netdata Agent software. Any Netdata Agent can be an Agent for a node and a Parent
for other Agents, at the same time.
It is recommended to set up multiple Netdata Parents. They will all seamlessly be integrated by Netdata Cloud into one monitoring solution.
3. **Netdata Cloud**
Our SaaS, combining all your infrastructure, all your Netdata Agents and Parents, into one uniform, distributed,
scalable, monitoring database, offering advanced data slicing and dicing capabilities, custom dashboards, advanced troubleshooting
tools, user management, centralized management of alerts, and more.
The Netdata Agent is a highly modular software piece, providing data collection via numerous plugins, an in-house crafted time-series
database, a query engine, health monitoring and alerts, machine learning and anomaly detection, metrics exporting to third party systems.
## Deployment Options Overview
This section provides a quick overview of a few common deployment options. The next sections go into configuration examples and further reading.
### Stand-alone Deployment
To help our users have a complete experience of Netdata when they install it for the first time, a Netdata Agent with default configuration
is a complete monitoring solution out of the box, having all these features enabled and available.
The Agent will act as a _stand-alone_ Agent by default, and this is great to start out with for small setups and home labs. By [connecting each Agent to Cloud](https://github.com/netdata/netdata/blob/master/claim/README.md), you can see an overview of all your nodes, with aggregated charts and centralized alerting, without setting up a Parent.
![image](https://github.com/netdata/netdata/assets/116741/6a638175-aec4-4d46-85a6-520c283ab6a8)
### Parent – Child Deployment
An Agent connected to a Parent is called a _Child_. It will _stream_ metrics to its Parent. The Parent can then take care of storing metrics on behalf of that node (with longer retention), handle metrics queries for showing dashboards, and provide alerting.
When using Cloud, it is recommended that just the Parent is connected to Cloud. Child Agents can then be configured to have short retention, in RAM instead of on Disk, and have alerting and other features disabled. Because they don't need to connect to Cloud themselves, those children can then be further secured by not allowing outbound traffic.
![image](https://github.com/netdata/netdata/assets/116741/cb65698d-a6b7-43ee-a2d1-c30d0a46f084)
This setup allows for leaner Child nodes and is good for setups with more than a handful of nodes. Metrics data remains accessible if the Child node is temporarily unavailable or decommissioned, although there is no failover in case the Parent becomes unavailable.
### Active–Active Parent Deployment
For high availability, Parents can be configured to stream data for their children between them, and keep the data sets in sync. Child Agents are configured with the addresses of both Parent Agents, but will only stream to one of them at a time. When that Parent becomes unavailable, it reconnects to another. When the first Parent becomes available again, that Parent will catch up by receiving the backlog from the second.
With both Parent Agents connected to Cloud, Cloud will route queries to either Parent transparently, depending on their availability. Alerts trigger on either Parent will stream to Cloud, and Cloud will deduplicate and debounce state changes to prevent spurious notifications.
![image](https://github.com/netdata/netdata/assets/116741/6ae2b10c-7f7d-4503-aac4-0a9381c6f80b)
## Configuration Details
### Stand-alone Deployment
The stand-alone setup is configured out of the box with reasonable defaults, but please consult our [configuration documentation](https://github.com/netdata/netdata/blob/master/docs/cloud/cheatsheet.md) for details, including the overview of [common configuration changes](https://github.com/netdata/netdata/blob/master/docs/configure/common-changes.md).
### Parent – Child Deployment
For setups involving Child and Parent Agents, the Agents need to be configured for [_streaming_](https://github.com/netdata/netdata/blob/master/streaming/README.md), through the configuration file `stream.conf`. This will instruct the Child to stream data to the Parent and the Parent to accept streaming connections for one or more Child Agents. To secure this connection, both need set up a shared API key (to replace the string `API_KEY` in the examples below). Additionally, the Child is configured with one or more addresses of Parent Agents (`PARENT_IP_ADDRESS`).
An API key is a key created with `uuidgen` and is used for authentication and/or customization in the Parent side. I.e. a Child will stream using the API key, and a Parent is configured to accept connections from Child, but can also apply different options for children by using multiple different API keys. The easiest setup uses just one API key for all Child Agents.
#### Child config
As mentioned above, the recommendation is to not claim the Child to Cloud directly during your setup, avoiding establishing an [ACLK](https://github.com/netdata/netdata/blob/master/aclk/README.md) connection.
To reduce the footprint of the Netdata Agent on your production system, some capabilities can be switched OFF on the Child and kept ON on the Parent. In this example, Machine Learning and Alerting are disabled in the Child, so that the Parent can take the load. We also use RAM instead of disk to store metrics with limited retention, covering temporary network issues.
##### netdata.conf
On the child node, edit `netdata.conf` by using the edit-config script: `/etc/netdata/edit-config netdata.conf` set the following parameters:
```yaml
[db]
# https://learn.netdata.cloud/docs/agent/database
# none = no retention, ram = some retention in ram
mode = ram
# The retention in seconds.
# This provides some tolerance to the time the child has to find a parent in
# order to transfer the data. For IoT this can be lowered to 120.
retention = 1200
# The granularity of metrics, in seconds.
# You may increase this to lower CPU resources.
update every = 1
[ml]
# Disable Machine Learning
enabled = no
[health]
# Disable Health Checks (Alerting)
enabled = no
[web]
# Disable remote access to the local dashboard
bind to = lo
[plugins]
# Uncomment the following line to disable all external plugins on extreme
# IoT cases by default.
# enable running new plugins = no
```
##### stream.conf
To edit `stream.conf`, again use the edit-config script: `/etc/netdata/edit-config stream.conf`.
Set the following parameters:
```yaml
[stream]
# Stream metrics to another Netdata
enabled = yes
# The IP and PORT of the parent
destination = PARENT_IP_ADDRESS:19999
# The shared API key, generated by uuidgen
api key = API_KEY
```
#### Parent config
For the Parent, besides setting up streaming, the example will also provide an example configuration of multiple [tiers](https://github.com/netdata/netdata/blob/master/database/engine/README.md#tiering) of metrics [storage](https://github.com/netdata/netdata/blob/master/docs/store/change-metrics-storage.md), for 10 children, with about 2k metrics each.
- 1s granularity at tier 0 for 1 week
- 1m granularity at tier 1 for 1 month
- 1h granularity at tier 2 for 1 year
Requiring:
- 25GB of disk
- 3.5GB of RAM (2.5GB under pressure)
##### netdata.conf
On the Parent, edit `netdata.conf` with `/etc/netdata/edit-config netdata.conf` and set the following parameters:
```yaml
[db]
mode = dbengine
storage tiers = 3
# To allow memory pressure to offload index from ram
dbengine page descriptors in file mapped memory = yes
# storage tier 0
update every = 1
dbengine multihost disk space MB = 12000
dbengine page cache size MB = 1400
# storage tier 1
dbengine tier 1 page cache size MB = 512
dbengine tier 1 multihost disk space MB = 4096
dbengine tier 1 update every iterations = 60
dbengine tier 1 backfill = new
# storage tier 2
dbengine tier 2 page cache size MB = 128
dbengine tier 2 multihost disk space MB = 2048
dbengine tier 2 update every iterations = 60
dbengine tier 2 backfill = new
[ml]
# Enabled by default
# enabled = yes
[health]
# Enabled by default
# enabled = yes
[web]
# Enabled by default
# bind to = *
```
##### stream.conf
On the Parent node, edit `stream.conf` with `/etc/netdata/edit-config stream.conf`, and then set the following parameters:
```yaml
[API_KEY]
# Accept metrics streaming from other Agents with the specified API key
enabled = yes
```
### Active–Active Parent Deployment
In order to setup active–active streaming between Parent 1 and Parent 2, Parent 1 needs to be instructed to stream data to Parent 2 and Parent 2 to stream data to Parent 1. The Child Agents need to be configured with the addresses of both Parent Agents. The Agent will only connect to one Parent at a time, falling back to the next if the previous failed. These examples use the same API key between Parent Agents as for connections from Child Agents.
On both Netdata Parent and all Child Agents, edit `stream.conf` with `/etc/netdata/edit-config stream.conf`:
##### stream.conf on Parent 1
```yaml
[stream]
# Stream metrics to another Netdata
enabled = yes
# The IP and PORT of Parent 2
destination = PARENT_2_IP_ADDRESS:19999
# This is the API key for the outgoing connection to Parent 2
api key = API_KEY
[API_KEY]
# Accept metrics streams from Parent 2 and Child Agents
enabled = yes
```
##### stream.conf on Parent 2
```yaml
[stream]
# Stream metrics to another Netdata
enabled = yes
# The IP and PORT of Parent 1
destination = PARENT_1_IP_ADDRESS:19999
api key = API_KEY
[API_KEY]
# Accept metrics streams from Parent 1 and Child Agents
enabled = yes
```
##### stream.conf on Child Agents
```yaml
[stream]
# Stream metrics to another Netdata
enabled = yes
# The IP and PORT of the parent
destination = PARENT_1_IP_ADDRESS:19999 PARENT_2_IP_ADDRESS:19999
# The shared API key, generated by uuidgen
api key = API_KEY
```
## Further Reading
We strongly recommend the following configuration changes for production deployments:
1. Understand Netdata's [security and privacy design](https://github.com/netdata/netdata/blob/master/docs/netdata-security.md) and
[secure your nodes](https://github.com/netdata/netdata/blob/master/docs/category-overview-pages/secure-nodes.md)
To safeguard your infrastructure and comply with your organization's security policies.
2. Set up [streaming and replication](https://github.com/netdata/netdata/blob/master/streaming/README.md) to:
- Offload Netdata Agents running on production systems and free system resources for the production applications running on them.
- Isolate production systems from the rest of the world and improve security.
- Increase data retention.
- Make your data highly available.
3. [Optimize the Netdata Agents system utilization and performance](https://github.com/netdata/netdata/blob/master/docs/guides/configure/performance.md)
To save valuable system resources, especially when running on weak IoT devices.
We also suggest that you:
1. [Use Netdata Cloud to access the dashboards](https://github.com/netdata/netdata/blob/master/docs/quickstart/infrastructure.md)
For increased security, user management and access to our latest tools for advanced dashboarding and troubleshooting.
2. [Change how long Netdata stores metrics](https://github.com/netdata/netdata/blob/master/docs/store/change-metrics-storage.md)
To control Netdata's memory use, when you have a lot of ephemeral metrics.
3. [Use host labels](https://github.com/netdata/netdata/blob/master/docs/guides/using-host-labels.md)
To organize systems, metrics, and alerts.
|