@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 180 lines 6.73 KB
Rendered Raw
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** (Live): Node is actively connected and streaming data
10 * **Stale**: Node disconnected, but a Parent connected to Netdata Cloud has its historical data
11 * **Offline** (Unreachable): Node is disconnected and no longer has data available for querying
12
13 For a complete explanation of node states, state transitions, and when nodes move between states, see [Node States and Transitions](/docs/netdata-cloud/node-states-and-transitions.md).
14
15 <details>
16 <summary><strong>Why Can't I Delete Stale Nodes?</strong></summary><br/>
17
18 **Stale means this node is a Child that has stopped streaming to its Parent, but the Parent still retains its historical data.**
19
20 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/>
21
22 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/>
23 </details>
24
25
26 ## Quick Decision Guide
27
28 **What type of node is it?**
29
30 ```
31 🔴 Standalone node (connects directly to Cloud) → Removing Standalone Nodes
32 🟡 Child node (streams through a Parent Agent) → Removing Child Nodes
33 ```
34
35 **Then, what's the node status?**
36
37 ```
38 📴 Node shows "Offline" → Use the UI removal method
39 🟡 Node shows "Stale" → Use the CLI method
40 ```
41
42 :::note
43
44 You need **Admin** role in your Space to remove nodes. The CLI method requires a system with Netdata Agent installed.
45
46 :::
47
48 ## Singular or Standalone Nodes
49
50 These are nodes that connect directly to Netdata Cloud without streaming through a Parent Agent.
51
52 <details>
53 <summary><strong>Removing Offline Standalone Nodes (UI Method)</strong></summary><br/>
54
55 **When to use**: Your standalone node shows as **Offline** status in Netdata Cloud.
56
57 :::note
58
59 Stale status does not apply to standalone nodes — stale specifically means a child node stopped streaming to its parent.
60
61 :::
62
63 **Steps**:
64 1. Stop the Netdata Agent on the node you want to remove
65 2. In Netdata Cloud, go to **Space Settings > Nodes** (click the ⚙️ cog icon below the spaces list).
66 3. Locate the offline node in the list
67 4. Select the trash icon to remove it
68
69 :::note
70
71 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.
72
73 :::
74
75 </details>
76
77 ## Child Nodes
78
79 These are nodes that stream metrics through a Parent Agent. When a child node stops streaming to its parent, it becomes **Stale**.
80
81 <details>
82 <summary><strong>Removing Stale Child Nodes (CLI Method)</strong></summary><br/>
83
84 **When to use**: Your child node shows as **Stale** status and UI shows "Delete is disabled".
85
86 **Step 1: Get the Node Identifier**
87 1. In Netdata Cloud, navigate to the stale node
88 2. Click the **node information (i)** button
89 3. Click **"View node info in JSON"**
90 4. Copy the identifier from the JSON data (node_id, machine_guid, or hostname)
91
92 **Step 2: Remove the Stale Node**
93 Run this command on the **Parent Agent** that holds the stale child's data:
94
95 ```bash
96 netdatacli remove-stale-node <identifier>
97 ```
98
99 Replace `<identifier>` with one of:
100 - `node_id` - The node's unique identifier
101 - `machine_guid` - The machine GUID from the node info
102 - `hostname` - The node's hostname
103
104 :::important
105
106 This command must be run on the **Parent Agent** that holds the node's metrics data, not on any arbitrary machine with Netdata Agent installed.
107
108 :::
109
110 :::note
111
112 If a node is represented by multiple Parent Agents in an HA setup, this command must be executed on **each** Parent Agent.
113
114 :::
115
116 **What happens next**: The command marks the node as ephemeral and removes it so it is no longer available for queries, from both the Netdata Agent dashboard and Netdata Cloud. The node is fully removed — it does not transition to Offline status.
117
118 </details>
119
120 <details>
121 <summary><strong>Removing All Child Nodes from a Parent</strong></summary><br/>
122
123 **When to use**: You need to remove all stale child nodes from a Parent Agent at once.
124
125 ```bash
126 # Remove ALL stale child nodes from this Parent (use with extreme caution)
127 netdatacli remove-stale-node ALL_NODES
128 ```
129
130 :::caution
131
132 This command affects all disconnected child nodes on the Parent Agent where it is run. Use with caution in production environments.
133
134 :::
135
136 </details>
137
138 ## Prevention and Best Practices
139
140 ### Auto-scaling/Spot Instances
141 For environments with auto-scaling cloud instances or spot instances that get terminated frequently, consider configuring nodes as ephemeral:
142
143 ```ini
144 # In netdata.conf
145 [global]
146 is ephemeral node = yes
147 ```
148
149 :::tip
150
151 For nodes that are part of streaming configurations, see [Nodes Ephemerality](/docs/nodes-ephemerality.md) for more advanced configuration options.
152
153 :::
154
155 ### Prevent Automatic Reconnection
156 To prevent removed nodes from reappearing:
157 * Remove or clear any existing `claim.conf` file
158 * Clear related environment variables on the node
159
160 ## Troubleshooting
161
162 **"Delete is disabled"**: The node is Stale, not Offline. Use the CLI approach for child nodes.
163
164 **"Command not found"**: Ensure you're running `netdatacli` on a system with Netdata Agent installed.
165
166 **"Permission denied"**: You need **Admin** role in the Space to remove nodes.
167
168 **"Node '\<name>' (machine guid: \<guid>) is our localhost - not changing it"**: The machine GUID you provided belongs to the agent where you are running `netdatacli`—in this procedure, that should be the Parent Agent—not the stale child node you want to remove. This usually happens when you accidentally copy the Parent's own machine GUID instead of the stale child's. Verify you are using the correct machine GUID by checking the stale child's node info in Netdata Cloud — the GUID must belong to the disconnected child, not the Parent Agent you are logged into.
169
170 **Node reappears after removal**: The agent may still be running and configured to reconnect. Stop the agent and clear claim configuration.
171
172 ## Additional Resources
173
174 For a complete reference on node states and transitions, see [Node States and Transitions](/docs/netdata-cloud/node-states-and-transitions.md).
175
176 For more advanced configuration options with streaming setups, see [Nodes Ephemerality](/docs/nodes-ephemerality.md).
177
178 To avoid removal issues when cloning VMs, see [VM Templates](/docs/learn/vm-templates.md) for proper identity cleanup.
179
180 To understand how node identity affects removal and cleanup, see [Node Identities](/docs/learn/node-identities.md).