Add Remove Node guide (#20549)
Kanela committed
Jun 25, 2025 at 20:58 UTC
fe4aee6d0221b6380d6376aa053e0ff2546c7f68
1 file changed
+139
docs/learn/remove-node.md
new
+139
@@ -0,0 +1,139 @@
1
+# Removing a node from your Netdata Cloud Space
2
+
3
+You can remove a node from your Space in Netdata Cloud, but the process depends on the node's current state and requires different approaches for different scenarios.
4
+
5
+## Understanding Node States
6
+
7
+Before attempting to remove a node, it's important to understand what each status means:
8
+
9
+* **Online**: Node is actively connected and streaming data
10
+* **Stale**: Node is a child that stopped streaming to its parent, but the parent still has its historical data
11
+* **Offline**: Node is disconnected and no longer has data available for querying
12
+
13
+<details>
14
+<summary><strong>Why Can't I Delete Stale Nodes?</strong></summary><br/>
15
+
16
+**Stale means this node is a Child that has stopped streaming to its Parent, but the Parent still retains its historical data.**
17
+
18
+You can't delete a Stale node because the Parent is alive/connected to the Cloud and has data for the Stale node. The UI disables the "Remove" option to protect this historical data and maintain the parent-child relationship integrity.<br/>
19
+
20
+This is why stale nodes show "Delete is disabled" - the system prevents deletion while the parent node still holds queryable metrics data for that child.<br/>
21
+</details>
22
+
23
+
24
+## Quick Decision Guide
25
+
26
+**What's your node status?**
27
+
28
+```
29
+🔴 Node shows "Offline" → Use Method 1 (UI Method)
30
+🟡 Node shows "Stale" → Use Method 2 (CLI Method) ← MOST COMMON ISSUE
31
+📦 Multiple nodes to remove → Use Method 3 (Bulk Operations)
32
+```
33
+
34
+:::note
35
+
36
+You need **Admin** role in your Space to remove nodes. The CLI method requires a system with Netdata Agent installed.
37
+
38
+:::
39
+
40
+## Removal Methods
41
+
42
+<details>
43
+<summary><strong>Method 1: Removing Offline Nodes (UI Method)</strong></summary><br/>
44
+
45
+**When to use**: Your node shows as **Offline** status in Netdata Cloud.
46
+
47
+**Steps**:
48
+1. Stop the Netdata Agent on the node you want to remove
49
+2. In Netdata Cloud, go to **Space Settings > Nodes**
50
+3. Locate the offline node in the list
51
+4. Select the trash icon to remove it
52
+
53
+:::note
54
+
55
+The **Remove** option is only available in the **Space Settings** view. It will appear disabled in the "All Nodes" room or other parts of the UI.
56
+
57
+:::
58
+
59
+</details>
60
+
61
+<details>
62
+<summary><strong>Method 2: Removing Stale Nodes (CLI Method)</strong></summary><br/>
63
+
64
+**When to use**: Your node shows as **Stale** status and UI shows "Delete is disabled".
65
+
66
+**Step 1: Get the Node UUID**
67
+1. In Netdata Cloud, navigate to the stale node
68
+2. Click the **node information (i)** button
69
+3. Click **"View node info in JSON"**
70
+4. Copy the UUID from the JSON data (it will be copied to your clipboard)
71
+
72
+**Step 2: Remove the Stale Node**
73
+Run this command on any node with Netdata Agent installed:
74
+
75
+```bash
76
+netdatacli remove-stale-node <UUID>
77
+```
78
+
79
+Replace `<UUID>` with the node's actual identifier from Step 1.
80
+
81
+**What happens next**: The command unregisters and removes the node from the cloud. The node status should change from **Stale → Offline** in Netdata Cloud, then you can remove it via the UI method if needed.
82
+
83
+</details>
84
+
85
+<details>
86
+<summary><strong>Method 3: Bulk Operations</strong></summary><br/>
87
+
88
+**When to use**: You need to remove multiple nodes at once.
89
+
90
+You can use the remove-stale-node command with different identifiers:
91
+
92
+```bash
93
+# Using machine GUID
94
+netdatacli remove-stale-node <machine_guid>
95
+
96
+# Using hostname
97
+netdatacli remove-stale-node <hostname>
98
+
99
+# Remove ALL stale nodes (use with extreme caution)
100
+netdatacli remove-stale-node ALL_NODES
101
+```
102
+
103
+</details>
104
+
105
+## Prevention and Best Practices
106
+
107
+### Auto-scaling/Spot Instances
108
+For environments with auto-scaling cloud instances or spot instances that get terminated frequently, consider configuring nodes as ephemeral:
109
+
110
+```ini
111
+# In netdata.conf
112
+[global]
113
+is ephemeral node = yes
114
+```
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.
119
+
120
+:::
121
+
122
+### Prevent Automatic Reconnection
123
+To prevent removed nodes from reappearing:
124
+* Remove or clear any existing `claim.conf` file
125
+* Clear related environment variables on the node
126
+
127
+## Troubleshooting
128
+
129
+**"Delete is disabled"**: The node is Stale, not Offline. Use Method 2 (CLI approach).
130
+
131
+**"Command not found"**: Ensure you're running `netdatacli` on a system with Netdata Agent installed.
132
+
133
+**"Permission denied"**: You need **Admin** role in the Space to remove nodes.
134
+
135
+**Node reappears after removal**: The agent may still be running and configured to reconnect. Stop the agent and clear claim configuration.
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).