docs: Add unclaim/reclaim node guide (#21539)
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> Co-authored-by: ilyam8 <ilya@netdata.cloud>
Kanela committed
Jan 20, 2026 at 17:52 UTC
dfa923c7f0ff9392ea5cedc7082731324e3932bf
2 files changed
+127
docs/.map/map.csv
+1
@@ -96,6 +96,7 @@ https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/authentication
96
https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/view-plan-and-billing.md,Netdata Plans & Billing,Published,Netdata Cloud,,
97
https://github.com/netdata/netdata/edit/master/src/aclk/README.md,Agent-Cloud Link (ACLK),Published,Netdata Cloud,,The Agent-Cloud link (ACLK) is the mechanism responsible for connecting a Netdata agent to Netdata Cloud.
98
https://github.com/netdata/netdata/edit/master/docs/learn/remove-node.md,Remove Agent,Published,Netdata Cloud,,
99
+https://github.com/netdata/netdata/edit/master/docs/learn/unclaim-reclaim-node.md,Unclaim and Reclaim a Node,Published,Netdata Cloud,,
100
https://github.com/netdata/netdata/edit/master/docs/delete/netdata/account.md,Account Deletion,Published,Netdata Cloud,,
101
,,,,,
102
https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/README.md,Netdata Cloud On-Prem,Published,Netdata Cloud On-Prem,,
docs/learn/unclaim-reclaim-node.md
new
+126
@@ -0,0 +1,126 @@
1
+# Unclaiming and Reclaiming a Node
2
+
3
+:::note
4
+
5
+**What's the difference between unclaiming/reclaiming and removing a node?**
6
+
7
+| Action | What it does | Agent status |
8
+|-----------------------|-------------------------------------------------------|-----------------------------------------|
9
+| **Unclaim & Reclaim** | Disconnect from current Space, connect to a new Space | Agent keeps running |
10
+| **Remove** | Permanently delete node from Netdata Cloud | Agent may keep running but disconnected |
11
+
12
+If you want to **move a node to a different Space**, use the **unclaim and reclaim** process on this page.
13
+
14
+If you want to **permanently remove a node** from Netdata Cloud entirely, see our guide: [Removing a node from your Netdata Cloud Space](/docs/learn/remove-node.md)
15
+
16
+:::
17
+
18
+This guide covers how to move a node from one Space to another without removing it from Netdata Cloud entirely.
19
+
20
+## Why Move a Node Between Spaces?
21
+
22
+You might need to move a node to a different Space when:
23
+
24
+- Reorganizing your infrastructure monitoring structure
25
+- Transferring node ownership between teams or departments
26
+- Consolidating multiple Spaces into one
27
+
28
+## Prerequisites
29
+
30
+- The node must have Netdata Agent installed
31
+- You need the claiming token and room keys for the **new** Space
32
+- Access to the node via SSH or terminal
33
+
34
+:::info
35
+
36
+**Need a claim token?** See **[Regenerate Claiming Token](/src/claim/README.md#regenerate-claiming-token)** to generate a new token for your Space (Space Administrator required).
37
+
38
+:::
39
+
40
+## Step 1: Unclaim from Current Space
41
+
42
+See our **[Reconnect Agent](/src/claim/README.md#reconnect-agent)** guide for the exact commands to:
43
+
44
+- Remove the Cloud connection directory (Linux)
45
+- Remove connection files and recreate container (Docker)
46
+
47
+:::warning
48
+
49
+**Restart the agent after removing cloud.d/**
50
+
51
+If you don't restart the agent after removing `/var/lib/netdata/cloud.d/`, the node will remain connected to Netdata Cloud until the agent restarts.
52
+
53
+To apply the unclaiming change immediately, run:
54
+
55
+```bash
56
+sudo systemctl restart netdata
57
+```
58
+
59
+:::
60
+
61
+## Step 2: Reclaim to New Space
62
+
63
+### Option 1: Quick Reclaim (Recommended)
64
+
65
+Run the standard claim command with your new Space's token:
66
+
67
+```bash
68
+bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token YOUR_NEW_TOKEN --claim-rooms YOUR_ROOMS --claim-url https://app.netdata.cloud
69
+```
70
+
71
+### Option 2: Configuration File
72
+
73
+Create `/INSTALL_PREFIX/etc/netdata/claim.conf` with:
74
+
75
+```bash
76
+[global]
77
+ url = https://app.netdata.cloud
78
+ token = NETDATA_CLOUD_SPACE_TOKEN
79
+ rooms = ROOM_KEY1,ROOM_KEY2
80
+```
81
+
82
+Then restart the agent or run:
83
+
84
+```bash
85
+netdatacli reload-claiming-state
86
+```
87
+
88
+### Option 3: Environment Variables
89
+
90
+For Docker/container deployments, set:
91
+
92
+```bash
93
+NETDATA_CLAIM_TOKEN=YOUR_NEW_TOKEN
94
+NETDATA_CLAIM_ROOMS=ROOM_KEY1,ROOM_KEY2
95
+```
96
+
97
+## Verification
98
+
99
+After reclaiming, verify the node appears in:
100
+
101
+- Your new Space in Netdata Cloud
102
+- The Rooms you specified
103
+- The node status shows as "Online"
104
+
105
+## Troubleshooting
106
+
107
+**Node doesn't appear in new Space:**
108
+
109
+- Verify the claim token is correct for the new Space
110
+- Check `/var/lib/netdata/cloud.d/` was removed before reclaiming
111
+- Review agent logs using:
112
+ - `journalctl --namespace netdata -b 0 | grep -i CLAIM`
113
+ - or:
114
+ - `grep -i CLAIM /var/log/netdata/daemon.log`
115
+
116
+**Reconnection fails:**
117
+
118
+- Check connection status: `curl http://localhost:19999/api/v1/aclk`
119
+- Ensure the agent has internet access to `app.netdata.cloud`
120
+- Check for firewall blocking port 443
121
+
122
+## Related Documentation
123
+
124
+- [Remove a node from Netdata Cloud entirely](/docs/learn/remove-node.md) - For permanent node removal
125
+- [Connect Agent to Cloud](/src/claim/README.md#connect-agent-to-cloud) - Initial connection setup
126
+- [Reconnect Agent](/src/claim/README.md#reconnect-agent) - Linux/ Docker-based installations