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.

Fix Docker child aliases that block command host routing

rcourtman8bab8328add1
diff --git a/docs/release-control/v6/internal/subsystems/ai-runtime.md b/docs/release-control/v6/internal/subsystems/ai-runtime.md
index bd5e132707..afafd36fd5 100644
--- a/docs/release-control/v6/internal/subsystems/ai-runtime.md
+++ b/docs/release-control/v6/internal/subsystems/ai-runtime.md
@@ -8727,6 +8727,15 @@ explicit renderer fixtures at 1440, 900 and 390 pixel widths.
### Monitoring identity without command access
+An ambiguous target returns `STRICT_RESOLUTION` with the tool error bit and
+guidance to select an exact canonical resource ID. It cannot be described as a
+missing command connection or fall back to a connected hostname. Docker children
+inherit placement, not their reporting host's identity aliases, through the
+shared canonical identity owner. `TestDockerLogReadRoutesToHostWithCollectedChildren`
+checks registered read dispatch with host/child ingestion and real-collision
+refusal; `TestAmbiguousResourceNameCannotFallBackToConnectedHostname` checks the
+failure envelope without dispatch.
+
Command routing resolves monitored topology independently of agent connection
availability. A missing connection must preserve the known target kind and
parent node, cannot fall back to a different agent with a colliding name or ID,
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index d93955f1fd..4eb790a50c 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -23,6 +23,22 @@ and sort the complete canonical change table while startup and ingestion wait.
## Purpose
+### Docker object aliases do not identify their reporting host
+
+Containers and other Docker child objects own their native IDs, names and
+subject-typed discovery/metrics targets. Reporting-agent IDs, Docker host IDs,
+hostnames and task placement nodes remain routing metadata, not child aliases.
+Canonical hostname/platform presentation must not reintroduce those parent
+identities. Missing child targets cannot promote the parent to primary identity.
+Host aliases and same-entity host facets retain their existing semantics.
+
+`TestDockerChildIdentityDoesNotClaimItsCommandHost` covers all nine child kinds,
+owned aliases and missing-target boundaries. The registered Docker log-read
+control in `internal/ai/tools/internal_routing_identity_test.go` consumes actual
+registry ingestion with collected containers, images and networks. Genuine
+duplicate names must still fail closed. Source controls alone do not establish
+installed command transport or autonomous recovery.
+
### Shared interpretation of selected guest memory
`GuestMemoryEvidenceForResource` and the VM/container `MemoryEvidence` accessors
diff --git a/internal/ai/tools/internal_routing_identity_test.go b/internal/ai/tools/internal_routing_identity_test.go
index 06b32376ee..ba15f7a064 100644
--- a/internal/ai/tools/internal_routing_identity_test.go
+++ b/internal/ai/tools/internal_routing_identity_test.go
@@ -1,12 +1,66 @@
package tools
import (
+ "context"
+ "encoding/json"
+ "strings"
+ "testing"
+
"github.com/rcourtman/pulse-go-rewrite/internal/agentexec"
"github.com/rcourtman/pulse-go-rewrite/internal/models"
"github.com/rcourtman/pulse-go-rewrite/internal/unifiedresources"
- "testing"
+ "github.com/stretchr/testify/mock"
)
+func TestDockerLogReadRoutesToHostWithCollectedChildren(t *testing.T) {
+ rr := unifiedresources.NewRegistry(nil)
+ rr.IngestSnapshot(models.StateSnapshot{
+ Hosts: []models.Host{{ID: "native-host", Hostname: "unattended-lab", MachineID: "machine-1", CommandsEnabled: true}},
+ DockerHosts: []models.DockerHost{{
+ ID: "native-host", AgentID: "native-host", Hostname: "unattended-lab", MachineID: "machine-1",
+ Containers: []models.DockerContainer{{ID: "container-1", Name: "target", State: "running"}, {ID: "container-2", Name: "control", State: "running"}},
+ Images: []models.DockerImage{{ID: "image-1", RepoTags: []string{"example:latest"}}},
+ Networks: []models.DockerNetwork{{ID: "network-1", Name: "bridge"}},
+ }},
+ })
+ if len(rr.Hosts()) != 1 || len(rr.DockerHosts()) != 1 || rr.Hosts()[0].ID() != rr.DockerHosts()[0].ID() || len(rr.DockerContainers()) != 2 {
+ t.Fatalf("fixture lost host or collected children")
+ }
+ server := &mockAgentServer{agents: []agentexec.ConnectedAgent{{AgentID: "native-host", Hostname: "unattended-lab"}}}
+ server.On("GetConnectedAgents").Return(server.agents)
+ server.On("ExecuteCommand", mock.Anything, "native-host", mock.MatchedBy(func(payload agentexec.ExecuteCommandPayload) bool {
+ return payload.TargetType == "agent" && payload.TargetID == "" && strings.Contains(payload.Command, "docker logs") && strings.Contains(payload.Command, "target")
+ })).Return(&agentexec.CommandResultPayload{ExitCode: 0, Stdout: "worker session stalled"}, nil)
+ executor := NewPulseToolExecutor(ExecutorConfig{ReadState: rr, AgentServer: server, ControlLevel: ControlLevelReadOnly})
+ containerID := ""
+ for _, container := range rr.DockerContainers() {
+ if container.Name() == "target" {
+ containerID = container.ID()
+ }
+ }
+ for _, reference := range []string{"unattended-lab", "native-host", "agent:native-host", rr.Hosts()[0].ID(), containerID} {
+ t.Run(reference, func(t *testing.T) {
+ result, err := executor.ExecuteTool(context.Background(), "pulse_read", map[string]interface{}{
+ "action": "logs", "source": "docker", "container": "target", "since": "30m", "target_host": reference,
+ })
+ if err != nil || result.IsError || len(result.Content) == 0 || !strings.Contains(result.Content[0].Text, "worker session stalled") {
+ t.Fatalf("registered Docker log read did not reach its connected parent: result=%+v err=%v", result, err)
+ }
+ })
+ }
+ server.AssertExpectations(t)
+ // A real child/host name collision is still ambiguous. It must not use
+ // the connected host merely because unrelated inherited aliases are gone.
+ rr.IngestResources([]unifiedresources.Resource{{
+ ID: "colliding-child", Type: unifiedresources.ResourceTypeAppContainer, Name: "unattended-lab",
+ Docker: &unifiedresources.DockerData{HostSourceID: "native-host", ContainerID: "container-3", Hostname: "unattended-lab"},
+ Identity: unifiedresources.ResourceIdentity{Hostnames: []string{"unattended-lab"}},
+ }})
+ if result := executor.resolveTargetForCommandFull("unattended-lab"); result.AgentID != "" || result.ResolvedKind != "ambiguous" {
+ t.Fatalf("a genuine child/host collision selected a command host: %+v", result)
+ }
+}
+
func TestCanonicalCommandTargetKeepsProviderScopedParent(t *testing.T) {
rr := unifiedresources.NewRegistry(nil)
records := []unifiedresources.Resource{}
@@ -47,6 +101,16 @@ func TestAmbiguousResourceNameCannotFallBackToConnectedHostname(t *testing.T) {
if result.AgentID != "" || result.ResolvedKind != "ambiguous" {
t.Fatalf("known ambiguity escaped topology ownership: %+v", result)
}
+ read, err := executor.ExecuteTool(context.Background(), "pulse_read", map[string]interface{}{
+ "action": "logs", "source": "docker", "container": "target", "target_host": "duplicate",
+ })
+ if err != nil || !read.IsError || len(read.Content) != 1 {
+ t.Fatalf("ambiguous read must fail before dispatch: %+v %v", read, err)
+ }
+ var response ToolResponse
+ if err := json.Unmarshal([]byte(read.Content[0].Text), &response); err != nil || response.Error == nil || response.Error.Code != ErrCodeStrictResolution {
+ t.Fatalf("ambiguity was misreported as an absent connection: %+v %v", response, err)
+ }
}
func TestKnownAgentIDCannotRouteToAnImpostorHostname(t *testing.T) {
diff --git a/internal/ai/tools/tools_control.go b/internal/ai/tools/tools_control.go
index 22fb7daeb0..03735c85b2 100644
--- a/internal/ai/tools/tools_control.go
+++ b/internal/ai/tools/tools_control.go
@@ -357,6 +357,16 @@ func (e *PulseToolExecutor) resolveTargetForCommandFull(targetHost string) Comma
// unavailableCommandConnection preserves monitoring context without inferring
// installation, permission, or guest capability from an absent connection.
func unavailableCommandConnection(target string, routing CommandRoutingResult) CallToolResult {
+ if routing.ResolvedKind == "ambiguous" {
+ return NewToolResponseResult(ToolResponse{
+ OK: false,
+ Error: &ToolError{
+ Code: ErrCodeStrictResolution, Failed: true,
+ Message: fmt.Sprintf("Target %q matches multiple monitored resources. Select the exact canonical resource ID from the inventory. The requested operation did not run.", target),
+ Details: map[string]any{"target": target, "resource_kind": "ambiguous"},
+ },
+ })
+ }
message := "No command connection is available. Specify a target with diagnostic access."
details := map[string]any{"target": target}
if target != "" {
diff --git a/internal/unifiedresources/canonical_identity.go b/internal/unifiedresources/canonical_identity.go
index cdafee8cd2..9511d290ef 100644
--- a/internal/unifiedresources/canonical_identity.go
+++ b/internal/unifiedresources/canonical_identity.go
@@ -32,15 +32,26 @@ func canonicalPrimaryID(resource Resource) string {
if nodeID := canonicalProxmoxNodePrimaryID(resource); nodeID != "" {
return nodeID
}
+ if isDockerChildResource(resource) {
+ for _, target := range []interface {
+ GetResourceType() string
+ GetResourceID() string
+ }{resource.MetricsTarget, resource.DiscoveryTarget} {
+ if id := dockerChildTargetID(resource, target); id != "" {
+ return string(CanonicalResourceType(resource.Type)) + ":" + id
+ }
+ }
+ if identity := canonicalDockerSwarmNodePrimaryID(resource); identity != "" {
+ return identity
+ }
+ return strings.TrimSpace(resource.ID)
+ }
if identity := formatTargetIdentity(resource.MetricsTarget); identity != "" {
return identity
}
if identity := formatTargetIdentity(resource.DiscoveryTarget); identity != "" {
return identity
}
- if identity := canonicalDockerSwarmNodePrimaryID(resource); identity != "" {
- return identity
- }
if runtimeID := strings.TrimSpace(canonicalDockerRuntimeID(resource)); runtimeID != "" {
return "docker-host:" + runtimeID
}
@@ -81,6 +92,21 @@ func canonicalProxmoxNodePrimaryID(resource Resource) string {
func canonicalAliases(resource Resource, primaryID, platformID, hostname string) []string {
values := append([]string{}, resource.SupersededCanonicalIDs...)
+ if isDockerChildResource(resource) {
+ // Docker placement identifies the command host, not the collected
+ // object. Indexing that host on every child makes the real host's
+ // otherwise unique hostname and agent ID ambiguous.
+ values = append(values, primaryID)
+ if CanonicalResourceType(resource.Type) == ResourceTypeDockerSwarmNode {
+ values = append(values, canonicalDockerNodeID(resource), canonicalDockerNodeName(resource))
+ }
+ values = append(values,
+ dockerChildTargetID(resource, resource.MetricsTarget),
+ dockerChildTargetID(resource, resource.DiscoveryTarget),
+ platformID, hostname, resource.Name, resource.Identity.MachineID, resource.ID,
+ )
+ return uniqueTrimmed(append(values, resource.Identity.Hostnames...)...)
+ }
values = append(values,
primaryID,
targetResourceID(resource.MetricsTarget),
@@ -139,6 +165,13 @@ func canonicalAliases(resource Resource, primaryID, platformID, hostname string)
}
func canonicalPlatformID(resource Resource) string {
+ if isDockerChildResource(resource) {
+ return firstTrimmed(
+ dockerChildTargetID(resource, resource.MetricsTarget),
+ dockerChildTargetID(resource, resource.DiscoveryTarget),
+ resource.Name, resource.ID,
+ )
+ }
return firstTrimmed(
canonicalProxmoxNodeName(resource),
canonicalAgentHostname(resource),
@@ -154,6 +187,9 @@ func canonicalPlatformID(resource Resource) string {
}
func canonicalHostname(resource Resource) string {
+ if isDockerChildResource(resource) {
+ return firstIdentityHostname(resource.Identity)
+ }
return firstTrimmed(
firstIdentityHostname(resource.Identity),
canonicalAgentHostname(resource),
@@ -165,6 +201,29 @@ func canonicalHostname(resource Resource) string {
)
}
+func isDockerChildResource(resource Resource) bool {
+ if resource.Docker == nil {
+ return false
+ }
+ switch CanonicalResourceType(resource.Type) {
+ case ResourceTypeAppContainer, ResourceTypeDockerService, ResourceTypeDockerImage,
+ ResourceTypeDockerVolume, ResourceTypeDockerNetwork, ResourceTypeDockerTask,
+ ResourceTypeDockerSwarmNode, ResourceTypeDockerSecret, ResourceTypeDockerConfig:
+ return true
+ }
+ return false
+}
+
+func dockerChildTargetID(resource Resource, target interface {
+ GetResourceType() string
+ GetResourceID() string
+}) string {
+ if target == nil || CanonicalResourceType(ResourceType(target.GetResourceType())) != CanonicalResourceType(resource.Type) {
+ return ""
+ }
+ return targetResourceID(target)
+}
+
func canonicalProxmoxNodeName(resource Resource) string {
if resource.Proxmox == nil {
return ""
diff --git a/internal/unifiedresources/canonical_identity_test.go b/internal/unifiedresources/canonical_identity_test.go
index 26ef04fd68..8a7203a3e2 100644
--- a/internal/unifiedresources/canonical_identity_test.go
+++ b/internal/unifiedresources/canonical_identity_test.go
@@ -3,6 +3,7 @@ package unifiedresources
import (
"encoding/json"
"reflect"
+ "slices"
"strings"
"testing"
"time"
@@ -115,6 +116,49 @@ func TestRefreshCanonicalIdentityPrefersTargetsAndCanonicalHostData(t *testing.T
}
}
+func TestDockerChildIdentityDoesNotClaimItsCommandHost(t *testing.T) {
+ for _, kind := range []ResourceType{
+ ResourceTypeAppContainer, ResourceTypeDockerService, ResourceTypeDockerImage,
+ ResourceTypeDockerVolume, ResourceTypeDockerNetwork, ResourceTypeDockerTask,
+ ResourceTypeDockerSwarmNode, ResourceTypeDockerSecret, ResourceTypeDockerConfig,
+ } {
+ t.Run(string(kind), func(t *testing.T) {
+ resource := Resource{
+ ID: "child-1", Type: kind, Name: "workload",
+ Identity: ResourceIdentity{Hostnames: []string{"workload"}},
+ Docker: &DockerData{HostSourceID: "native-host", AgentID: "native-host", Hostname: "command-host", NodeID: "swarm-node", NodeName: "swarm-worker"},
+ MetricsTarget: &MetricsTarget{ResourceType: string(kind), ResourceID: "native-child"},
+ DiscoveryTarget: &DiscoveryTarget{ResourceType: string(kind), ResourceID: "workload", AgentID: "native-host", Hostname: "command-host"},
+ }
+ RefreshCanonicalIdentity(&resource)
+ for _, alias := range resource.Canonical.Aliases {
+ if alias == "native-host" || alias == "agent:native-host" || alias == "command-host" || alias == "docker-host:native-host" {
+ t.Fatalf("child claimed parent identity %q: %+v", alias, resource.Canonical)
+ }
+ }
+ if resource.Canonical.PlatformID != "native-child" || resource.Canonical.Hostname != "workload" {
+ t.Fatalf("child presentation borrowed parent placement: %+v", resource.Canonical)
+ }
+ for _, reference := range []string{"child-1", "native-child", "workload", string(kind) + ":native-child"} {
+ if !slices.Contains(resource.Canonical.Aliases, reference) {
+ t.Fatalf("child lost its own reference %q: %+v", reference, resource.Canonical)
+ }
+ }
+ // Losing discovery detail must not turn the child into its parent.
+ resource.MetricsTarget = nil
+ resource.DiscoveryTarget = &DiscoveryTarget{ResourceType: "agent", ResourceID: "native-host", AgentID: "native-host"}
+ resource.Identity = ResourceIdentity{}
+ RefreshCanonicalIdentity(&resource)
+ if resource.Canonical.PrimaryID == "agent:native-host" || resource.Canonical.PrimaryID == "docker-host:native-host" || resource.Canonical.Hostname != "" {
+ t.Fatalf("incomplete child became its parent: %+v", resource.Canonical)
+ }
+ if slices.Contains(resource.Canonical.Aliases, "native-host") {
+ t.Fatalf("parent discovery target became a child alias: %+v", resource.Canonical)
+ }
+ })
+ }
+}
+
func TestDockerCollectionModeDoesNotChangeCanonicalIdentity(t *testing.T) {
resource := Resource{
ID: "docker-host-1",
@@ -505,8 +549,6 @@ func TestRefreshCanonicalIdentityUsesDockerSwarmNodeIdentity(t *testing.T) {
"docker-swarm-node:cluster-1:node-1",
"node-1",
"manager-1",
- "docker-host-1",
- "docker-host",
"docker-swarm-node-resource-1",
}
if len(resource.Canonical.Aliases) != len(wantAliases) {