Deployment Overview

Deploying with Suga means running standard Terraform commands on the infrastructure generated by suga build. This page explains the deployment lifecycle, how to deploy to different environments, and best practices for production deployments.

Deployment Overview

Suga’s deployment model is transparent and uses standard tools:

Generate Terraform - suga build creates Terraform modules
Configure Provider - Set up cloud provider credentials and configuration
Initialize Terraform - Download providers and modules
Preview Changes - Review what will be created/modified
Apply Changes - Deploy to your cloud provider
Verify Deployment - Test deployed resources

The Deployment Lifecycle

Build Infrastructure

Generate Terraform from your project:

suga build

Output:

✓ Terraform generated successfully
  output written to terraform/stacks/my-app

Next steps:
1. Run cd terraform/stacks/my-app to move to the stack directory
2. Initialize the stack terraform init -upgrade
3. Optionally, preview with terraform plan
4. Deploy with terraform apply

Navigate to Stack

Change to the generated Terraform directory:

cd terraform/stacks/my-app

Contents:

my-app/
├── cdk.tf.json          # Main Terraform Entrypoint
└── .terraform/          # Plugin Terraform modules
    └── modules/
        ├── api/
        ├── api_image/
        ├── uploads_bucket/
        └── ...

Configure Cloud Provider

Set up provider configuration and credentials:

# Configure credentials
aws configure

Create provider configuration:

provider.tf

provider "aws" {
  region = "us-west-2"
}

Files like provider.tf and terraform.tfvars are preserved across builds and won’t be overwritten.

Initialize Terraform

Download providers and modules:

terraform init -upgrade

This downloads:

Cloud provider Terraform providers (AWS, GCP, etc.)
Plugin modules referenced by your platform
Backend configuration (if configured)

Preview Changes

Review what Terraform will create:

terraform plan

Output shows:

Resources to be created (+)
Resources to be modified (~)
Resources to be deleted (-)

Always review the plan carefully before applying, especially in production environments.

Deploy

Apply the Terraform configuration:

terraform apply

Terraform will:

Show the plan again
Ask for confirmation
Create resources in your cloud account
Save state to track resources

Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

Outputs:
entrypoint_web_url = "https://d123abc.cloudfront.net"
service_api_function_name = "my-app-api"

Verify Deployment

Test your deployed application:

# Get the entrypoint URL from outputs
terraform output entrypoint_web_url

# Test the endpoint
curl https://d123abc.cloudfront.net/api/health

Managing Deployments

Updating Your Application

When you make changes to your project:

Rebuild Terraform:
```
suga build
```

Preview changes:

cd terraform/stacks/my-app
terraform plan

Apply updates:
```
terraform apply
```

Terraform intelligently updates only what changed:

Modified services are redeployed
New resources are created
Removed resources are deleted
Unchanged resources remain untouched

Deploying Code Updates

When you update service code without changing infrastructure:

# Simply re-run terraform apply
cd terraform/stacks/my-app
terraform apply

Terraform automatically:

Builds new container images from your updated code
Pushes images to the container registry (ECR, Artifact Registry, etc.)
Updates services to use the new images
Handles rolling deployments with zero downtime

No manual Docker commands needed - the generated Terraform includes container build and push logic.

CI/CD pipelines typically automate this by running terraform apply on every commit. See the CI/CD Authentication Guide for details.

Rolling Back

If a deployment causes issues, roll back:

# Revert code changes
git revert <commit-hash>

# Rebuild Terraform
suga build

# Apply previous configuration
cd terraform/stacks/my-app
terraform apply

Or roll back to a previous Terraform state:

# List state backups
terraform state list

# If using versioned state backend, restore previous version
# (AWS S3, GCS, Terraform Cloud all support versioning)

Destroying Resources

When you’re done with a deployment:

cd terraform/stacks/my-app
terraform destroy

terraform destroy permanently deletes all cloud resources. Databases, buckets, and all data will be lost. Use with extreme caution, especially in production.

Multi-Environment Deployments

Deploy the same application to multiple environments (dev, staging, production) using Terraform workspaces and environment-specific variable files. This allows you to maintain a single infrastructure definition while customizing configuration per environment.

Terraform Environment Management

Learn how to manage multiple environments with Terraform workspaces and variables

Cloud Provider Setup

Each cloud provider requires specific credentials and permissions. Detailed setup instructions including required permissions, authentication methods, and provider configuration are available in the provider-specific guides:

AWS Deployment

AWS credentials, IAM permissions, and configuration

GCP Deployment

GCP service accounts, permissions, and configuration

Azure Deployment

Azure credentials, RBAC, and configuration

Terraform State Management

Terraform state tracks deployed resources and must be managed carefully. By default, state is stored locally, which is suitable for personal projects but not recommended for teams. For production deployments, use a remote backend for state locking, versioning, and team collaboration.

Terraform Backend Configuration

Complete guide to configuring remote state backends (S3, GCS, Terraform Cloud)

CI/CD Integration

Automate deployments with CI/CD pipelines to build infrastructure and deploy on every commit. Common patterns include GitHub Actions, GitLab CI, CircleCI, and Jenkins.

CI/CD Authentication Guide

Learn how to authenticate Suga in CI/CD pipelines with example workflows

Best Practices

1. Always Preview Before Applying

terraform plan  # Review changes
terraform apply  # Only after reviewing

2. Use Remote State for Teams

Configure a remote backend for team deployments. See the Terraform Backend Configuration guide.

3. Separate Environments

Use Terraform workspaces or separate state files. See the Environment Management docs.

4. Version Control Everything

Commit generated Terraform to git:

git add terraform/
git commit -m "Update infrastructure"

5. Test in Non-Production First

Always deploy to dev/staging before production:

# Deploy to dev
terraform workspace select dev
terraform apply

# Test thoroughly
# Then deploy to prod
terraform workspace select prod
terraform apply

6. Use Terraform Variables for Configuration

Use variable files for environment-specific configuration. See the Terraform Configuration guide.

7. Monitor Deployments

Set up monitoring for deployed resources:

CloudWatch (AWS)
Cloud Monitoring (GCP)
Application Performance Monitoring (APM) tools

8. Document Your Deployments

Maintain deployment documentation:

DEPLOYMENT.md

## Production Deployment

Ensure tests pass: `npm test`
Build infrastructure: `suga build`
Review changes: `terraform plan`
Deploy: `terraform apply`
Verify: `curl https://api.example.com/health`
Monitor: Check CloudWatch dashboard

Troubleshooting

Common Deployment Issues

“No valid credential sources found” Solution: Configure cloud provider credentials properly. “Resource already exists” Solution: Import existing resource into Terraform state:

terraform import <resource_type>.<name> <resource_id>

“State lock timeout” Solution: Another apply is running, or a previous one crashed. Release lock:

terraform force-unlock <lock-id>

“Plan shows unwanted changes” Solution: Check for drift between state and actual resources:

terraform refresh
terraform plan

Learn More

Infrastructure Generation

Understand how Terraform is generated

Terraform Environment Management

Learn how to manage multiple environments with Terraform workspaces and variables

Terraform Configuration

Best practices for Terraform configuration

Local Development

How to develop applications locally with Suga

Getting Started

Core Concepts

Develop

Deploy

Guides

Resources

Deployment Overview