Stack

A stack is a collection of infrastructure resources. You decide what resources belong together in a stack. Stacks are the basic unit of management in formae, enabling features like automatically removing resources when they're no longer needed during reconciliation.

When you apply a forma, formae looks for existing stacks by label. If a stack with the specified label doesn't exist, it creates a new one. This allows you to define infrastructure declaratively without explicitly creating stacks beforehand.

Stacks are the recommended way to organize your infrastructure code in version control. formae manages resources at the stack level, enabling resource tracking and lifecycle operations. You can extract any managed stack in your preferred format, allowing integration with version control systems, saving to files, or applying to new environments. This provides flexibility across different operational environments while maintaining state consistency throughout the infrastructure lifecycle.

Examples

A stack in Pkl:

new formae.Stack {
  label = "production-api"
  description = "Production API infrastructure"
}

Resources in a stack:

// In your forma, resources are automatically assigned to the stack
forma {
  new formae.Stack {
    label = "my-stack"
  }

  new bucket.Bucket {
    label = "api-bucket"
    bucketName = "my-api-bucket"
  }

  new instance.Instance {
    label = "api-server"
    instanceType = "t3.medium"
  }
}

Common stack patterns: - By environment: dev-infrastructure, staging-infrastructure, production-infrastructure - By application: user-service, payment-service, analytics-pipeline - By layer: networking, databases, compute

Tip: Choose stack boundaries that match how you want to deploy and version your infrastructure. Smaller stacks give you more granular control, while larger stacks simplify dependencies.

Stack Constraints

Each resource can only belong to one stack. This ensures clear ownership and prevents conflicts in resource management and state tracking.

This single-stack rule:

• Makes it clear which stack is responsible for each resource
• Simplifies dependency management between resources
• Enables accurate state tracking and version control
• Prevents conflicts from multiple stacks trying to manage the same resource

When planning your infrastructure, consider this constraint early to create logical stack boundaries that match your application's architecture.