feat(docker): the Swarm page is laid out by node: role, what its containers use, and the services placed on each (#5303)

#5303 "Swarm page laid out by node: role, resources and the tasks placed on each"

A verdict line first, then the nodes that are down or drained and the
services short of replicas, then one card per node. A node with a Steward
agent shows what its swarm tasks use against the machine's cores and memory,
service by service. A node without one lists Swarm's placement, by count.
The services table moved to the Docker overview, where it can be filtered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

plugins/docker/routes.py

@@ -20,6 +20,7 @@ from .swarm_view import (
     build_swarm_services, failing_services, parse_tasks, replaced_tasks, services_problems_first,
     task_summary, trouble_since,
 )
+from .swarm_nodes import node_cards
 from .overview import (
     DOCKER_SORTS, DOCKER_STATES, NO_STACK, container_row, filter_rows, service_row, sort_rows,
     stack_of,
@@ -497,7 +498,9 @@ async def container_detail(host_id: str, name: str):
 @docker_bp.get("/swarm")
 @require_role(UserRole.viewer)
 async def swarm():
-    """Swarm topology page: services with replica health, nodes, placement.
+    """The Swarm page, laid out by node (#5303): each node's role, whether it
+    takes work, what its containers use against what the machine has, and the
+    services placed on it; services short of replicas first.
 
     Swarm services/nodes are cluster-global — every manager's API returns the
     same list — but each manager reports them independently (rows keyed by
@@ -515,6 +518,20 @@ async def swarm():
                 DockerSwarmNode.role, DockerSwarmNode.hostname)
         )).scalars())
         hosts = await docker_svc.host_map(db, {s.host_id for s in services} | {n.host_id for n in nodes})
+        containers = await docker_svc.list_containers(db)
+        # The Steward host on each node: the one whose agent reports its
+        # containers, else the host named as the node is.
+        node_host = {c.node_id: c.host_id for c in containers if c.node_id}
+        unmatched = {(n.hostname or "").lower() for n in nodes if n.node_id not in node_host} - {""}
+        if unmatched:
+            by_name = {h.name.lower(): h for h in (await db.execute(
+                select(Host).where(func.lower(Host.name).in_(unmatched)))).scalars()}
+            for n in nodes:
+                h = by_name.get((n.hostname or "").lower())
+                if n.node_id not in node_host and h is not None:
+                    node_host[n.node_id] = h.id
+        hosts.update(await docker_svc.host_map(db, set(node_host.values()) - set(hosts)))
+        capacity = await docker_svc.host_capacity(db, set(node_host.values()))
 
     # ── Group reporting managers into swarms by shared node membership ──────────
     manager_ids = {s.host_id for s in services} | {n.host_id for n in nodes}
@@ -586,17 +603,16 @@ async def swarm():
                 **summary,
                 "trouble_since": trouble_since(tasks, state, summary["crash_looping"], now),
             })
-        # Problems first: a node that is down or not taking work, then by role.
-        node_rows = sorted(
-            node_by_id.values(), key=lambda n: (
-                n.status == "ready" and n.availability == "active",
-                n.role, (n.hostname or n.node_id).lower())
-        )
         manager_names = sorted(hosts[m].name if m in hosts else m for m in members)
         swarms.append({
             "managers": manager_names,
-            "services": services_problems_first(svc_dicts),
-            "nodes": node_rows,
+            "services_total": len(svc_dicts),
+            "services_healthy": sum(d["state"] == "healthy" for d in svc_dicts),
+            "troubled": failing_services(svc_dicts),
+            "nodes": node_cards(
+                node_by_id.values(), svc_by_name.values(), containers, node_host=node_host,
+                host_names={h.id: h.name for h in hosts.values()}, capacity=capacity,
+                service_state={d["name"]: d["state"] for d in svc_dicts}),
         })
 
     swarms.sort(key=lambda g: g["managers"][0].lower() if g["managers"] else "")

plugins/docker/swarm_nodes.py

