[PR #6434] Add explicit peer kind support to Management API #25705

Open
opened 2026-08-05 07:06:22 -04:00 by saavagebueno · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/netbirdio/netbird/pull/6434
Author: @ramphex
Created: 6/15/2026
Status: 🔄 Open

Base: mainHead: fix/peers-kind


📝 Commits (1)

  • 1c4c031 Add peer kind API support

📊 Changes

10 files changed (+178 additions, -10 deletions)

View changed files

📝 management/server/account_test.go (+2 -1)
📝 management/server/http/handlers/peers/peers_handler.go (+11 -0)
📝 management/server/http/handlers/peers/peers_handler_test.go (+34 -1)
📝 management/server/peer.go (+8 -1)
📝 management/server/peer/peer.go (+27 -0)
📝 management/server/peer_test.go (+39 -0)
📝 management/server/store/sql_store.go (+4 -3)
📝 management/server/store/store.go (+3 -0)
📝 shared/management/http/api/openapi.yml (+13 -0)
📝 shared/management/http/api/types.gen.go (+37 -4)

📄 Description

Describe your changes

This PR adds explicit peer kind support to the Management API so peers can be classified as auto, device, or server.

Today, the dashboard has to infer peer type from enrollment behavior: peers enrolled with setup keys are treated as servers, and peers enrolled through SSO are treated as user devices. That inference is probably correct for most installations most of the time, but it is not always true. Some setup-key peers are regular devices, and some SSO-enrolled peers may function as servers, shared infrastructure, or unattended systems. Using enrollment method as the only source of truth makes the implementation clunky and limits the dashboard’s ability to represent the user’s actual environment.

This PR keeps the current behavior compatible by making auto the default value. In auto mode, dashboards and clients can continue using the existing inference logic. Newer dashboards can optionally let users override the classification by setting kind to device or server.

Changes included:

  • Adds a peer Kind field in the management server model.
  • Supports three values: auto, device, and server.
  • Defaults existing and new peers to auto.
  • Adds a store migration to backfill the new kind field on existing peer records.
  • Includes kind in peer list and single-peer API responses.
  • Accepts optional kind updates through the peer update API.
  • Validates invalid peer kind values server-side and rejects them with an invalid argument error.
  • Updates the optimized/raw SQL account loader so peer kind is loaded consistently across store paths.
  • Updates the OpenAPI schema and generated API types for the new field.
  • Adds tests for valid peer kind updates, invalid peer kind rejection, persistence, preservation when omitted, migration/default behavior, and account copy/store consistency.

This is intended to support the companion dashboard change that restores the combined Peers page and allows the UI to respect explicit peer type when the backend provides it.

Supports dashboard issue: https://github.com/netbirdio/dashboard/issues/663
Supports dashboard PR: https://github.com/netbirdio/dashboard/pull/668

Issue #663 reports that the split Peers UI reduced functionality by forcing users to move between separate User Devices and Servers pages instead of working from one complete peer list. This API change addresses the underlying classification limitation that made the split awkward: the existing server/device distinction is inferred from enrollment method, which is useful as a default but not always accurate.

Stack

Companion dashboard PR: https://github.com/netbirdio/dashboard/pull/668

Checklist

  • Is it a bug fix
  • Is a typo/documentation fix
  • Is a feature enhancement
  • It is a refactor
  • Created tests that fail without the change (if possible)
  • This change does not modify the public API, gRPC protocols, functionality behavior, CLI / service flags, or introduce a new feature — OR I have discussed it with the NetBird team beforehand (link the issue / Slack thread in the description). See CONTRIBUTING.md.

Because this adds a public REST API field, I left the public API checklist item unchecked unless maintainers consider the linked dashboard issue/PR sufficient prior discussion.

By submitting this pull request, you confirm that you have read and agree to the terms of the Contributor License Agreement.

Documentation

Select exactly one:

  • I added/updated documentation for this change
  • Documentation is not needed for this change (explain why)

This change adds a small Management API field used by the dashboard to classify peers as automatic, device, or server. It does not introduce a new setup flow, operator configuration step, CLI flag, or user-facing self-hosting procedure. The dashboard companion PR presents the relevant behavior directly in the UI through the Peers page controls and peer detail field.

Docs PR URL (required if "docs added" is checked)

Paste the PR link from https://github.com/netbirdio/docs here:

https://github.com/netbirdio/docs/pull/__

Summary by CodeRabbit

  • New Features
    • Peers can now be classified with a kind field (auto, device, or server)
    • The kind field is included in peer API responses and can be updated
    • Invalid kind values are rejected with appropriate error responses

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/netbirdio/netbird/pull/6434 **Author:** [@ramphex](https://github.com/ramphex) **Created:** 6/15/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `fix/peers-kind` --- ### 📝 Commits (1) - [`1c4c031`](https://github.com/netbirdio/netbird/commit/1c4c031c8a6a7d3048ec9592cf66d8b1d4dae2ab) Add peer kind API support ### 📊 Changes **10 files changed** (+178 additions, -10 deletions) <details> <summary>View changed files</summary> 📝 `management/server/account_test.go` (+2 -1) 📝 `management/server/http/handlers/peers/peers_handler.go` (+11 -0) 📝 `management/server/http/handlers/peers/peers_handler_test.go` (+34 -1) 📝 `management/server/peer.go` (+8 -1) 📝 `management/server/peer/peer.go` (+27 -0) 📝 `management/server/peer_test.go` (+39 -0) 📝 `management/server/store/sql_store.go` (+4 -3) 📝 `management/server/store/store.go` (+3 -0) 📝 `shared/management/http/api/openapi.yml` (+13 -0) 📝 `shared/management/http/api/types.gen.go` (+37 -4) </details> ### 📄 Description ## Describe your changes This PR adds explicit peer kind support to the Management API so peers can be classified as `auto`, `device`, or `server`. Today, the dashboard has to infer peer type from enrollment behavior: peers enrolled with setup keys are treated as servers, and peers enrolled through SSO are treated as user devices. That inference is probably correct for most installations most of the time, but it is not always true. Some setup-key peers are regular devices, and some SSO-enrolled peers may function as servers, shared infrastructure, or unattended systems. Using enrollment method as the only source of truth makes the implementation clunky and limits the dashboard’s ability to represent the user’s actual environment. This PR keeps the current behavior compatible by making `auto` the default value. In `auto` mode, dashboards and clients can continue using the existing inference logic. Newer dashboards can optionally let users override the classification by setting `kind` to `device` or `server`. Changes included: - Adds a peer `Kind` field in the management server model. - Supports three values: `auto`, `device`, and `server`. - Defaults existing and new peers to `auto`. - Adds a store migration to backfill the new `kind` field on existing peer records. - Includes `kind` in peer list and single-peer API responses. - Accepts optional `kind` updates through the peer update API. - Validates invalid peer kind values server-side and rejects them with an invalid argument error. - Updates the optimized/raw SQL account loader so peer kind is loaded consistently across store paths. - Updates the OpenAPI schema and generated API types for the new field. - Adds tests for valid peer kind updates, invalid peer kind rejection, persistence, preservation when omitted, migration/default behavior, and account copy/store consistency. This is intended to support the companion dashboard change that restores the combined Peers page and allows the UI to respect explicit peer type when the backend provides it. ## Issue ticket number and link Supports dashboard issue: https://github.com/netbirdio/dashboard/issues/663 Supports dashboard PR: https://github.com/netbirdio/dashboard/pull/668 Issue #663 reports that the split Peers UI reduced functionality by forcing users to move between separate User Devices and Servers pages instead of working from one complete peer list. This API change addresses the underlying classification limitation that made the split awkward: the existing server/device distinction is inferred from enrollment method, which is useful as a default but not always accurate. ## Stack <!-- branch-stack --> Companion dashboard PR: https://github.com/netbirdio/dashboard/pull/668 ### Checklist - [ ] Is it a bug fix - [ ] Is a typo/documentation fix - [x] Is a feature enhancement - [ ] It is a refactor - [x] Created tests that fail without the change (if possible) - [ ] This change does **not** modify the public API, gRPC protocols, functionality behavior, CLI / service flags, or introduce a new feature — **OR** I have discussed it with the NetBird team beforehand (link the issue / Slack thread in the description). See [CONTRIBUTING.md](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTING.md#discuss-changes-with-the-netbird-team-first). Because this adds a public REST API field, I left the public API checklist item unchecked unless maintainers consider the linked dashboard issue/PR sufficient prior discussion. > By submitting this pull request, you confirm that you have read and agree to the terms of the [Contributor License Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md). ## Documentation Select exactly one: - [ ] I added/updated documentation for this change - [x] Documentation is **not needed** for this change (explain why) This change adds a small Management API field used by the dashboard to classify peers as automatic, device, or server. It does not introduce a new setup flow, operator configuration step, CLI flag, or user-facing self-hosting procedure. The dashboard companion PR presents the relevant behavior directly in the UI through the Peers page controls and peer detail field. ### Docs PR URL (required if "docs added" is checked) Paste the PR link from https://github.com/netbirdio/docs here: https://github.com/netbirdio/docs/pull/__ <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Peers can now be classified with a kind field (auto, device, or server) * The kind field is included in peer API responses and can be updated * Invalid kind values are rejected with appropriate error responses <!-- end of auto-generated comment: release notes by coderabbit.ai --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
saavagebueno added the pull-request label 2026-08-05 07:06:22 -04:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#25705