Backend Tags and Placement Bias

Tags label what a backend can do. Workspaces declare which tags they require, prefer, or forbid. Placement bias tags tip the load balancer toward the least-loaded, lowest-latency, or most memory-rich host among the candidates that already match.

What a backend tag is

A backend tag is a short capability label such as gpu, autocad, or windows-2022. Matching is case-insensitive. Tokens must match ^[A-Za-z0-9][A-Za-z0-9_-]*$; the installer and gateway sanitize invalid tokens away.

How tags are assigned

When a backend registers (and on heartbeat), the gateway resolves tags in this order:

AMI catalog — for auto-scaled instances that appear in managed_instances (copied from the AMI entry at launch).
Admin override — row in backend_tag_overrides, keyed by the backend’s advertised URL (for example http://10.0.2.15:9005).
Node’s own tags — from gateway/backend/tags in app.config.xml, set at install time or via the -tags command line, and sent in the registration payload.

Registration reports which source won via tagSource: ami-catalog, admin-override, cli, or none.

Static nodes

Set tags in the Backend Only wizard (Backend Tags field), or with Configure-Config.ps1 -BackendTags "gpu,cad".
Override centrally in the admin console: Infrastructure › Backend Tags. Overrides can be created for a URL before the node is online.

Note

Static seed entries under <gateway><backends><backend> accept only URL and maxSessions — never tags. Tags always come from registration, heartbeat, AMI catalog, or an admin override.

What consumes tags

Only workspaces express tag requirements. Edit a workspace and use the Image Tag Routing section. Values are stored in workspaces.config_json.imageTags:

{
  "required": ["gpu"],
  "preferred": ["fewest-sessions", "gp3"],
  "forbidden": ["spot"]
}

List	Effect
`required`	Hard filter. The backend must have every required tag (placement-bias names in this list are stripped and ignored).
`forbidden`	Hard exclusion. Any match removes the backend from the candidate set.
`preferred`	Soft scoring. Matching soft tags and placement biases raise a backend’s score; they never eliminate candidates alone.

Applications, policy sets, and users cannot declare tag requirements for routing.

Selection order

Session affinity — if this session is already pinned to a healthy, non-draining backend, that backend wins (capacity is not re-checked for sticky traffic).
Workspace imageTags — loaded after POST /gateway/session/select.
Capacity filter — new sessions (GET /getConnection) only consider backends that are healthy, not draining, and below maxSessions.
Required / forbidden filters, then preferred scoring (base 100, +10 per matching soft tag, placement-bias bonuses, minus a utilization penalty). With no soft preferences, the gateway falls through to least-connections.

If no backend matches the required tags, the client receives a generic HTTP 503 No backend servers available. The gateway log carries the real reason: No backends match required tags: [...].

Placement bias tags

These built-in names go in the workspace preferred list. They are not ordinary capability tags; they adjust scoring among hosts that already passed hard filters.

Tag	Scoring	Typical use
`lowest-cpu-load`	`+(100 - CpuUsage) × 0.2`	CPU-heavy apps; prefer quieter hosts.
`highest-mem-available`	`+(100 - MemoryUsage) × 0.2`	Memory-hungry CAD or data tools.
`lowest-latency`	Bonus from recent average response time (or a default if no data yet)	Interactive UI work where round-trip feels important.
`fewest-sessions`	`+(1 - utilization) × 20`	Spread users across the fleet instead of packing onto the least-connections default alone.

Tip

Placement bias needs live CPU, memory, and latency from heartbeats. A node that has just registered scores on defaults until the first heartbeats arrive.

Use cases

Scenario	Configuration
GPU or CAD nodes only for one workspace	Tag backends `gpu` (or `autocad`). Workspace `required: ["gpu"]`.
Licence-restricted application hosts	Tag the licensed hosts; require that tag on the workspace that publishes the licensed app.
Keep critical work off spot capacity	Tag spot workers `spot`. Critical workspace `forbidden: ["spot"]`.
Spread interactive users	Workspace `preferred: ["fewest-sessions"]` (optionally with `lowest-latency`).
Pack sessions to leave hosts free for scale-in	Omit placement bias; rely on default least-connections among matching hosts.

Limitations

Tags route workspaces only — not applications, policy sets, or individual users.
Required-tag misses produce a generic 503; operators must read the gateway log for the tag detail.
<gateway><loadBalancing><strategy> (RoundRobin / LeastConnections / Weighted) is ignored for new-session placement, which always uses least-loaded or tag scoring.
There are no admin-assigned per-backend weights; the Weighted strategy computes weight from live utilization on non-placement paths.
A mid-session backend failure does not fail over WebSockets. Affinity expires by sessionAffinityTimeout (default 3600 s).
Static seed backends in config cannot carry tags; use install-time tags or admin overrides.