Label

A label is a simple identifier for a stack or resource. Labels are how you identify and reference your stacks and resources in formae. Instead of using different terms like "name" or "id" for different technologies, formae uses label consistently throughout the platform.

Resource labels must be unique within a stack. This ensures you can always reference a specific resource without ambiguity.

Examples

A resource label in Pkl:

new bucket.Bucket {
  label = "my-s3-bucket"
  bucketName = "my-unique-bucket-name"
}

A stack label in Pkl:

new formae.Stack {
  label = "my-stack"
  description = "Stack for my resources"
}

Using labels in commands:

# Destroy resources in a specific stack by label
formae destroy --query="stack:production-api"

# View resources with a specific label
formae inventory resources --query="label:my-s3-bucket"

Tip: Use descriptive labels that clearly identify the purpose of your stacks and resources. 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 the resource a label so you can refer to it without having to know the provider's identifier. The label is derived from the resource's properties using a JSONPath query supplied by the plugin's labelConfig.

Each plugin ships a sensible default. The AWS plugin, for example, uses the Name tag ($.Tags[?(@.Key=='Name')].Value), so an EC2 instance tagged Name=web-server is discovered with 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 advances past whatever is already in the inventory, regardless of current label. 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

A label is a formae-side identifier that lives in formae's inventory; it is never sent to the cloud provider. Changing a label produces no cloud operations; only the inventory row is updated.

To rename a resource, set alias to its previous label and label to the new one. On apply, formae matches the existing row by the alias and updates it in place.

new vpc.VPC {
  label = "production-vpc"   // the NEW label
  alias = "vpc-008eef..."    // the PREVIOUS label
  cidrBlock = "172.31.0.0/16"
}

After a successful apply, the resource lives at production-vpc. The alias can stay in the forma: a subsequent apply with the alias still set is a no-op, because formae looks the row up by label first and only consults alias when no current-label match is found.

Common use cases

Naming a discovered resource. When the label discovery assigned isn't what you want (most often when discovery fell through to the provider identifier, like a VPC discovered as vpc-008eef40942ac586b), rename it as you bring it under management:

new vpc.VPC {
  label = "production-vpc"
  alias = "vpc-008eef40942ac586b"
  cidrBlock = "172.31.0.0/16"
}

Refactoring a stack. Rename a resource as part of a broader refactor without touching the cloud object:

new bucket.Bucket {
  label = "platform-logs"
  alias = "team-platform-bucket-logs"
  bucketName = "platform-logs"
}

Scope

Rename happens inline with formae apply in both reconcile and patch modes. There is no separate formae rename command.