docs: Add reciprocal links between ephemerality and identity docs (#21552)
- nodes-ephemerality.md: Add See Also section linking to node-identities.md and vm-templates.md - node-identities.md: Add ephemerality intro explaining node lifecycle concepts - vm-templates.md: Add ephemerality section explaining ephemeral vs permanent nodes - remove-node.md: Fix absolute URL to use relative path These links create a coherent navigation flow between ephemerality, identity, and template documentation.
Costa Tsaousis committed
Jan 13, 2026 at 04:05 UTC
0deb6217c50b479d110617e4ca98838e68904b63
4 files changed
+115
-3
docs/learn/node-identities.md
+48
@@ -8,6 +8,27 @@ How Netdata identifies nodes across Agents, Parents, and Cloud - and why each id
8
9
:::
10
11
+## Node Lifecycle and Ephemerality
12
+
13
+Every node has a **lifecycle** determined by its **ephemerality** setting. By default, all nodes are **permanent** - they are expected to maintain connectivity, and disconnections trigger alerts.
14
+
15
+Ephemeral nodes are designed for dynamic infrastructure:
16
+- No alerts when they disconnect
17
+- Automatic cleanup after configurable timeout
18
+- Perfect for auto-scaling and short-lived workloads
19
+
20
+To change a node's ephemerality, edit `netdata.conf`:
21
+
22
+```ini
23
+[global]
24
+is ephemeral node = yes # Ephemeral - no alerts, auto-cleanup
25
+is ephemeral node = no # Permanent (default) - alerts on disconnect
26
+```
27
+
28
+See [Node Ephemerality](/docs/nodes-ephemerality.md) for detailed configuration options.
29
+
30
+---
31
+
32
Netdata uses several identity mechanisms to uniquely identify nodes, authenticate connections, and track metrics across your infrastructure. Understanding these identities is essential when:
33
34
- Creating VM templates or golden images
@@ -244,3 +265,30 @@ Containers with ephemeral storage get unique GUIDs automatically on each start.
265
No. A node can only exist in one Space. To move a node to a different Space, unclaim it first, then claim to the new Space.
266
267
</details>
268
+
269
+<details>
270
+<summary>Does ephemerality affect my node's identity?</summary>
271
+
272
+No. **Identity** and **ephemerality** are separate concepts:
273
+
274
+- **Identity** (Machine GUID, Node ID) uniquely identifies the node
275
+- **Ephemerality** determines lifecycle behavior (alerts, cleanup)
276
+
277
+A node can be permanent or ephemeral and still have a unique identity. Changing ephemerality does not change or reset identity.
278
+
279
+</details>
280
+
281
+<details>
282
+<summary>Can I change a node's ephemerality after cloning?</summary>
283
+
284
+Yes. Edit `/etc/netdata/netdata.conf` and restart Netdata:
285
+
286
+```ini
287
+[global]
288
+is ephemeral node = yes # Enable ephemeral behavior
289
+is ephemeral node = no # Revert to permanent (default)
290
+```
291
+
292
+Changes apply immediately. Ephemerality is stored as a host label and propagates to Parents and Netdata Cloud.
293
+
294
+</details>
docs/learn/remove-node.md
+6
-2
@@ -115,7 +115,7 @@ is ephemeral node = yes
115
116
:::tip
117
118
-For nodes that are part of streaming configurations, see the [Nodes Ephemerality documentation](https://learn.netdata.cloud/docs/observability-centralization-points/nodes-ephemerality) for more advanced configuration options.
118
+For nodes that are part of streaming configurations, see [Nodes Ephemerality](/docs/nodes-ephemerality.md) for more advanced configuration options.
119
120
:::
121
@@ -136,4 +136,8 @@ To prevent removed nodes from reappearing:
136
137
## Additional Resources
138
139
-For more advanced configuration options with streaming setups, see the [Nodes Ephemerality documentation](https://learn.netdata.cloud/docs/observability-centralization-points/nodes-ephemerality).
139
+For more advanced configuration options with streaming setups, see [Nodes Ephemerality](/docs/nodes-ephemerality.md).
140
+
141
+To avoid removal issues when cloning VMs, see [VM Templates](/docs/learn/vm-templates.md) for proper identity cleanup.
142
+
143
+To understand how node identity affects removal and cleanup, see [Node Identities](/docs/learn/node-identities.md).
docs/learn/vm-templates.md
+55
@@ -41,6 +41,31 @@ To prepare a VM template:
41
3. **Keep claim.conf** - Enable auto-claiming (optional)
42
4. **Convert to template** - Without starting Netdata
43
44
+## Node Types: Ephemeral vs Permanent
45
+
46
+VMs cloned from templates can be configured as **ephemeral** or **permanent** nodes. This affects how Netdata handles disconnections, alerts, and cleanup.
47
+
48
+| Type | Behavior | Use Case |
49
+|------|-----------|----------|
50
+| **Ephemeral** | No alerts on disconnect, auto-cleanup after 24h | Auto-scaling instances, spot VMs, short-lived workloads |
51
+| **Permanent** | Alerts trigger on disconnect | Long-running production systems |
52
+
53
+### Configuring Ephemeral Nodes in Templates
54
+
55
+To make cloned VMs ephemeral by default, add to `/etc/netdata/netdata.conf` **in the template**:
56
+
57
+```ini
58
+[global]
59
+is ephemeral node = yes
60
+```
61
+
62
+### When to Use Each Type
63
+
64
+- **Ephemeral**: Auto-scaling groups, spot instances, Kubernetes pod templates, CI/CD build agents
65
+- **Permanent**: Production database servers, core infrastructure, stable monitoring targets
66
+
67
+See [Node Ephemerality](/docs/nodes-ephemerality.md) for full documentation.
68
+
69
## Files to Delete
70
71
:::danger
@@ -278,3 +303,33 @@ No. Containers start with empty volumes, so each gets a unique identity automati
303
The token only allows claiming to your Space. It cannot read data or modify other nodes. Treat it like an API key - don't expose publicly, but it's safe in private templates.
304
305
</details>
306
+
307
+<details>
308
+<summary>Should I make my template VMs ephemeral or permanent?</summary>
309
+
310
+Use **ephemeral** for auto-scaling groups, spot instances, or any VMs that may terminate at any time. Use **permanent** for long-running production systems where disconnections indicate problems.
311
+
312
+Configure in the template before conversion:
313
+
314
+```ini
315
+# For ephemeral (auto-scaling, spot instances)
316
+[global]
317
+is ephemeral node = yes
318
+
319
+# For permanent (default - production systems)
320
+[global]
321
+is ephemeral node = no
322
+```
323
+
324
+See [Node Types](/docs/learn/vm-templates.md#node-types-ephemeral-vs-permanent) for full guidance.
325
+
326
+</details>
327
+
328
+<details>
329
+<summary>Does ephemerality affect cleanup behavior?</summary>
330
+
331
+Yes. Ephemeral nodes are automatically cleaned up after 24 hours of disconnection (configurable via `cleanup ephemeral hosts after`). Permanent nodes never auto-cleanup - they remain visible until manually removed, or their metrics are fully rotated due to retention.
332
+
333
+This prevents dashboards from cluttering with stale auto-scaled instances while preserving long-term monitoring data for permanent infrastructure.
334
+
335
+</details>
docs/nodes-ephemerality.md
+6
-1
@@ -158,5 +158,10 @@ flowchart TD
158
class E alert
159
class F alert
160
class G database
161
- class H database
161
+ class H database
162
```
163
+
164
+## See Also
165
+
166
+- [Node Identities](/docs/learn/node-identities.md) - Understand how node identity works alongside ephemerality
167
+- [VM Templates](/docs/learn/vm-templates.md) - Configure ephemerality in VM templates for auto-scaling groups