Skip to main content
When you run suga build, Suga transforms your high-level project specification into production-ready Terraform code. This page explains how this transformation works, what gets generated, and how to customize the output.

​
The Build Process

The suga build command orchestrates a multi-step process:
1

Load Project

Suga reads your suga.yaml file and validates the configuration:
suga.yaml
target: suga/aws@1
name: my-app

services:
  api:
    subtype: lambda
    dev:
      script: npm run dev

buckets:
  subtype: s3
  uploads:
    access:
      api: [read, write]
2

Fetch Platform

Suga retrieves the target platform specification from the registry:
# Platform: suga/aws@1
- Services: lambda, fargate
- Buckets: s3
- Databases: neon
- Entrypoints: cloudfront
- Infrastructure: vpc, loadbalancer, security-groups
3

Map Resources

Each project resource is mapped to a platform blueprint, by the selected subtype:
suga.yaml
services:
  api:
    subtype: fargate

buckets:
  uploads:
    subtype: s3

Project           Platform Blueprint     Plugin
-------           ------------------     ------
service "api"  →  services.fargate    →   suga/aws/fargate
bucket "uploads" → buckets.s3        →   suga/aws/s3-bucket
4

Generate Terraform Output

Suga then uses Terraform CDK to resolve the modules, variables and other configuration to produce a Terraform stack.
terraform/stacks/my-app/
├── cdk.tf.json          # Main Terraform Entrypoint
└── .terraform/         # Plugin Terraform modules
    └── modules/
        ├── api/
        ├── api_image/
        ├── uploads_bucket/
        └── ...

​
Module Naming

Suga generates consistent module names for application resources:

​
Terraform Module Names

Pattern: {resource_name}_{submodule_name} 
module "api"       # Service named "api"
module "api_image" # Container image submodule for the "api" service
module "uploads"   # Bucket named "uploads"

​
Dependency Management

Suga automatically manages resource dependencies:

​
Explicit Dependencies

Defined by platform:
Platform blueprint
services:
  fargate:
    depends_on:
      - ${infra.aws_vpc}
      - ${infra.aws_lb}
Results in:
Generated Terraform
module "service_api" {
  # ...
  depends_on = [
    module.aws_vpc,
    module.aws_lb
  ]
}

​
Implicit Dependencies

Created by resource references:
Automatic dependency
module "service_api" {
  vpc_id = module.aws_vpc.vpc_id  # Creates implicit dependency
}

​
Multi-Environment Support

The same generated Terraform can deploy to multiple environments using Terraform workspaces and environment-specific variable files. This allows you to maintain a single infrastructure definition while customizing configuration for dev, staging, and production.

Terraform Environment Management

Learn how to manage multiple environments with Terraform workspaces and variables
 See the CLI reference for complete build options.

​
Getting Help

If you encounter issues during build:
  1. Review platform documentation in the platform browser
  2. Contact Suga support

​
Best Practices

​
1. Version Control Generated Terraform

Commit generated Terraform to version control: 
git add terraform/
git commit -m "Update infrastructure"
Benefits:
  • Track infrastructure changes over time
  • Review Terraform diffs in pull requests
  • Rollback if needed

​
2. Validate Before Deploying

Always validate and preview: 
suga build
cd terraform/stacks/my-app
terraform init
terraform validate
terraform plan  # Review before apply

​
Learn More

Deployment Guide

Understand the deployment process

Build Command

Complete CLI reference for suga build

Platform Development

Learn how platforms define infrastructure

Terraform Configuration

Best practices for Terraform configuration