A label is how you identify and reference a stack or resource in formae.
Instead of different terms like “name” or “id” for different technologies,
formae uses label consistently throughout the platform.
Resource labels must be unique within a stack, so you can always reference a
specific resource without ambiguity.
Examples
A resource label in Pkl:
A stack label in Pkl:
Using labels in commands:
Use descriptive labels that clearly identify the purpose of a stack or
resource. Labels are how you’ll reference and query your infrastructure.
Labels for discovered resources
When formae discovers a resource that isn’t already managed, it assigns a
label so you can refer to it by a readable name rather than the provider’s raw
identifier. The label is taken from one of the resource’s own properties, so a
discovered resource arrives with a name that already means something to you.
Which property? Each plugin decides, and ships a sensible default. The rule is
expressed as a small JSONPath
query in the plugin’s
labelConfig. The syntax
can look dense at first, but it is really just “pull this one field out of the
resource”. The AWS plugin’s default reads the Name tag:
Read that as: from the resource’s Tags, take the one whose Key is Name,
and use its Value. So an EC2 instance tagged Name=web-server is discovered
with the label web-server. You can override the rule per resource type in your
formae.conf.pkl.
If the query returns nothing (the resource has no Name tag, or your
override matched no fields), formae falls back to the resource’s provider
identifier as the label. An EC2 instance with no Name tag would be
discovered with a label like i-0abc1234.
Collisions
If two discovered resources would yield the same label, formae appends a
numeric suffix to disambiguate. Three Aurora replica instances all tagged
Name=database are discovered as database, database-1, database-2, in
the order they are discovered. The first instance keeps the unsuffixed
label; later ones get the next free number.
Renaming a resource later does not free its old label for future
discoveries: the suffix counter is derived from labels currently in the
inventory, not a separate counter. Renaming database to aurora-writer
while database-1 and database-2 still exist means the next discovery
that would land on database becomes database-3, not database.
Renaming a resource
Because a label is a formae-side identifier that is never sent to the cloud
provider, you can rename a resource with no cloud operation at all: only the
inventory row changes. This makes labels safe to refactor, and it is how you give
a readable name to a resource that discovery labeled with a raw provider
identifier.
For the steps, see Rename a resource.
See also
- Resources: managed versus unmanaged resources, and how discovered ones are brought under management.
- Configuration: overriding a plugin’s default label extraction.
- Resolvable: referencing a resource by its label via
.res.
