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.

Preserve distinct guest FQDNs during automatic agent attribution

pulse-triage[bot]8b213d05d487
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index 36e01ba408..87aafb76fc 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -15,6 +15,22 @@
## Purpose
+### Automatic provider links retain full hostname distinctions
+
+An agent report may automatically associate a short hostname with a unique
+Proxmox node/guest FQDN, or an FQDN with a short provider name. Two distinct
+FQDNs sharing a first label cannot link by hostname alone. Adding an independent
+provider with a different guest domain must not clear the original exact-FQDN
+link. Ambiguous bare names still yield no automatic link; operator-owned links,
+endpoint/network hints, token/machine identity and enrolment remain unchanged.
+
+`TestFindLinkedProxmoxEntityPreservesDistinctGuestFQDNs` and the FQDN sequential
+addition cases in `TestCrossInstallationIdentitySurvivesStandaloneAddition`
+verify this attribution boundary and retained Docker inventory. Connection
+endpoint form does not prove guest hostname, reporter cause, native recovery or
+containing release availability.
+
+
### PMG scope persistence does not change agent authority
PMG scope booleans remain explicit when false in shared settings readback,
diff --git a/docs/release-control/v6/internal/subsystems/monitoring.md b/docs/release-control/v6/internal/subsystems/monitoring.md
index 18b3436fb0..7594ef8083 100644
--- a/docs/release-control/v6/internal/subsystems/monitoring.md
+++ b/docs/release-control/v6/internal/subsystems/monitoring.md
@@ -17,6 +17,24 @@
## Purpose
+### Automatic Proxmox agent attribution preserves distinct FQDNs
+
+Hostname-only attribution uses the common full-hostname equivalence rule:
+case, surrounding whitespace and a DNS root dot are normalised; a short name
+may match an FQDN, but different full domains never identify the same machine.
+A bare name matching multiple provider nodes/guests stays unlinked. Explicit
+endpoint and unique provider-network hints retain their existing precedence.
+The connection FQDN and Pulse display name are not guest-hostname evidence.
+
+`TestFindLinkedProxmoxEntityPreservesDistinctGuestFQDNs` covers node, VM and LXC
+selection, a sole unrelated domain, ambiguous short names and legacy short/full
+pairs. `TestCrossInstallationIdentitySurvivesStandaloneAddition` adds FQDN
+connections with overlapping native node names/VMIDs and distinct guest domains,
+checking original node health, scoped backups, Docker inventory and agent link
+continuity. These are source controls, not the established reporter cause or
+native three-surface recovery for #2681.
+
+
### PMG saved collection scope and incomplete observations
The PMG poller snapshots the selected connection's saved scope once per poll.
diff --git a/internal/monitoring/monitor_agents.go b/internal/monitoring/monitor_agents.go
index 598c6b3bd5..764e307315 100644
--- a/internal/monitoring/monitor_agents.go
+++ b/internal/monitoring/monitor_agents.go
@@ -4590,25 +4590,12 @@ func (m *Monitor) findLinkedProxmoxEntityWithHints(
return "", "", ""
}
- // Normalize hostname for comparison (lowercase, strip domain)
- normalizedHostname := strings.ToLower(hostname)
- shortHostname := normalizedHostname
- if idx := strings.Index(normalizedHostname, "."); idx > 0 {
- shortHostname = normalizedHostname[:idx]
- }
-
+ // A short name may match its FQDN, but two different FQDNs are not the
+ // same machine. Collapsing both to the first label can erase a working
+ // guest link when an independent installation is added, or link a sole
+ // unrelated guest before that installation has been discovered.
matchHostname := func(name string) bool {
- normalized := strings.ToLower(name)
- if normalized == normalizedHostname || normalized == shortHostname {
- return true
- }
- // Also check short version of the candidate
- if idx := strings.Index(normalized, "."); idx > 0 {
- if normalized[:idx] == shortHostname {
- return true
- }
- }
- return false
+ return unifiedresources.HostnamesEquivalent(hostname, name)
}
readState := m.GetUnifiedReadStateOrSnapshot()
diff --git a/internal/monitoring/monitor_cross_installation_identity_test.go b/internal/monitoring/monitor_cross_installation_identity_test.go
index f2186780e0..2294e5579b 100644
--- a/internal/monitoring/monitor_cross_installation_identity_test.go
+++ b/internal/monitoring/monitor_cross_installation_identity_test.go
@@ -19,11 +19,14 @@ func TestCrossInstallationIdentitySurvivesStandaloneAddition(t *testing.T) {
for _, tc := range []struct {
name, host string
classified bool
+ fqdnGuests bool
}{
- {"unclassified distinct-address node", "https://203.0.113.10:8006", false},
- {"classified distinct-address node", "https://203.0.113.10:8006", true},
- {"unclassified member-hostname coincidence", "https://pmx1:8006", false},
- {"classified member-hostname coincidence", "https://pmx1:8006", true},
+ {"unclassified distinct-address node", "https://203.0.113.10:8006", false, false},
+ {"classified distinct-address node", "https://203.0.113.10:8006", true, false},
+ {"unclassified member-hostname coincidence", "https://pmx1:8006", false, false},
+ {"classified member-hostname coincidence", "https://pmx1:8006", true, false},
+ {"unclassified FQDN connection and distinct guest domains", "https://pmx1.remote.example:8006", false, true},
+ {"classified FQDN connection and distinct guest domains", "https://pmx1.remote.example:8006", true, true},
} {
name, classified := tc.name, tc.classified
clusterName := ""
@@ -39,6 +42,10 @@ func TestCrossInstallationIdentitySurvivesStandaloneAddition(t *testing.T) {
m.SetResourceStore(adapter)
now := time.Now().UTC()
backupAt := now.Add(-time.Hour)
+ homeGuestName, remoteGuestName := "docker-vm", "docker-vm"
+ if tc.fqdnGuests {
+ homeGuestName, remoteGuestName = "docker-vm.home.example", "docker-vm.remote.example"
+ }
homeNodes := []models.Node{}
for _, native := range []string{"pmx1", "pmx2", "pmx3"} {
node := m.placeholderNodeForInstance("Home", &m.config.PVEInstances[0], native)
@@ -49,18 +56,18 @@ func TestCrossInstallationIdentitySurvivesStandaloneAddition(t *testing.T) {
}
m.state.UpdateNodesForInstance("Home", homeNodes)
homeGuestID := makeGuestID("Home", "pmx1", 100)
- m.state.UpdateVMsForInstance("Home", []models.VM{{ID: homeGuestID, Instance: "Home", Node: "pmx1", VMID: 100, Name: "docker-vm", Status: "running", LastSeen: now}})
+ m.state.UpdateVMsForInstance("Home", []models.VM{{ID: homeGuestID, Instance: "Home", Node: "pmx1", VMID: 100, Name: homeGuestName, Status: "running", LastSeen: now}})
m.state.UpdateStorageBackupsForInstance("Home", []models.StorageBackup{{Instance: "Home", Node: "pmx1", VMID: 100, Time: backupAt}})
m.state.SyncGuestBackupTimes()
adapter.PopulateFromSnapshot(m.state.GetSnapshot())
token := &config.APITokenRecord{ID: "home-agent-token"}
hostReport := agentshost.Report{
Agent: agentshost.AgentInfo{ID: "home-agent", IntervalSeconds: 30},
- Host: agentshost.HostInfo{ID: "home-machine", MachineID: "home-machine", Hostname: "docker-vm", Platform: "linux"}, Timestamp: now,
+ Host: agentshost.HostInfo{ID: "home-machine", MachineID: "home-machine", Hostname: homeGuestName, Platform: "linux"}, Timestamp: now,
}
dockerReport := agentsdocker.Report{
Agent: agentsdocker.AgentInfo{ID: "home-agent", IntervalSeconds: 30},
- Host: agentsdocker.HostInfo{MachineID: "home-machine", Hostname: "docker-vm", DockerVersion: "27.0.0", TotalCPU: 4},
+ Host: agentsdocker.HostInfo{MachineID: "home-machine", Hostname: homeGuestName, DockerVersion: "27.0.0", TotalCPU: 4},
Containers: []agentsdocker.Container{{ID: "home-workload", Name: "app", State: "running"}}, Timestamp: now,
}
if _, err := m.ApplyHostReport(hostReport, token); err != nil {
@@ -81,7 +88,7 @@ func TestCrossInstallationIdentitySurvivesStandaloneAddition(t *testing.T) {
remote.ConnectionHealth = "unhealthy"
remote.PendingUpdatesReason = "api_error"
m.state.UpdateNodesForInstance(standalone.Name, []models.Node{remote})
- m.state.UpdateVMsForInstance(standalone.Name, []models.VM{{ID: makeGuestID(standalone.Name, "pmx1", 100), Instance: standalone.Name, Node: "pmx1", VMID: 100, Name: "docker-vm", Status: "running", LastSeen: now}})
+ m.state.UpdateVMsForInstance(standalone.Name, []models.VM{{ID: makeGuestID(standalone.Name, "pmx1", 100), Instance: standalone.Name, Node: "pmx1", VMID: 100, Name: remoteGuestName, Status: "running", LastSeen: now}})
m.normalizePVEConfigState()
if len(m.config.PVEInstances) != 2 {
t.Fatal("standalone connection retired on discovered hostname alone")
@@ -130,6 +137,12 @@ func TestCrossInstallationIdentitySurvivesStandaloneAddition(t *testing.T) {
if len(guestNodes) != 1 || guestNodes[100] != "pmx1" {
t.Fatal("backup node lookup lost home scope")
}
+ if tc.fqdnGuests {
+ hosts := m.state.GetSnapshot().Hosts
+ if len(hosts) != 1 || hosts[0].LinkedVMID != homeGuestID {
+ t.Fatalf("distinct guest FQDNs erased or redirected the original agent link: %+v", hosts)
+ }
+ }
if len(adapter.DockerHosts()) != 1 || len(adapter.DockerContainers()) != 1 {
t.Fatal("Docker monitoring disappeared after independent guest addition")
}
diff --git a/internal/monitoring/monitor_host_agents_test.go b/internal/monitoring/monitor_host_agents_test.go
index 7f1fe56568..c4321e7b61 100644
--- a/internal/monitoring/monitor_host_agents_test.go
+++ b/internal/monitoring/monitor_host_agents_test.go
@@ -7452,3 +7452,60 @@ func TestPreviousVMFromViewKeepsLinkedAgentDiskOutOfProxmoxCarry(t *testing.T) {
t.Fatalf("Proxmox's own guest disk not carried: usage=%v reason=%q", usage, reason)
}
}
+
+// Endpoint hints are deliberately absent: an operator-saved FQDN endpoint
+// does not establish the agent's guest hostname. Test that attribution keeps
+// full provider/agent names distinct while preserving short-name compatibility.
+func TestFindLinkedProxmoxEntityPreservesDistinctGuestFQDNs(t *testing.T) {
+ for _, kind := range []string{"node", "vm", "container"} {
+ t.Run(kind, func(t *testing.T) {
+ m := &Monitor{state: models.NewState()}
+ setNames := func(names ...string) {
+ nodes, vms, containers := []models.Node{}, []models.VM{}, []models.Container{}
+ for i, name := range names {
+ id, instance := "home", "Home"
+ if i > 0 {
+ id, instance = "remote", "Remote"
+ }
+ switch kind {
+ case "node":
+ nodes = append(nodes, models.Node{ID: id, Name: name, Instance: instance})
+ case "vm":
+ vms = append(vms, models.VM{ID: id, Name: name, Instance: instance, VMID: 100})
+ case "container":
+ containers = append(containers, models.Container{ID: id, Name: name, Instance: instance, VMID: 100})
+ }
+ }
+ m.state.UpdateNodes(nodes)
+ m.state.UpdateVMs(vms)
+ m.state.UpdateContainers(containers)
+ }
+ check := func(hostname, want string) {
+ t.Helper()
+ node, vm, container := m.findLinkedProxmoxEntity(hostname)
+ got := map[string]string{"node": node, "vm": vm, "container": container}
+ for k, id := range got {
+ expected := ""
+ if k == kind {
+ expected = want
+ }
+ if id != expected {
+ t.Errorf("hostname %q: %s=%q, want %q", hostname, k, id, expected)
+ }
+ }
+ }
+ setNames("docker.home.example")
+ check("docker.home.example", "home")
+ check(" DOCKER.HOME.EXAMPLE. ", "home")
+ check("docker.remote.example", "") // A sole unrelated FQDN is not identity.
+ check("docker", "home")
+ setNames("docker.home.example", "docker.remote.example")
+ check("docker.home.example", "home")
+ check("docker.remote.example", "remote")
+ check("docker", "") // Bare name still cannot choose between estates.
+ check("docker.third.example", "")
+ setNames("docker")
+ check("docker.home.example", "home") // Legacy short provider name remains usable.
+ })
+ }
+}