Portainer Swarm node labels and CPU limits for a low-traffic stack: which constraint actually controls placement?

Answer

When you deploy a stack through Portainer, the deploy.placement.constraints and deploy.resources.limits defined in the Compose file are the source of truth. Editing those values in Portainer’s stack editor updates the Compose file itself, so the UI values take precedence only because they replace the Compose content. If you change constraints or limits on a running service via the Service → Details page, Portainer creates a runtime override that lasts until the next stack redeploy, at which point the Compose file values are reapplied.

How the Swarm scheduler decides placement

1. Constraint filtering – Swarm first evaluates placement constraints (e.g., node.labels.tier==low). Only nodes that satisfy all constraints remain eligible.
2. Resource feasibility check – For each eligible node, Swarm checks whether the node has enough free CPU (and memory) to meet the service’s resources.limits and resources.reservations. If a node lacks sufficient capacity, it is treated as ineligible.
3. Node selection – Among the nodes that pass both steps, Swarm applies any placement preferences (spread, binpack) and picks the best fit.

Therefore, the node‑label constraint is the decisive filter; CPU limits act only as a secondary feasibility check.

Verifying node labels in Portainer

Portainer shows a node’s labels on the Nodes → <node‑name> → Labels tab. This view mirrors the output of docker node inspect <node-id> and is the supported way to confirm which labels a node carries before scheduling.

Steps to confirm your low‑traffic stack lands on the labeled cheap nodes

1. Label the two small nodes: docker node update --label-add tier=low <node-id> (or do it via Portainer → Nodes → Edit).
2. In your stack’s Compose file, set the constraint, for example:

   deploy:
     placement:
       constraints:
         - node.labels.tier==low
     resources:
       limits:
         cpus: '0.5'
         memory: 256M
   

3. Deploy or redeploy the stack through Portainer → Stacks → your‑stack → Deploy. Portainer will write the UI values back to the Compose file if you edited them there.
4. After deployment, check placement: Portainer → Stacks → your‑stack → Resources shows the node each task runs on, or run docker service ps <service-name>.
5. If the labeled nodes run out of CPU, the service will stay pending (no task assigned) until a labeled node frees capacity; Swarm will not fall back to unlabeled nodes because the constraint filter excludes them.

Version consistency

The described behavior has been unchanged in Portainer CE 2.x and BE releases up to at least 2.19.0 (the latest as of 2026‑09). No recent release altered the way Compose‑defined constraints or limits are merged with UI edits, so you can rely on this behavior across recent versions.

Missing diagnostic detail

Are you planning to adjust constraints/limits via the Stack editor (which updates the Compose file) or via the Service → Details page (which creates a temporary override)? The answer determines whether your changes will persist after a redeploy.