​
Overview

Suga uses CDKTF (Cloud Development Kit for Terraform) to generate Terraform configurations. By default, the generated stacks use local state files. For production environments and team collaboration, you’ll want to configure a remote backend to store your Terraform state securely and enable state locking. This guide covers how to add backend configuration to your Suga-generated Terraform stacks for common backend providers.

​
Prerequisites

Ensure you have completed these steps before configuring a backend.
  1. Generate your Terraform stack using suga build (this runs CDKTF synthesis)
  2. Choose a backend provider (AWS S3, Google Cloud Storage, Azure Storage, Terraform Cloud, etc.)
  3. Create the backend storage resources (bucket, storage account, workspace, etc.)
  4. Ensure proper permissions are configured for accessing the backend

​
Understanding Suga’s CDKTF Output

When you run suga build, CDKTF synthesizes your infrastructure into standard Terraform JSON configuration files:
Generated Directory Structure
terraform/
└── stacks/
    └── <stack_name>/
        ├── cdk.tf.json      # Main configuration
        └── ...
The synthesized output can be found in the terraform directory.

​
Adding Backend Configuration

After running suga build, add a backend configuration file to the synthesized output:
1

Generate the Stack

Generate Terraform Stack
suga build
2

Create Backend Configuration

Create backend.tf in the synthesized stack directory:
Create Backend File
touch terraform/stacks/<stack_name>/backend.tf
3

Add Backend Configuration

Choose your backend provider and add the appropriate configuration:
backend.tf - AWS S3
terraform {
  backend "s3" {
    bucket         = "my-terraform-state-bucket"
    key            = "suga/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}
Ensure your S3 bucket has versioning enabled and consider enabling MFA delete for production environments.
4

Initialize and Deploy

Initialize Terraform
cd terraform/stacks/<stack_name>
terraform init
Deploy Infrastructure
terraform apply
Only the cdktf files are managed by Suga. You can safely add custom .tf files to the stack directory to extend the configuration.

​
Managing Multiple Environments

For managing multiple environments, we recommend using Terraform workspaces:
Create and Switch Workspaces
# Create and switch to staging environment
terraform workspace new staging

# Switch to production environment
terraform workspace new production
terraform workspace select production
Each workspace maintains its own state file, allowing you to manage different environments with the same configuration.
For comprehensive documentation on best practices, see the official Terraform workspace docs.