Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Carry the PBS-reported node name into the connections ledger

rcourtman884694a0462e
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index 2625c04957..b273c5853b 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -4293,7 +4293,11 @@ That host identity includes the hostname the PBS node reports about itself
so an IP-or-alias-configured PBS connection still reconciles with the agent's
reported hostname. The reported node name is identity evidence only: it never
enrolls the machine, extends heartbeats, or substitutes for agent-source
-identity in lifecycle decisions.
+identity in lifecycle decisions. The agent only reconciles through that name if
+it survives to the ledger: `Monitor.PBSInstancesSnapshot()` carries
+`PBSInstance.NodeName` back out of the unified PBS view, and
+`TestMonitorPBSInstancesSnapshotCarriesReportedNodeName` in
+`internal/monitoring/monitor_host_agents_test.go` pins that.
### Docker and Podman report sizes share one exact-byte contract
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md
index 3ea9c617e3..9e88c05935 100644
--- a/docs/release-control/v6/internal/subsystems/api-contracts.md
+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md
@@ -3962,7 +3962,9 @@ a new API state machine, queue contract, or verification-accounting field.
closed when more than one enabled platform source matches; VMware remains
excluded because a vCenter connection is not the ESXi host on which an
agent would run. PBS source aliases include the hostname the PBS node
- reports about itself (state-side `PBSInstance.NodeName`), because reported
+ reports about itself (`PBSInstance.NodeName` as returned by
+ `Monitor.PBSInstancesSnapshot()`, which converts it back out of the unified
+ PBS view), because reported
machine identity, not configured addressing, is what reconciles an
IP-or-alias-configured PBS connection with the host agent running on that
machine. Composition adds agent telemetry to the source row without
diff --git a/docs/release-control/v6/internal/subsystems/monitoring.md b/docs/release-control/v6/internal/subsystems/monitoring.md
index ab25b4cbda..9a68d9c806 100644
--- a/docs/release-control/v6/internal/subsystems/monitoring.md
+++ b/docs/release-control/v6/internal/subsystems/monitoring.md
@@ -3863,6 +3863,18 @@ one request per caller. The `GetNodeName` tests in
recovery, cache, and race proof; monitoring coverage also proves a token poll
never requests `/nodes`.
+The captured name only helps connected-system grouping if it survives the trip
+back out of the unified read state: `PBSData.NodeName` holds it on the PBS
+resource, `PBSInstanceView.NodeName()` exposes it, and
+`pbsInstanceFromReadStateView` copies it onto the `models.PBSInstance` that
+`Monitor.PBSInstancesSnapshot()` returns and `/api/connections` reads. A
+conversion that drops it leaves the PBS connection without its reported alias
+and the host agent on that machine as a separate row, with no error anywhere.
+`TestMonitorPBSInstancesSnapshotCarriesReportedNodeName` pins the snapshot
+carrying the name, and
+`TestConnectionsLedger_GroupsHostAgentWithPBSByReportedNodeName` in
+`internal/api` pins it from the unified PBS resource to the grouped system.
+
### Host snapshots carry integration provenance; doctor copy is user-facing
`models.Host.IntegrationSource` mirrors the unified fabric's
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index eb6b8fd3a7..4c6ef72f98 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -6535,6 +6535,14 @@ merge the PBS service and host, change either metrics target, or turn PBS API
polls into a host-agent time series. A missing or ambiguous host leaves the
link absent.
+`PBSInstanceView.NodeName()` hands read-state consumers the hostname the PBS
+server reports about itself (`PBSData.NodeName`), which is not `Hostname()`, the
+host of the endpoint Pulse was configured with. Consumers that rebuild a
+`models.PBSInstance` from the view, such as `Monitor.PBSInstancesSnapshot()`
+feeding the connections ledger, must carry it: it is empty only when the
+connection cannot read the node-name endpoint (API tokens).
+`TestView_PBSAndPMGInstanceViewAccessors` pins the accessor.
+
PBS does not supply the SMART inventory. Disk identity, health, temperature,
and other typed physical-disk facts therefore remain agent-owned, while the
PBS source mapping and PBS-parent relationship make the existing disk
diff --git a/internal/api/connections_aggregator_test.go b/internal/api/connections_aggregator_test.go
index 0afda6ee35..a8d68727bf 100644
--- a/internal/api/connections_aggregator_test.go
+++ b/internal/api/connections_aggregator_test.go
@@ -1,6 +1,7 @@
package api
import (
+ "context"
"reflect"
"testing"
"time"
@@ -11,6 +12,7 @@ import (
"github.com/rcourtman/pulse-go-rewrite/internal/monitoring"
"github.com/rcourtman/pulse-go-rewrite/internal/platformsupport"
"github.com/rcourtman/pulse-go-rewrite/internal/remoteconfig"
+ unified "github.com/rcourtman/pulse-go-rewrite/internal/unifiedresources"
)
func ptrTime(t time.Time) *time.Time { return &t }
@@ -393,6 +395,79 @@ func TestPBSReportedNodeNamesByInstanceSkipsBlankIdentity(t *testing.T) {
}
}
+// The reported node name has to survive the whole route into the ledger:
+// unified PBS resource, Monitor.PBSInstancesSnapshot, aggregator inputs,
+// connection HostAliases, system grouping. A PBS connection configured by IP
+// depends on it, because nothing the host agent running on that machine
+// reports matches the configured address. The unit tests above feed their
+// inputs by hand and cannot see the snapshot dropping the name.
+func TestConnectionsLedger_GroupsHostAgentWithPBSByReportedNodeName(t *testing.T) {
+ setMockModeForTest(t, false)
+
+ monitor, err := monitoring.New(&config.Config{DataPath: t.TempDir()})
+ if err != nil {
+ t.Fatalf("monitoring.New: %v", err)
+ }
+ t.Cleanup(func() { monitor.Stop() })
+
+ now := time.Now()
+ adapter := unified.NewMonitorAdapter(nil)
+ adapter.PopulateFromSnapshot(models.StateSnapshot{
+ PBSInstances: []models.PBSInstance{{
+ ID: "pbs-backup",
+ Name: "backup",
+ Host: "https://192.0.2.40:8007",
+ NodeName: "pbs01",
+ Status: "online",
+ LastSeen: now,
+ }},
+ Hosts: []models.Host{{
+ ID: "host-pbs01",
+ Hostname: "pbs01",
+ Status: "online",
+ LastSeen: now,
+ }},
+ })
+ setTestUnexportedField(t, monitor, "resourceStore", monitoring.ResourceStoreInterface(adapter))
+
+ cfg := &config.Config{
+ PBSInstances: []config.PBSInstance{{Name: "backup", Host: "https://192.0.2.40:8007"}},
+ }
+ inputs := buildAggregatorInputsWithRuntimeSources(context.Background(), cfg, nil, monitor, aggregatorRuntimeSources{})
+ connections := buildConnections(inputs)
+
+ var pbsConnection, agentConnection *Connection
+ for i := range connections {
+ switch connections[i].Type {
+ case ConnectionTypePBS:
+ pbsConnection = &connections[i]
+ case ConnectionTypeAgent:
+ agentConnection = &connections[i]
+ }
+ }
+ if pbsConnection == nil || agentConnection == nil {
+ t.Fatalf("expected a PBS and an agent connection, got %+v", connections)
+ }
+ if !reflect.DeepEqual(pbsConnection.HostAliases, []string{"backup", "192.0.2.40", "pbs01"}) {
+ t.Fatalf("pbs host aliases = %+v, want the reported node name %q included", pbsConnection.HostAliases, "pbs01")
+ }
+
+ systems := buildConnectionSystems(connections, monitor)
+ if len(systems) != 1 || systems[0].ID != pbsConnection.ID {
+ t.Fatalf("expected one system led by %q, got %+v", pbsConnection.ID, systems)
+ }
+ roles := make(map[string]ConnectionSystemComponentRole, len(systems[0].Components))
+ for _, component := range systems[0].Components {
+ roles[component.ConnectionID] = component.Role
+ }
+ if roles[pbsConnection.ID] != ConnectionSystemComponentRolePrimary {
+ t.Fatalf("%s role = %q, want %q", pbsConnection.ID, roles[pbsConnection.ID], ConnectionSystemComponentRolePrimary)
+ }
+ if roles[agentConnection.ID] != ConnectionSystemComponentRoleAttachment {
+ t.Fatalf("%s role = %q, want %q", agentConnection.ID, roles[agentConnection.ID], ConnectionSystemComponentRoleAttachment)
+ }
+}
+
func TestBuildConnections_ProjectsLegacyLinuxDistroToRuntimePlatform(t *testing.T) {
now := time.Now()
got := buildConnections(aggregatorInputs{
diff --git a/internal/monitoring/monitor.go b/internal/monitoring/monitor.go
index 72aff4182a..67df1befb1 100644
--- a/internal/monitoring/monitor.go
+++ b/internal/monitoring/monitor.go
@@ -3981,6 +3981,7 @@ func pbsInstanceFromReadStateView(view *unifiedresources.PBSInstanceView) models
ID: firstNonEmptyString(view.InstanceID(), view.ID()),
Name: view.Name(),
Host: view.HostURL(),
+ NodeName: view.NodeName(),
GuestURL: view.GuestURL(),
Status: string(view.Status()),
Version: view.Version(),
diff --git a/internal/monitoring/monitor_host_agents_test.go b/internal/monitoring/monitor_host_agents_test.go
index 46cf04cea2..324a24eab1 100644
--- a/internal/monitoring/monitor_host_agents_test.go
+++ b/internal/monitoring/monitor_host_agents_test.go
@@ -7969,3 +7969,43 @@ func TestFindLinkedProxmoxEntityPreservesDistinctGuestFQDNs(t *testing.T) {
})
}
}
+
+// The poller records the hostname a PBS node reports about itself so the
+// connections ledger can group the host agent running on that machine under
+// the PBS connection, even when the connection was configured by IP or DNS
+// alias. The ledger reads the name back through PBSInstancesSnapshot, which
+// rebuilds each instance from the unified read state; a conversion that
+// drops the name leaves the agent as a separate row with no error anywhere.
+func TestMonitorPBSInstancesSnapshotCarriesReportedNodeName(t *testing.T) {
+ registry := unifiedresources.NewRegistry(nil)
+ registry.IngestSnapshot(models.StateSnapshot{
+ PBSInstances: []models.PBSInstance{{
+ ID: "pbs-1",
+ Name: "backup",
+ Host: "https://192.0.2.40:8007",
+ NodeName: "pbs01",
+ Status: "online",
+ LastSeen: time.Date(2026, 10, 10, 9, 0, 0, 0, time.UTC),
+ }},
+ })
+
+ // The unified resource holds the name, so a missing value below is lost
+ // in the conversion, not at ingest.
+ resources := registry.ListByType(unifiedresources.ResourceTypePBS)
+ if len(resources) != 1 || resources[0].PBS == nil || resources[0].PBS.NodeName != "pbs01" {
+ t.Fatalf("expected the PBS resource to keep the reported node name, got %+v", resources)
+ }
+
+ m := &Monitor{
+ state: models.NewState(),
+ resourceStore: unifiedresources.NewMonitorAdapter(registry),
+ }
+
+ instances := m.PBSInstancesSnapshot()
+ if len(instances) != 1 {
+ t.Fatalf("expected one PBS instance, got %d", len(instances))
+ }
+ if instances[0].NodeName != "pbs01" {
+ t.Fatalf("PBSInstancesSnapshot()[0].NodeName = %q, want the reported node name %q", instances[0].NodeName, "pbs01")
+ }
+}
diff --git a/internal/unifiedresources/views.go b/internal/unifiedresources/views.go
index a7a295d038..a1c31267eb 100644
--- a/internal/unifiedresources/views.go
+++ b/internal/unifiedresources/views.go
@@ -2752,6 +2752,16 @@ func (v PBSInstanceView) Hostname() string {
return v.r.PBS.Hostname
}
+// NodeName is the hostname the PBS server reports about itself, as opposed to
+// Hostname, which is the host of the address Pulse was configured with. It is
+// empty when the connection cannot read the node-name endpoint (API tokens).
+func (v PBSInstanceView) NodeName() string {
+ if v.r == nil || v.r.PBS == nil {
+ return ""
+ }
+ return v.r.PBS.NodeName
+}
+
func (v PBSInstanceView) InstanceID() string {
if v.r == nil || v.r.PBS == nil {
return ""
diff --git a/internal/unifiedresources/views_test.go b/internal/unifiedresources/views_test.go
index f035ee84f7..c66d0765dc 100644
--- a/internal/unifiedresources/views_test.go
+++ b/internal/unifiedresources/views_test.go
@@ -1571,6 +1571,7 @@ func TestView_PBSAndPMGInstanceViewAccessors(t *testing.T) {
PBS: &PBSData{
InstanceID: "pbs-instance-1",
Hostname: "pbs.example",
+ NodeName: "pbs01",
HostURL: "https://pbs.example:8007",
GuestURL: "https://pbs-guest.example:8007",
Version: "3.2",
@@ -1625,6 +1626,9 @@ func TestView_PBSAndPMGInstanceViewAccessors(t *testing.T) {
if v.Hostname() != "pbs.example" || v.Version() != "3.2" || v.UptimeSeconds() != 100 {
t.Fatalf("expected hostname/version/uptime to match, got %q/%q/%d", v.Hostname(), v.Version(), v.UptimeSeconds())
}
+ if v.NodeName() != "pbs01" {
+ t.Fatalf("expected the node name the PBS server reports, distinct from the configured hostname, got %q", v.NodeName())
+ }
if v.InstanceID() != "pbs-instance-1" || v.HostURL() != "https://pbs.example:8007" || v.GuestURL() != "https://pbs-guest.example:8007" {
t.Fatalf("expected canonical instance/host/guest URLs, got id=%q host=%q guest=%q", v.InstanceID(), v.HostURL(), v.GuestURL())
}