Skip to main content

Best Practices Guide

Scanning Best Practices​

Start Small, Then Scale​

When scanning a new environment, start with specific services before doing a full account scan:

# Test with a single service first
terraback aws s3 scan --region us-east-1 --output-dir ./test-output

# Review the output
ls -la ./test-output/

# Then scan all resources
terraback scan all aws -r us-east-1 -o ./full-output

Use Dependency Scanning Wisely​

The --with-deps flag (Professional) discovers related resources automatically. Use it when you need complete resource graphs:

# Scan EC2 instances with all dependencies (VPCs, subnets, security groups, etc.)
terraback aws ec2 scan-instances --with-deps --region us-east-1 --output-dir ./output

When to use --with-deps:

  • Migrating a complete application stack
  • Understanding resource relationships
  • Generating comprehensive Terraform modules

When to skip --with-deps:

  • Scanning specific isolated resources
  • Quick inventory of a single service
  • Testing or exploration

Leverage Caching​

Caching is opt-in. Pass --cache to terraback scan all to store API responses and speed up repeated scans (it is off by default):

# Enable caching for this scan
terraback scan all aws -r us-east-1 --cache -o ./output

# View cache statistics
terraback cache stats

# Clear cache when you need fresh data
terraback cache clear

# Invalidate specific service cache
terraback cache invalidate --service ec2

Caching tips:

  • Caching is off by default; enable it with --cache
  • Cache TTL is 60 minutes by default
  • Clear cache after making infrastructure changes
  • Use caching for iterative scanning during development

Output Organization​

Standard Output​

For simple projects, use standard output:

terraback scan all aws -r us-east-1 -o ./generated

This creates:

generated/
├── provider.tf
├── vpc.tf
├── subnets.tf
├── security_groups.tf
├── s3_bucket.tf
└── import/
    └── *.json

Enterprise Modules (Professional)​

For larger environments, use enterprise modules for organized output:

terraback scan all aws -r us-east-1 --enterprise-modules -o ./enterprise

This creates a modular structure:

enterprise/
├── main.tf
├── variables.tf
├── outputs.tf
├── provider.tf
├── imports.tf
├── config/
│   ├── default.tfvars
│   ├── dev.tfvars
│   └── production.tfvars
└── modules/
    ├── vpc/
    ├── ec2-instance/
    └── s3-bucket/

Authentication Best Practices​

AWS​

Use AWS profiles for multiple accounts:

# Configure profiles
aws configure --profile production
aws configure --profile staging

# Scan with specific profile
terraback aws ec2 scan-instances --profile production --region us-east-1 --output-dir ./prod-output
terraback aws ec2 scan-instances --profile staging --region us-east-1 --output-dir ./staging-output

Azure​

Use service principals for automation:

# Set environment variables
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_SUBSCRIPTION_ID="your-subscription-id"

# Scan resources
terraback scan all azure -g my-resource-group -o ./azure-output

GCP​

Use service accounts for automation:

# Set credentials path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

# Scan resources
terraback scan all gcp --project-id my-project -o ./gcp-output

Working with Generated Code​

Review Before Import​

Always review generated Terraform before importing:

# Generate code
terraback scan all aws -r us-east-1 -o ./output

# Review generated files
cd ./output
cat provider.tf
cat vpc.tf

# Initialize Terraform
terraform init

# Validate syntax
terraform validate

Import Workflow​

  1. Generate - Run Terraback scan
  2. Review - Check generated .tf files
  3. Initialize - Run terraform init
  4. Validate - Run terraform validate
  5. Import - Use generated import commands
  6. Plan - Run terraform plan to verify no drift
# Example import workflow
cd ./output
terraform init
terraform validate

# Import resources (from generated import/ files)
terraform import aws_vpc.main vpc-12345678
terraform import aws_s3_bucket.mybucket mybucket

# Verify - should show no changes
terraform plan

Performance Tips​

Parallel Scanning (Professional)​

For large environments, use parallel scanning:

# Use multiple 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-1000 resources): 4-8 workers
  • Large accounts (over 1000 resources): 8-16 workers

Note: Higher parallelism increases API rate. Monitor for throttling.

Region-Specific Scanning​

Scan specific regions to reduce scope:

# Scan only production regions
terraback scan all aws -r us-east-1 -o ./us-east-1
terraback scan all aws -r eu-west-1 -o ./eu-west-1

Common Pitfalls​

API Rate Limits​

Cloud providers have API rate limits. If you encounter throttling:

  1. Reduce parallel workers
  2. Use caching between scans
  3. Scan during off-peak hours
  4. Scan specific services instead of all

Large State Files​

For environments with thousands of resources:

  1. Scan by service or region
  2. Use enterprise modules to organize output
  3. Consider splitting into multiple Terraform workspaces

Credential Security​

  • Never commit credentials to version control
  • Use environment variables or profiles
  • Rotate credentials regularly
  • Use read-only permissions for scanning

Multi-Cloud Workflows​

When managing multiple cloud providers:

# Create separate output directories
mkdir -p terraform/{aws,azure,gcp}

# Scan each provider
terraback scan all aws -r us-east-1 -o ./terraform/aws
terraback scan all azure -g my-rg -o ./terraform/azure
terraback scan all gcp --project-id my-project -o ./terraform/gcp

Getting Help​