Tagging

Use tags to organize, filter, and manage your targets effectively.

What Are Tags?

Tags are key-value pairs attached to targets for organization and filtering:

target: web-prod-01
tags:
  role: web
  region: us-east-1
  tier: frontend
  team: platform

Tag Structure

Component	Description	Example
Key	Category name	role, region, team
Value	Specific value	web, us-east-1, platform

Naming Conventions

Rule	Good	Bad
Lowercase keys	role	Role, ROLE
Alphanumeric	team_name	team-name!
Descriptive	deployment_group	dg
No spaces	data_center	data center

Adding Tags

Single Target

┌─────────────────────────────────────────────────────────────┐
│  Target: web-prod-01                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Tags:                                                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ role         │ web                    │ [×]          │  │
│  │ region       │ us-east-1              │ [×]          │  │
│  │ tier         │ frontend               │ [×]          │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  Add Tag:                                                   │
│  Key: [team_____________]  Value: [platform_________]       │
│                                            [Add Tag]        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via REST API

Tags are created once, then attached to targets by tag ID. Tag management is performed in Lens or via the REST API (there is no mantisctl tag subcommand).

# Attach one or more existing tags to a target
curl -X POST "$MANTIS_URL/api/v1/targets/<target-id>/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["<role-web-tag-id>", "<region-tag-id>"]}'

Removing Tags

From UI

Click the [×] next to any tag to remove it.

Via REST API

# Detach one or more tags from a target
curl -X DELETE "$MANTIS_URL/api/v1/targets/<target-id>/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["<role-web-tag-id>"]}'

Standard Tag Taxonomy

Recommended Tags

Tag Key	Purpose	Example Values
role	Server function	web, api, worker, db, cache
environment	Deploy environment	development, staging, production
region	Geographic location	us-east-1, eu-west-1, ap-south-1
tier	Application tier	frontend, backend, data
team	Owning team	platform, payments, auth
service	Service name	user-api, order-service
cost_center	Billing allocation	engineering, operations

Example Tag Sets

Web Server:

role: web
tier: frontend
region: us-east-1
team: platform

Database Server:

role: database
tier: data
db_type: postgresql
replication: primary

Worker Node:

role: worker
queue: high-priority
service: order-processor

Filtering by Tags

Via REST API

GET /api/v1/targets returns each target with its tags, so you can filter client-side (the list endpoint has no tag query parameter). Tag filtering is not available in the Lens UI; use the jq client-side approach below.

# List targets tagged role=web
curl "$MANTIS_URL/api/v1/targets" -H "Authorization: Bearer $TOKEN" | \
  jq '.data[] | select(.tags[] | .key == "role" and .value == "web")'

Tags in Deployments

Target Selection by Tag

Deploy to targets matching tag criteria with --target-tag (repeatable):

mantisctl deployment create --solution-id customer-portal \
  --source-version 1.3.0 \
  --target-tag role=web \
  --target-tag region=us-east-1

Tag-Based Rollout Strategy

Staged Deployment by Tag

Phase 1: Deploy to tag:canary=true
Phase 2: Deploy to tag:region=us-east-1
Phase 3: Deploy to tag:region=us-west-2
Phase 4: Deploy to tag:region=eu-west-1

Tag-Based Organization

By Team

Tags: team=platform, team=payments, team=auth

By Environment

Tags: environment=production, environment=staging, environment=development

By Service

service=user-api:
  - user-api-01
  - user-api-02

service=order-service:
  - order-svc-01
  - order-svc-02

service=payment-gateway:
  - payment-01
  - payment-02

Tag Management Best Practices

1. Establish a Taxonomy

Define standard tags before deployment:

## Required Tags

All targets MUST have:

- role: Server function (web, api, worker, db)
- environment: Environment name (from Mantis environments)
- team: Owning team

## Optional Tags

- region: Geographic region
- service: Service/application name
- cost_center: For billing
- maintenance_window: Preferred maintenance time

2. Use Consistent Values

Instead of	Use
prod, production, prd	production
US-East-1, us_east_1	us-east-1
WebServer, web-server	web

3. Avoid Over-Tagging

Keep tags meaningful:

Good	Avoid
role=web	is_web_server=true
team=platform	managed_by_platform_team=yes
tier=frontend	tier=frontend_presentation_layer

4. Document Tag Usage

Maintain documentation of tag meanings:

Tag	Values	Description
role	web, api, worker, db	Server’s primary function
region	us-east-1, us-west-2, etc.	AWS region location
tier	frontend, backend, data	Application architecture tier

5. Audit Tags Regularly

Review tags periodically:

# List all unique tag keys across targets
curl -s "$MANTIS_URL/api/v1/targets" -H "Authorization: Bearer $TOKEN" | \
  jq -r '.data[].tags[].key' | sort | uniq

# Find targets missing a required tag key (e.g. role)
curl -s "$MANTIS_URL/api/v1/targets" -H "Authorization: Bearer $TOKEN" | \
  jq '.data[] | select([.tags[].key] | index("role") | not) | .name'

# Find targets carrying a deprecated tag
curl -s "$MANTIS_URL/api/v1/targets" -H "Authorization: Bearer $TOKEN" | \
  jq '.data[] | select([.tags[].key] | index("deprecated")) | .name'

Troubleshooting

Tags Not Saving

Cause: Invalid characters in key or value

Solution: Use lowercase alphanumeric characters and underscores only

Filter Returns No Results

Cause: Tag values don’t match exactly

Solution: Check for typos, case sensitivity, extra spaces

Next Steps

• Managing Targets - Target management
• Health Status - Monitor target health
• Overview - Return to targets overview