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. You apply them in Hosts → [host] → Edit → Tags.

What tags do

1. Filter lists

The host filter on any list page (Stacks, Containers, Volumes, Networks) accepts a tag:

• Show me stacks on prod hosts
• Show me all containers tagged team-frontend

2. Scope RBAC roles

A role can be scoped to hosts matching a tag:

• Role: Frontend Operator
• Scope: tag=team-frontend
• Permissions: stacks.deploy, containers.logs

User assigned this role can manage stacks only on hosts tagged team-frontend. All other hosts return 403.

3. Target alerts

Alert rules can match hosts by tag:

• Rule: “Host CPU > 90% for 10m on prod hosts, notify PagerDuty critical”

Non-prod hosts use a different (or no) rule.

4. Target backup jobs

A single backup job can apply to all hosts matching a tag:

• Job: nightly-db-backup
• Scope: all stacks tagged db-backup on hosts tagged prod

Auto-includes new hosts as they get tagged.

5. Host placement during migration / drain

When draining a host, dockmesh picks destinations from hosts with compatible tags. When migrating manually, you pick the destination — but the UI suggests hosts with matching tags first.

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 RBAC 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 3 roles:

   • Frontend-Ops: stacks.*, containers.* scoped to tag=team-frontend
   • Backend-Ops: same, scoped to tag=team-backend
   • Data-Ops: same, scoped to tag=team-data

3. Map SSO groups to roles:

   • Azure AD group frontend-engineers → Frontend-Ops
   • Azure AD group backend-engineers → Backend-Ops
   • Azure AD group data-engineers → Data-Ops

Engineers now see and manage only their team’s hosts. No one can accidentally deploy to another team’s infrastructure.

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

Tag-based automation

Several features auto-pick hosts by tag:

Stack templates with placement hints

A template can specify: “Prefer hosts tagged gpu”. When deploying from template, hosts with that tag are pre-selected.

Alert rule inheritance

New hosts joining a tag automatically inherit alert rules scoped to that tag. No per-host alert config.

Agent upgrade phases

Roll out an agent upgrade to dev-tagged hosts first, monitor, then expand to staging, then prod. (Settings → Maintenance → Upgrade rollout)

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:

• List filters: immediately (next page load)
• RBAC scoping: immediately
• Alert rule matching: on next evaluation cycle (~30s)
• Backup job scoping: on next run

Changing a host’s tags rarely requires any action beyond the tag change itself. dockmesh reconciles the rest.

See also

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