docs: add FAQ on vnode rename and node identity (#22278)
docs: add FAQ entry on vnode rename and node identity Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com>
nedi-app[bot] committed
Apr 30, 2026 at 10:24 UTC
cff4b03fa28b36c4dc97d8f129b893dfd344a8ea
1 file changed
+13
docs/learn/node-identities.md
+13
@@ -292,3 +292,16 @@ is ephemeral node = no # Revert to permanent (default)
292
Changes apply immediately. Ephemerality is stored as a host label and propagates to Parents and Netdata Cloud.
293
294
</details>
295
+
296
+<details>
297
+<summary>Does renaming a virtual node change its identity?</summary>
298
+
299
+A virtual node's identity is determined by its **`guid`** field — not its `hostname` or `name`. The fields behave as follows:
300
+
301
+- **`guid`** — This is the vnode's identity. Changing it creates an entirely new node in Netdata Cloud. The old vnode's historical data remains under the old GUID but is no longer associated with the new one.
302
+- **`hostname`** — This is used as the internal lookup key in the Agent and as the display name in dashboards. Changing `hostname` while keeping the same `guid` renames the display without creating a new node identity.
303
+- **`name`** — The Agent ignores this field. When set to a value different from `hostname`, the Agent logs a warning and overrides it with `hostname`.
304
+
305
+**To preserve data continuity when renaming a vnode**, change only the `hostname` field in the YAML config file under `/etc/netdata/vnodes/` and keep the `guid` unchanged. If a true identity change is needed, accept that historical data belongs to the old identity.
306
+
307
+</details>