Forma

A forma (plural: formae) is an infrastructure declaration. When you apply a forma, formae processes it to create, update, or delete resources.

A forma defines the exact scope of change, whether that be an entire environment or a single update. This gives you the ability to manage your deployment at any level of granularity, without being forced to deploy unrelated resources.

Formae support three operations: apply a forma to provision or modify infrastructure, extract a forma from existing resources to capture their current state and reuse it elsewhere, and destroy a forma to decommission the resources it declares.

A forma can be temporary (used once) or committed to version control for long-term management.

Example

amends "@formae/forma.pkl"
import "@formae/formae.pkl"
import "@aws/aws.pkl"
import "@aws/s3/bucket.pkl"

forma {
  new formae.Stack {
    label = "my-app"
    description = "My application stack"
  }

  new formae.Target {
    label = "my-aws-target"
    config = new aws.Config {
      region = "us-east-1"
    }
  }

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

Every forma includes at least one Stack to organize resources and at least one Target to specify where they are applied.

Learn to Write Forma

To author a forma, see Fundamentals for structure, properties, resource references, and common pitfalls.

Note: A forma might not complete successfully. Failures can occur between the agent and the target systems. Incomplete execution leaves infrastructure in a consistent state. If the failure is recoverable or due to user input, reapply the forma. The agent retries when possible.