Host Tags

Host tags are simple labels on hosts. But they’re used in so many places that understanding them pays off.

What a tag is

A string attached to a host. No namespacing, no keys-and-values (just strings), no reserved names:

• prod
• staging
• dev
• eu-west
• us-east
• gpu
• edge
• home-lab
• team-frontend

A host can have many tags. Apply them under Hosts → host detail → edit tags.

What tags do today

1. Search + filter

The Hosts page search matches host name OR any tag — typing team-frontend narrows to hosts carrying that tag. Detail-list pages (Stacks, Containers) have a host selector for picking a single host, but no tag-filter dropdown on top of that yet.

2. Scope user + role access (RBAC)

Tags drive the scope mechanism in two layers:

• Custom-role host_tag scope rows (Roles → custom role → Scopes). The common pattern: a custom role with host_tag = team-frontend only grants its permissions on hosts carrying that tag.
• Per-user scope_tags (Users → user → scope icon). An additional filter on top of the role’s scope. Same host_tag:team-frontend syntax.

Both layers apply — the request is allowed only when neither says no. An empty value at a layer means “no restriction at this layer”. See RBAC scopes for the full mechanism.

3. Restrict registry credentials

Saved registry credentials carry an optional scope_tags field — a credential tagged prod only attaches to image pulls on hosts that also carry prod. Useful for keeping a production Harbor PAT off dev agents.

What tags do not do (yet)

These show up in older marketing copy and aren’t shipped:

• Alert rules don’t route by host tag. The alert engine scopes by container_filter glob (a container-name pattern like paperless-*) — there’s no host_tag dimension on rules.
• Backup jobs don’t scope by host tag. A job targets specific stacks, not “every host tagged prod”.
• Stack templates don’t carry placement hints. Deploying from a template still asks you which host.
• Agent upgrade staging isn’t tag-based. Staged mode rolls out a configurable percentage of drifted agents per tick; it doesn’t pick by tag.
• Drain doesn’t filter destinations by tag. The planner bin-packs onto whatever online hosts are available; if you need “only land on gpu hosts”, drain to a smaller fleet first.

These are roadmap items, not designed-out limitations.

Tag conventions

Common tagging schemas (pick what fits your org):

By environment: prod · staging · dev · sandbox

By region / zone: eu-west · us-east · home

By team: team-frontend · team-backend · team-data

By hardware: gpu · nvme · high-mem · arm

By role: web · db · cache · batch

Combine freely. A host might be tagged: prod, eu-west, team-backend, db, nvme.

Scoping by tag — worked example

Your company has 3 teams: Frontend, Backend, Data.

1. Tag hosts:

   • Frontend’s web servers: team-frontend
   • Backend’s API servers: team-backend
   • Data team’s DB hosts: team-data

2. Create a lean custom role for team operators — say Team-Operator with containers.view/update/exec/logs, stacks.view/deploy, images.view/scan, audit.view. Decide whether the role itself carries the scope (preferred — one role per team) or whether the scope lives on each user (more flexible if users move between teams).

3. Pattern A — role-scoped:

   • One role per team: Team-Frontend-Operator with role-scope host_tag = team-frontend, same for backend and data
   • Assign the role to each engineer; no per-user scope needed

4. Pattern B — user-scoped:

   • One generic Team-Operator role with no role-scope
   • Per-user scope_tags: ["host_tag:team-frontend"] for frontend engineers etc.

Either way: engineers now see and manage only their team’s hosts. The backend re-checks the scope on every API call, so no UI bypass.

This is the kind of setup Portainer Business charges for. dockmesh ships it free.

Tag-based automation — roadmap

Several “tags driving automation” features are planned but not shipped — they’re worth knowing about so you don’t end up modeling them prematurely. See What tags do not do (yet) above.

Anti-patterns

Too few tags: everything tagged prod. You lose the ability to segment by team, role, or region.

Too many tags: 15 tags per host, half are one-off. Gets messy fast. Keep it to what actually drives automation.

Tag sprawl: creating new tags casually. Establish a convention early.

Using tags as a database: dockmesh tags aren’t key-value. Don’t try to encode structured data (env=prod,region=eu,team=web). Use separate tags.

Tag lifecycle

Tags can be added/removed at any time. Changes take effect:

• Hosts-page search: immediately
• RBAC scoping (role-scope + user scope_tags): immediately, on the next API call
• Registry-credential attachment to pulls: on the next pull

Changing a host’s tags doesn’t require any further action.

See also

• RBAC — role + scope model
• Multi-Host — host lifecycle
• SSO — group mapping to roles