@@ -0,0 +1,71 @@
+# plugins/docker/swarm_nodes.py
+"""The Swarm page laid out by node (#5303): one card per node with its role,
+whether it takes work, what its containers use against what the machine has,
+and the services Swarm placed on it. Model-free, so it is unit-tested without
+a database; routes.swarm() feeds it.
+
+A node with a Steward agent reports its own containers, so its services carry
+CPU and memory. A node without one is known only from the managers' placement:
+its services are listed by count, with no figures.
+"""
+from __future__ import annotations
+
+from .swarm_view import _placement
+
+
+def node_ok(n) -> bool:
+    """A node that is up and taking work."""
+    return n.status == "ready" and n.availability == "active"
+
+
+def node_cards(nodes, services, containers, *, node_host: dict, host_names: dict,
+               capacity: dict, service_state: dict) -> list[dict]:
+    """One card per node, a node in trouble first, then managers, then by name.
+
+    `nodes` and `services` are one swarm's deduplicated rows; `containers`
+    every container row (only running swarm tasks on these nodes count);
+    `node_host` maps a node id to the Steward host on it, `capacity` a host id
+    to (cores, memory bytes), `service_state` a service name to healthy,
+    degraded or down."""
+    running_on: dict[str, dict[str, dict]] = {}
+    for c in containers:
+        if not (c.node_id and c.service_name and c.status == "running"):
+            continue
+        row = running_on.setdefault(c.node_id, {}).setdefault(
+            c.service_name, {"name": c.service_name, "tasks": 0, "cpu_pct": 0.0, "mem_bytes": 0,
+                             "measured": True})
+        row["tasks"] += 1
+        row["cpu_pct"] += c.cpu_pct or 0.0
+        row["mem_bytes"] += c.mem_usage_bytes or 0
+    placed: dict[str, dict[str, int]] = {}
+    for s in services:
+        for p in _placement(s):
+            count = int(p.get("running") or 0)
+            if count > 0 and p.get("node_id"):
+                placed.setdefault(p["node_id"], {})[s.service_name] = count
+
+    cards = []
+    for n in nodes:
+        rows = dict(running_on.get(n.node_id, {}))
+        for name, count in placed.get(n.node_id, {}).items():
+            rows.setdefault(name, {"name": name, "tasks": count, "cpu_pct": None, "mem_bytes": None,
+                                   "measured": False})
+        for r in rows.values():
+            r["state"] = service_state.get(r["name"], "healthy")
+            r["cores"] = r["cpu_pct"] / 100 if r["cpu_pct"] is not None else None
+        tasks = sorted(rows.values(), key=lambda r: (r["state"] == "healthy", -(r["cores"] or 0.0),
+                                                     r["name"].lower()))
+        host_id = node_host.get(n.node_id)
+        cores, mem = capacity.get(host_id, (None, None)) if host_id else (None, None)
+        measured = [r for r in tasks if r["measured"]]
+        cards.append({
+            "node_id": n.node_id, "hostname": n.hostname or n.node_id[:12], "role": n.role,
+            "leader": n.leader, "status": n.status, "availability": n.availability, "ok": node_ok(n),
+            "host_id": host_id, "host_name": host_names.get(host_id) if host_id else None,
+            "agent": bool(running_on.get(n.node_id)) or host_id is not None,
+            "tasks": tasks, "task_count": sum(r["tasks"] for r in tasks),
+            "cores_used": sum(r["cores"] for r in measured) if measured else None,
+            "mem_used": sum(r["mem_bytes"] for r in measured) if measured else None,
+            "cores": cores, "mem": mem,
+        })
+    return sorted(cards, key=lambda c: (c["ok"], c["role"] != "manager", c["hostname"].lower()))

plugins/docker/templates/docker/swarm.html

