Tagging AWS Resources
AWS tags are key-value pairs you attach to resources. They show up in the AWS console, Cost Explorer, and billing reports, making it easier to track costs, identify resource owners, enforce policies, and filter resources across accounts.
Stelvio gives you three tagging layers that work together:
- Auto-tags — applied automatically to every resource
- Global tags — set once in
StelvioAppConfig, applied to all components - Component tags — set per component for fine-grained control
Auto-Tags
Stelvio automatically tags every resource with:
| Tag | Value | Example |
|---|---|---|
stelvio:app |
Your app name from StelvioApp("name") |
my-app |
stelvio:env |
The current deployment environment | dev, staging, prod |
These tags are always present — you don't need to configure anything. They're applied through the AWS provider's default_tags, so they appear on every taggable resource Stelvio creates. They also reach other AWS resources you create in @app.run.
This means you can always filter resources in the AWS console or Cost Explorer by app and environment, even if you never set any custom tags.
Global Tags
Set organization-wide tags in @app.config to apply them to all components:
from stelvio.app import StelvioApp
from stelvio.config import StelvioAppConfig
app = StelvioApp("my-app")
@app.config
def config(env: str) -> StelvioAppConfig:
return StelvioAppConfig(
tags={
"Team": "platform",
"CostCenter": "infra",
}
)
Global tags are applied through AWS provider default_tags, alongside auto-tags.
Set app-wide tags here, not in a global customize
StelvioAppConfig.tags reaches every taggable resource and merges with other tags key by
key. tags in a global customize don't merge. A dict's tags are dropped wherever the
resource gets tags of its own: from a component's tags=, or the Name tag Stelvio sets
on Vpc and DocumentDb resources and the stelvio:subnet-type tag on Vpc subnets. A
callable's tags replace all of the resource's tags, these included, unless the callable
merges in props.get("tags", {}) itself. Auto-tags and global tags still apply.
Component Tags
You can set tags on a specific component:
from stelvio.aws.queue import Queue
orders = Queue(
"orders",
tags={
"Service": "checkout",
"Owner": "payments-team",
},
)
Component tags are applied to that component's taggable AWS resources.
Precedence
Tags from these levels merge key by key. If the same key exists at more than one level, the more specific level wins:
- Auto-tags (
stelvio:app,stelvio:env) — lowest priority - Global tags (
StelvioAppConfig.tags) - Component tags (
tags=...on a component)
Example:
from stelvio.aws.queue import Queue
from stelvio.config import StelvioAppConfig
@app.config
def config(env: str) -> StelvioAppConfig:
return StelvioAppConfig(tags={"Shared": "global", "GlobalOnly": "yes"})
@app.run
def run() -> None:
Queue("jobs", tags={"Shared": "component", "ComponentOnly": "yes"})
Result for jobs queue tags:
Shared=component(component overrides global)GlobalOnly=yesComponentOnly=yes- auto-tags are still present
tags in a component's own customize replace its whole tags= dict, so a key you set only in
tags= is dropped. On Vpc and DocumentDb resources they also drop the Name tag Stelvio
sets, and on Vpc subnets the stelvio:subnet-type tag. Auto-tags and global tags still
apply.
Common Patterns
Cost allocation by team:
StelvioAppConfig(tags={"CostCenter": "platform"})
Environment-specific tags:
@app.config
def config(env: str) -> StelvioAppConfig:
tags = {"Team": "backend"}
if env == "prod":
tags["OnCall"] = "backend-oncall"
return StelvioAppConfig(tags=tags)
Per-service ownership:
Queue("orders", tags={"Service": "checkout", "Owner": "payments-team"})
Queue("notifications", tags={"Service": "notifications", "Owner": "comms-team"})
Tag Propagation
For components that create internal resources (for example, subscription-generated Lambda functions), Stelvio propagates component tags to those generated internals where tagging is supported.
Examples:
Queue(..., tags=...)+queue.subscribe(...)— generated subscription function inherits tagsTopic(..., tags=...)+topic.subscribe(...)— generated subscription function inherits tagsRestApi(..., tags=...)+ string/config handlers — generated route functions inherit tags
Non-Taggable Resources
Not every AWS resource type supports tags. Stelvio applies tags where AWS supports them and skips non-taggable resource types.
Note
AWS Lambda LayerVersion does not accept tags in the current Pulumi AWS provider API. Because of that, Stelvio Layer does not expose a tags parameter.