Configuration Guide

Configuration Overview

Terraback can be configured through command-line options, environment variables, and configuration files to customize scanning behavior and output.

Command-Line Options

Global Options

Option	Description
--verbose, -v	Enable verbose output
--debug	Enable debug logging
-o, --output-dir	Output directory for generated files

Scan Options

Option	Description	Default
-r, --region	AWS region, Azure location, or GCP region	Provider default
-p, --profile	AWS profile name	default
-g, --resource-group	Azure resource group	Required for Azure
--project-id	GCP project ID	Required for GCP
--with-deps	Enable dependency scanning	false
--parallel N	Number of parallel workers	1
--enterprise-modules	Generate enterprise module structure	false
--cache / --no-cache	Cache API responses for faster re-scans	--no-cache (off)
--cache-encrypt	Encrypt cache files at rest (requires --cache)	false
--all-regions	Scan all enabled regions/locations in parallel	false
--resume	Resume an interrupted scan	false
--preview	Run terraform plan preview after scan	false

Environment Variables

AWS Configuration

# AWS credentials
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_SESSION_TOKEN="optional-session-token"

# Default region
export AWS_DEFAULT_REGION="us-east-1"

# AWS profile
export AWS_PROFILE="myprofile"

Azure Configuration

# Azure service principal
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"

GCP Configuration

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

# Project ID
export GOOGLE_CLOUD_PROJECT="your-project-id"

Terraback Configuration

# Log level (DEBUG, INFO, WARNING, ERROR)
export TERRABACK_LOG_LEVEL="INFO"

# Log file path
export TERRABACK_LOG_FILE="/path/to/terraback.log"

Output Configuration

Standard Output Structure

Default output with -o ./output:

output/
├── provider.tf           # Provider configuration
├── vpc.tf                # VPC resources
├── subnets.tf            # Subnet resources
├── security_groups.tf    # Security group resources
├── s3_bucket.tf          # S3 bucket resources
├── ...                   # Additional resource files
└── import/               # Import commands
    ├── vpc_import.json
    ├── subnet_import.json
    └── ...

Enterprise Module Structure

Output with --enterprise-modules:

output/
├── main.tf               # Module instantiation
├── variables.tf          # Root variables
├── outputs.tf            # Root outputs
├── provider.tf           # Provider configuration
├── imports.tf            # Import blocks
├── config/               # Environment configurations
│   ├── default.tfvars
│   ├── dev.tfvars
│   ├── production.tfvars
│   └── test.tfvars
└── modules/              # Individual modules
    ├── vpc/
    │   ├── main.tf
    │   ├── variables.tf
    │   ├── outputs.tf
    │   └── README.md
    ├── s3-bucket/
    ├── lambda-function/
    └── ...

License Configuration

License File Location

License information is stored in:

• Linux/macOS: ~/.terraback/license.jwt
• Windows: %USERPROFILE%\.terraback\license.jwt

License Status

# Check current license
terraback license status

# Diagnose license issues
terraback license doctor

License Activation

# Activate a license key
terraback license activate YOUR-LICENSE-KEY

Cache Configuration

Caching is opt-in. By default Terraback does not cache API responses (--no-cache). Pass --cache to terraback scan all to store API responses and speed up repeated scans:

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

# Enable caching and encrypt the cache files at rest
terraback scan all aws -r us-east-1 --cache --cache-encrypt -o ./output

Cache Location

When --cache is enabled, cached data is stored in the user cache directory under:

• ~/.terraback/cache/

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

Cache Management

# View cache statistics
terraback cache stats

# Clear all cache
terraback cache clear

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

Cache TTL

Default cache TTL is 60 minutes. Cached data includes:

• Resource lists
• Resource configurations
• API metadata

Provider Configuration

AWS Provider

Generated provider.tf for AWS:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  # region = "us-east-1"  # Uncomment and set your preferred region
}

Azure Provider

Generated provider.tf for Azure:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

GCP Provider

Generated provider.tf for GCP:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 6.0"
    }
  }
}

provider "google" {
  project = "your-project-id"
  region  = "us-central1"
}

Parallel Scanning

Enable parallel scanning for faster results:

# Use 4 parallel workers
terraback scan all aws -r us-east-1 --parallel 4 -o ./output

Recommendations:

• Small accounts (less than 100 resources): 1-2 workers
• Medium accounts (100-1000 resources): 4-8 workers
• Large accounts (more than 1000 resources): 8-16 workers

Note: Higher parallelism increases API request rate. Ensure your account has sufficient API limits.

Dependency Configuration

Enable dependency scanning to discover related resources:

# Scan EC2 instances with all dependencies
terraback aws ec2 scan-instances --with-deps --output-dir ./output

Dependencies are discovered based on:

• Resource references (e.g., VPC ID in subnet)
• Tags and naming conventions
• IAM role associations
• Network configurations

Best Practices

1. Use profiles for multiple accounts: Keep credentials organized with AWS profiles
2. Use consistent output directories: Specify --output-dir for organized output
3. Enable caching for large scans: Add --cache to reduce API calls on repeated scans (off by default)
4. Start with specific services: Test with one service before full account scan
5. Review generated code: Always verify generated Terraform before importing