@@ -1,95 +1,103 @@
-{# docker/swarm.html — Swarm topology: services, replica health, nodes, placement.
-   Services in trouble come first (crash loop, down, short), with since-times;
-   nodes that are down or not taking work come first. #}
+{# docker/swarm.html — the Swarm laid out by node (#5303). A verdict, the
+   services short of replicas, then one card per node: a node that is down or
+   not taking work first, then managers. Each card says what its containers use
+   against what the machine has, and lists the services placed on it. #}
 {% extends "base.html" %}
-{% from "_macros.html" import crumbs %}
+{% from "_macros.html" import crumbs, status_badge, status_dot %}
+{% from "docker/_usage.html" import cores as fmt_cores %}
 {% block title %}Swarm — Docker — Steward{% endblock %}
 {% block breadcrumb %}{{ crumbs([("Docker", "/plugins/docker/"), ("Swarm", "")]) }}{% endblock %}
 {% block content %}
 
-<h1 class="page-title" style="margin-bottom:1.5rem;">Swarm</h1>
+<h1 class="page-title">Swarm</h1>
 
 {% if swarms %}
 {% for g in swarms %}
-<div style="margin-bottom:2rem;">
-  <div style="display:flex;align-items:baseline;gap:0.6rem;margin-bottom:0.75rem;flex-wrap:wrap;">
-    <span style="font-weight:500;font-size:0.95rem;">Swarm</span>
-    <span style="font-size:0.78rem;color:var(--text-muted);">
-      reported by {{ g.managers | length }} manager{{ 's' if g.managers | length != 1 }} · {{ g.managers | join(", ") }}
-    </span>
-  </div>
+{% set down_nodes = g.nodes|rejectattr("ok")|list %}
+<section class="swarm-group" aria-label="Swarm reported by {{ g.managers|join(', ') }}">
+  <p class="docker-verdict">
+    {% if down_nodes or g.troubled %}<strong class="tone-crit">{{ down_nodes|length + g.troubled|length }} need{{ "s" if (down_nodes|length + g.troubled|length) == 1 }} attention</strong>
+    {% else %}<strong class="tone-ok">Every node is up and taking work</strong>{% endif %}
+    · {{ g.nodes|length }} node{{ "s" if g.nodes|length != 1 }}
+    · <span class="tone-{{ 'ok' if g.services_healthy == g.services_total else 'warn' }}">{{ g.services_healthy }}/{{ g.services_total }}</span> services healthy
+    <span class="tone-dim">· reported by {{ g.managers|join(", ") }}</span>
+  </p>
 
-  {# ── Services ─────────────────────────────────────────────────────────── #}
-  <div class="card-flush" style="margin-bottom:1rem;">
-    <table class="table">
-      <thead>
-        <tr>
-          <th>Service</th><th>Mode</th><th>Replicas</th><th>Image</th><th>Placement</th><th>Task failures</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for s in g.services %}
-        <tr>
-          <td style="font-weight:500;font-size:0.9rem;">{{ s.name }}</td>
-          <td style="font-size:0.82rem;color:var(--text-muted);">{{ s.mode }}</td>
-          <td style="font-family:ui-monospace,monospace;font-size:0.88rem;">
-            <span style="color:{% if s.healthy %}var(--green){% elif s.down %}var(--red){% elif s.degraded %}var(--orange){% else %}var(--text-muted){% endif %};">
-              {{ s.running }}/{{ s.desired }}
-            </span>
-            {% if s.state != 'healthy' and s.trouble_since %}<div style="font-family:inherit;font-size:0.72rem;color:var(--text-dim);" title="{{ s.trouble_since }}">since {{ s.trouble_since|ago }}</div>{% endif %}
-          </td>
-          <td style="font-size:0.8rem;color:var(--text-muted);max-width:220px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">{{ s.image or "—" }}</td>
-          <td style="font-size:0.78rem;color:var(--text-muted);">
-            {% for p in s.placement %}{{ p.node }} ({{ p.running }}){% if not loop.last %}, {% endif %}{% else %}—{% endfor %}
-          </td>
-          <td style="max-width:360px;">
-            {% include "docker/_swarm_failures.html" %}
-            {%- if not s.tasks_known %}<span style="font-size:0.78rem;color:var(--text-dim);" title="The reporting manager's agent predates task reporting (1.8.0); update it to see task failures.">—</span>
-            {%- elif not (s.crash_looping or s.failures_24h or (s.last_error and s.state != 'healthy')) %}<span style="font-size:0.78rem;color:var(--text-dim);">none in 24h</span>{% endif %}
-          </td>
-        </tr>
-        {% else %}
-        <tr><td colspan="6" style="color:var(--text-muted);font-size:0.85rem;text-align:center;padding:1.5rem;">No services in this swarm.</td></tr>
-        {% endfor %}
-      </tbody>
-    </table>
-  </div>
+  {% if down_nodes or g.troubled %}
+  <section class="card problem-card" aria-label="Needs attention">
+    <ul class="problem-list">
+      {% for n in down_nodes %}
+      <li>
+        {{ status_badge('crit', 'Node ' ~ n.status) if n.status != 'ready' else status_badge('warn', n.availability|capitalize) }}
+        <span>{{ n.hostname }}</span>
+        <span class="problem-detail">{{ n.role }} · {{ n.task_count }} task{{ "s" if n.task_count != 1 }} placed on it</span>
+      </li>
+      {% endfor %}
+      {% for s in g.troubled %}
+      <li>
+        {% if s.crash_looping %}{{ status_badge('crit', 'Crash-looping') }}{% elif s.state == 'down' %}{{ status_badge('crit', 'Down') }}{% else %}{{ status_badge('warn', 'Degraded') }}{% endif %}
+        <a href="/plugins/docker/service/{{ s.name }}">{{ s.name }}</a>
+        {% set e = s.last_error %}
+        <span class="problem-detail">
+          {{- s.running }} of {{ s.desired }} running
+          {%- if e %} · last task {{ e.state }}: {{ e.error or e.message or e.state }}{% if e.node %} on {{ e.node }}{% endif %}{% endif %}
+          {%- if s.trouble_since %} · since {{ s.trouble_since|ago }}{% endif -%}
+        </span>
+      </li>
+      {% endfor %}
+    </ul>
+  </section>
+  {% endif %}
 
-  {# ── Nodes ────────────────────────────────────────────────────────────── #}
-  <div class="card-flush">
-    <table class="table">
-      <thead>
-        <tr><th>Node</th><th>Role</th><th>Availability</th><th>Status</th></tr>
-      </thead>
-      <tbody>
-        {% for n in g.nodes %}
-        <tr>
-          <td style="font-weight:500;font-size:0.9rem;">
-            {{ n.hostname or n.node_id }}
-            {% if n.leader %}<span title="cluster leader" style="font-size:0.68rem;color:var(--accent);border:1px solid var(--accent);border-radius:3px;padding:0 0.3rem;margin-left:0.3rem;">leader</span>{% endif %}
-          </td>
-          <td style="font-size:0.82rem;color:var(--text-muted);">{{ n.role }}</td>
-          <td style="font-size:0.82rem;color:{% if n.availability == 'active' %}var(--text){% else %}var(--orange){% endif %};">{{ n.availability }}</td>
-          <td style="font-size:0.82rem;">
-            <span class="dot {% if n.status == 'ready' %}dot-up{% else %}dot-down{% endif %}"></span>
-            <span style="color:{% if n.status == 'ready' %}var(--green){% else %}var(--red){% endif %};">{{ n.status }}</span>
-          </td>
-        </tr>
+  <div class="node-grid">
+    {% for n in g.nodes %}
+    <section class="card node-card{% if not n.ok %} problem-card{% endif %}" aria-labelledby="node-{{ n.node_id }}">
+      <h2 id="node-{{ n.node_id }}" class="node-card-head">
+        {{ status_dot('up' if n.status == 'ready' else 'down') }}
+        {% if n.host_id %}<a href="/hosts/{{ n.host_id }}">{{ n.hostname }}</a>{% else %}{{ n.hostname }}{% endif %}
+        <span class="chip">{{ "leader" if n.leader else n.role }}</span>
+        {% if n.availability != 'active' %}{{ status_badge('warn', n.availability|capitalize, title="Swarm places no new tasks here") }}{% endif %}
+      </h2>
+      <p class="node-card-figures">
+        {% if n.cores_used is not none %}
+        Containers use <strong>{{ fmt_cores(n.cores_used) }}</strong>{% if n.cores %} of {{ n.cores }}{% endif %}
+        · <strong>{{ n.mem_used|bytes }}</strong>{% if n.mem %} of {{ n.mem|bytes }}{% endif %}
+        {% elif n.agent %}
+        <span class="tone-muted">No swarm task reports figures here yet.</span>
         {% else %}
-        <tr><td colspan="4" style="color:var(--text-muted);font-size:0.85rem;text-align:center;padding:1.5rem;">No nodes reported.</td></tr>
-        {% endfor %}
-      </tbody>
-    </table>
+        <span class="tone-muted" title="Install the Steward agent on this node to see what its tasks use">No Steward agent: what runs here is Swarm's placement, without figures.</span>
+        {% endif %}
+      </p>
+      {% if n.tasks %}
+      <table class="table node-tasks">
+        <thead><tr><th>Service</th><th class="num">Tasks</th><th class="num">CPU</th><th class="num">Memory</th></tr></thead>
+        <tbody>
+          {% for t in n.tasks %}
+          <tr>
+            <td class="cell-name">
+              {%- if t.state != 'healthy' %}{{ status_dot('down' if t.state == 'down' else 'warn') }} {% endif -%}
+              <a href="/plugins/docker/service/{{ t.name }}" title="{{ t.name }}">{{ t.name }}</a>
+            </td>
+            <td class="num">{{ t.tasks }}</td>
+            <td class="num">{% if t.cores is not none %}{{ fmt_cores(t.cores) }}{% else %}<span class="tone-dim">—</span>{% endif %}</td>
+            <td class="num">{% if t.mem_bytes is not none %}{{ t.mem_bytes|bytes }}{% else %}<span class="tone-dim">—</span>{% endif %}</td>
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+      {% else %}
+      <p class="tone-muted" style="margin:0;">No tasks placed here.</p>
+      {% endif %}
+    </section>
+    {% endfor %}
   </div>
-</div>
+</section>
 {% endfor %}
 {% else %}
-<div class="card" style="text-align:center;padding:3rem;">
-  <div style="color:var(--text-muted);font-size:0.9rem;">
-    No Swarm topology reported. A Steward host agent running on a Swarm
-    <strong>manager</strong> reports services, nodes, and task placement here —
-    workers and non-swarm hosts contribute only their local containers.
-  </div>
+<div class="card empty-state">
+  No Swarm topology reported. A Steward host agent running on a Swarm
+  <strong>manager</strong> reports services, nodes and task placement here;
+  workers and hosts outside a swarm contribute only their own containers.
 </div>
 {% endif %}
 {% endblock %}