Target Selection
Choosing the right targets for your deployment ensures your changes reach the intended machines.
Selection Methods
Section titled “Selection Methods”A deployment’s destination is explicit target IDs, a set of tags, or an
off-target destination — an execution pool or a named Thorax instance, which run
the work on the control plane rather than on an agent. The two off-target destinations
are mutually exclusive with each other and with the target selectors; target_ids and
target_tags may be sent together, in which case the ID’d targets are then filtered by
the tags. Lens’ three mode buttons pick one at a time, so the combination is a
request-shape capability rather than a UI one. The UI layers convenience flows (manual picking, name patterns) on top of
them. The environment is a deployment scope, not a destination and not a target
source: a deployment must still carry target_ids or target_tags, or it is rejected
with No target selection criteria provided. The environment’s own target assignments
(and their priority ordering) are resolved only by promotions and rollbacks.
| Method | Resolves via | Best For |
|---|---|---|
| By Tag | Tags | Targeted updates |
| By Target | Target IDs | Ad-hoc operations |
| By Pool | execution_pool_id | Off-target work, any pool member |
| By Instance | execution_thorax_instance_id | Off-target work, one instance |
Deploying Within an Environment
Section titled “Deploying Within an Environment”The environment scopes the deployment; it does not pre-populate the target list. The
picker shows every target you can reach, with its name, status badge, hostname:port
and tags — there is no environment filter, no mode column and no priority column.
Environment Selection Process
Section titled “Environment Selection Process”- Choose the environment in the Context step
- In Targets, pick by target, by tags, or by pool
- Proceed with deployment
Environment target assignments — and the priority ordering attached to them — are read only by promotions and rollbacks, which resolve their targets from the environment rather than from the request.
Tag-Based Selection
Section titled “Tag-Based Selection”Filter targets using tags for more granular control:
┌─────────────────────────────────────────────────────────────┐│ Filter by Tags │├─────────────────────────────────────────────────────────────┤│ ││ Include targets where: ││ ││ ┌─────────────────────────────────────────────────────┐ ││ │ role [=] [web ] [×] │ ││ │ region [=] [us-east-1 ] [×] │ ││ │ [+ Add Filter] │ ││ └─────────────────────────────────────────────────────┘ ││ ││ Matching targets (4 of 12): ││ ● web-prod-01 ││ ● web-prod-02 ││ ● web-prod-03 ││ ● web-prod-04 ││ │└─────────────────────────────────────────────────────────────┘Tag Filter Operations
Section titled “Tag Filter Operations”Tag filters match by exact key=value equality. Each filter you add must specify both a key and a value; a target is included only when it carries a tag with that exact key and that exact value.
| Field | Description | Example |
|---|---|---|
key | The tag key to match | role |
value | The exact value | web |
Combining Filters
Section titled “Combining Filters”By default multiple tag filters combine with ANY (OR) logic — a target
matches if it has any of the tags. Set target_tags_match_all: true on the
REST request to require ALL tags instead, or tick Require every tag in Lens’
target step. There is no CLI flag for it: repeated --target-tag is always ANY, so
from mantisctl it needs a direct API call.
# default (ANY): role = web OR region = us-east-1 OR tier = frontend# match_all=true: role = web AND region = us-east-1 AND tier = frontendThis selects only targets matching all criteria.
By Target Selection
Section titled “By Target Selection”For ad-hoc deployments, manually pick targets by their ID. The search box filters the displayed list by name or hostname on the client side — it is a convenience filter for finding the right targets, not a deployment selector itself. Only the targets you check are sent to the deployment.
┌─────────────────────────────────────────────────────────────┐│ Select Targets │├─────────────────────────────────────────────────────────────┤│ ││ Search: [web-prod_________] ││ ││ Available Targets: ││ ┌────────────────┬────────┬──────────┬────────────────┐ ││ │ [✓] web-prod-01│ Online │ Listen │ Production │ ││ │ [✓] web-prod-02│ Online │ Listen │ Production │ ││ │ [ ] web-prod-03│ Online │ Listen │ Production │ ││ │ [ ] web-stg-01 │ Online │ Poll │ Staging │ ││ └────────────────┴────────┴──────────┴────────────────┘ ││ ││ Selected: 2 targets ││ │└─────────────────────────────────────────────────────────────┘When to Use By Target Selection
Section titled “When to Use By Target Selection”- Testing on specific machines
- Investigating issues on particular targets
- Running maintenance on subset of servers
- Canary deployments to single targets
Target Status and Deployment
Section titled “Target Status and Deployment”Health status does not gate deployment. Target selection filters by id, tag and tenant only — a deployment dispatches to its selected targets regardless of whether they are Online, Stale or Offline, and there is no “include by status” or “wait for stale recovery” setting. A command sent to an Offline target simply waits (listen mode) or is picked up when the agent next polls; if the agent never returns, the command times out.
The picker does carry a status dropdown, beside its search box:
┌─────────────────────────────────────────────────────────────┐│ Select Targets │├─────────────────────────────────────────────────────────────┤│ ││ [ Search by name or hostname ] [ All Status ▾ ] ││ ││ [ ] Select all matching (2 of 3) ││ ││ [✓] web-prod-01 Online ││ [✓] web-prod-02 Online ││ [ ] db-prod-01 Stale ││ │└─────────────────────────────────────────────────────────────┘It narrows the rows on screen so you can find a target in a long list. It is not part of the deployment request: what is sent is the set of ids you ticked. The one way it reaches the outcome is “Select all matching”, which ticks the rows the dropdown is currently showing — it changes what you selected, not what the server does with the selection.
Ordering
Section titled “Ordering”priority is a column on the environment’s target assignments (range -100 to 100,
default 50, higher first). It orders the targets that promotions and rollbacks
resolve from an environment.
It does not order an ordinary deployment. Targets named in the request are run in the
order you named them — a sequential deployment’s contract — and concurrency comes from
the execution mode (parallel, sequential, rolling:N), not from priority groups.
Selection Validation
Section titled “Selection Validation”There is no pre-flight warning screen. The selector reports only that a selection resolves to nothing:
| Situation | What the UI shows |
|---|---|
| The picker loaded no targets | No targets available |
| The search matches nothing | No targets match your search criteria |
| The search matches nothing and the picker’s read was bounded | No target this picker loaded matches your search criteria; more exist than were read. |
| A tag selection resolves to no targets | No targets match these tags |
Health is not among these — as noted above, an offline or stale target is selectable and the deployment is created against it.
CLI Target Selection
Section titled “CLI Target Selection”Using the CLI for target selection:
# `deployment create` addresses everything by UUID, and needs targets of its own —# an environment alone does not supply them.mantisctl deployment create --solution-id <id> --environment-id <environment-uuid> \ --target <target-uuid>
# The same deployment addressed by slugmantisctl deploy <solution-slug> --env production --target <target-uuid>
# By tag (repeat --target-tag for multiple key=value pairs)mantisctl deployment create --solution-id <id> \ --target-tag role=web --target-tag region=us-east-1
# Explicit targets by UUID (repeat --target for each)mantisctl deployment create --solution-id <id> \ --target <target-uuid-1> --target <target-uuid-2> --target <target-uuid-3>Building a Target List from a File
Section titled “Building a Target List from a File”--target is repeatable, so you can expand a one-target-per-line file with
your shell:
# targets.txt - one target UUID per line (blank lines and # comments ignored)args=$(grep -v '^\s*#' targets.txt | grep -v '^\s*$' | sed 's/^/--target /')mantisctl deployment create --solution-id <id> $argsSelection Strategies
Section titled “Selection Strategies”Canary Deployment
Section titled “Canary Deployment”Deploy to a single target first:
┌─────────────────────────────────────────────────────────────┐│ Canary Strategy │├─────────────────────────────────────────────────────────────┤│ ││ Phase 1: Canary (1 target) ││ [✓] web-prod-01 ││ ││ Phase 2: Remaining (11 targets) ││ [ ] web-prod-02 through web-prod-12 ││ ││ ● Deploy Phase 1, then manually approve Phase 2 ││ │└─────────────────────────────────────────────────────────────┘Geographic Rollout
Section titled “Geographic Rollout”Deploy by region:
Phase 1: us-east-1 (tag: region=us-east-1)Phase 2: us-west-2 (tag: region=us-west-2)Phase 3: eu-west-1 (tag: region=eu-west-1)Role-Based Rollout
Section titled “Role-Based Rollout”Deploy by server role:
Phase 1: Workers (tag: role=worker)Phase 2: API servers (tag: role=api)Phase 3: Web servers (tag: role=web)Best Practices
Section titled “Best Practices”1. Always Preview Selection
Section titled “1. Always Preview Selection”Review matched targets before deploying:
Preview shows:├── Target count├── Target names├── Target status└── Any warnings2. Use Tags Consistently
Section titled “2. Use Tags Consistently”Standardize tags across your infrastructure:
| Tag | Purpose |
|---|---|
role | Server function |
region | Geographic location |
tier | Application tier |
team | Owning team |
3. Consider Target Status
Section titled “3. Consider Target Status”- Deploy to online targets for reliability
- Investigate stale targets before including
- Never deploy to offline targets in production
4. Document Selection Criteria
Section titled “4. Document Selection Criteria”Record why you selected specific targets:
Deployment: Emergency security patchSelection (default ANY): role=web OR region=us-east-1Reason: Patch critical vulnerability in US East web servers onlyTroubleshooting
Section titled “Troubleshooting”No Targets Found
Section titled “No Targets Found”Cause: Filter criteria too restrictive
Solution: Broaden filters or check tag values
Wrong Targets Selected
Section titled “Wrong Targets Selected”Cause: Incorrect filter or environment
Solution: Review selection preview before deploying
Target Missing from Selection
Section titled “Target Missing from Selection”Cause: Target not in environment or missing tags
Solution: Verify target assignment and tag values
Next Steps
Section titled “Next Steps”- Execution Modes - How targets are deployed
- Monitoring - Track deployment progress
- Creating Deployments - Start a deployment
- Overview - Return to deployments overview