Speed and Performance

Speed is Terraback's core design goal. Scanning a cloud account and generating Terraform should take seconds to minutes, not hours or days. This guide explains the features that make Terraback fast and how to tune them for large environments.

What to Expect

These are rough estimates, not guarantees. Real scan time depends on your account size, the cloud provider's API rate limits, and network latency. In practice the provider's API throttling is usually the bottleneck, not Terraback itself.

Account size	Estimated scan time (with --parallel)
Under 100 resources	Around 30 seconds
Hundreds of resources	1-3 minutes
1,000+ resources	5-20 minutes (lower with --cache on repeat runs)

Importing is fast too: with the bulk method (Terraform 1.5+ import blocks), hundreds of resources import in roughly 2-3 minutes in a single operation instead of one terraform import call each.

Parallel Scanning

The --parallel N flag runs scanners concurrently. It controls both the number of top-level scanners running at once and the worker pool inside each scanner, bounded to the range 1-32.

# Scan with 8 parallel workers
terraback scan all aws -r us-east-1 --parallel 8 -o ./output

Recommendations:

• Small accounts (under 100 resources): 1-2 workers
• Medium accounts (100-1,000 resources): 4-8 workers
• Large accounts (over 1,000 resources): 8-16 workers

Higher parallelism increases your API request rate. If you hit throttling, reduce the worker count. Parallel scanning is a Professional feature.

Caching

Caching is opt-in. Pass --cache to store API responses so repeated scans skip redundant API calls. The cache is dual-level (in-memory plus on-disk) with a 60 minute TTL by default.

# First scan populates the cache
terraback scan all aws -r us-east-1 --cache -o ./output

# Re-run within the TTL reuses cached responses
terraback scan all aws -r us-east-1 --cache -o ./output

Use --cache-encrypt (which requires --cache) to encrypt cache files at rest with a per-install Fernet key:

terraback scan all aws -r us-east-1 --cache --cache-encrypt -o ./output

Caching is most useful during iterative development, when you scan the same account repeatedly. Clear it with terraback cache clear after you change infrastructure.

Multi-Region Scanning

By default Terraback scans a single region or location. The --all-regions flag scans every enabled region in parallel, splitting global and regional services so each region is covered without duplicating global resources.

# Scan every enabled AWS region in parallel
terraback scan all aws --all-regions --parallel 8 -o ./output

This is a Professional feature and is the fastest way to inventory an account that spans many regions.

Resuming Interrupted Scans

For very large accounts, use --resume to continue an interrupted scan without re-running scanners that already completed:

terraback scan all aws -r us-east-1 --parallel 8 --resume -o ./output

Built-In Reliability at Speed

Terraback pushes API rate limits hard while staying within them automatically. You get these protections without configuration:

• Automatic retry with backoff. Throttled or transient API errors are retried with exponential backoff across AWS, Azure, and GCP, so a brief rate-limit spike does not fail the whole scan.
• Global API throttle. A shared concurrency limit caps in-flight API calls per provider so high --parallel values do not overwhelm the cloud APIs.
• Connection pooling. The AWS client uses an enlarged connection pool so many concurrent workers reuse connections instead of exhausting them.

If you still see throttling on a very large account, lower --parallel, enable --cache for repeat runs, or scan specific services or regions at a time.

Fast Import

Generating Terraform is only half the job; importing it into state must be fast too. The provider-level import command imports every scanned resource in one command, and with Terraform 1.5+ it uses import blocks to import them all in a single bulk operation.

# Bulk import everything Terraback scanned
terraback aws import -o ./output --method bulk --yes

See the Import Guide for method details and the drift-validation workflow.

Tuning Checklist

1. Start with --parallel 8 and adjust up or down based on throttling.
2. Add --cache when you scan the same account more than once.
3. Use --all-regions instead of looping over regions manually.
4. Use --resume to recover from interruptions on large scans.
5. Import with --method bulk (Terraform 1.5+) for the fastest state import.