Skip to main content
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.