Getting Started Guide

Quick Start

Get Terraback running in under 5 minutes with this quick start guide.

Prerequisites

Before you begin, ensure you have:

1. Python 3.8+ installed
2. Cloud credentials configured:
   • AWS: ~/.aws/credentials or environment variables
   • Azure: az login or service principal
   • GCP: gcloud auth application-default login
3. Terraform (optional, for validation and import)

Verify Installation

# Check cloud authentication
terraback scan auth-check

Your First Scan

Step 1: Scan AWS Resources

Let's scan your AWS infrastructure and generate Terraform code.

# Scan all resources in a region
terraback scan all aws -r us-east-1 -o ./generated

# Or scan specific services
terraback aws s3 scan --output-dir ./generated
terraback aws ec2 scan-instances --output-dir ./generated
terraback aws vpc scan --output-dir ./generated

Step 2: Review Generated Files

# List generated files
ls -la ./generated/

# You'll see:
# provider.tf      - AWS provider configuration
# vpc.tf           - VPC resources
# subnets.tf       - Subnet resources
# security_groups.tf - Security group resources
# s3_bucket.tf     - S3 bucket resources
# import/          - Import command files

Step 3: Initialize Terraform

cd ./generated
terraform init

Step 4: Import Existing Resources

Terraback already knows every resource's Terraform address and cloud ID from the scan (stored in the import/ directory). Instead of running terraform import once per resource, use Terraback's own import command to bring everything into state in one operation:

# Import everything Terraback discovered (uses Terraform 1.5+ import blocks when available)
terraback aws import -o ./generated

See the Import Guide for the full workflow and method comparison.

Step 5: Verify with Terraform Plan

# Should show no changes if import was successful
terraform plan

Scanning with Dependencies

Use the --with-deps flag to automatically discover related resources:

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

# This automatically discovers:
# - VPCs and subnets
# - Security groups
# - IAM roles and instance profiles
# - EBS volumes
# - Key pairs

Enterprise Module Generation

For larger environments, use enterprise modules to organize output:

# Generate organized module structure
terraback scan all aws -r us-east-1 --enterprise-modules -o ./enterprise

# This creates:
# enterprise/
# ├── main.tf              # Module instantiation
# ├── variables.tf         # Root variables
# ├── outputs.tf           # Root outputs
# ├── provider.tf          # Provider config
# ├── imports.tf           # Import blocks
# ├── config/              # Environment configs (auto-detected from resource tags)
# │   ├── default.tfvars
# │   ├── dev.tfvars
# │   └── production.tfvars
# └── modules/             # Organized modules
#     ├── vpc/
#     ├── ec2-instance/
#     ├── s3-bucket/
#     ├── lambda-function/
#     └── ...

Multi-Cloud Scanning

Azure

# Authenticate
az login

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

# Or scan specific services
terraback azure compute vm scan -g my-resource-group
terraback azure network vnet scan -g my-resource-group

GCP

# Authenticate
gcloud auth application-default login

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

# Or scan specific services
terraback gcp compute scan-all --project-id my-project
terraback gcp storage scan-all --project-id my-project

Common Options

These options are available on terraback scan all. Service-specific commands use the long-form flags (--region, --output-dir, --profile).

Option	Description
-o, --output-dir	Directory for generated files (default: ./generated)
-r, --region	AWS region or GCP region
-p, --profile	AWS profile name
-g, --resource-group	Azure resource group
--project-id	GCP project ID
--with-deps	Scan dependencies automatically
--enterprise-modules	Generate organized module structure
--parallel N	Number of parallel workers (1-32)
--cache / --no-cache	Cache API responses for faster re-scans (off by default)
--cache-encrypt	Encrypt cache files at rest (requires --cache)
--all-regions	Scan all enabled regions/locations in parallel
--resume	Resume an interrupted scan
--preview	Run terraform plan preview after scan

Note: Azure-specific commands use --location (or -l) instead of --region.

Next Steps

• CLI Reference: Complete command documentation
• Import Guide: Fast bulk import into Terraform state
• Speed and Performance: Scan and import large accounts fast
• Configuration: Advanced configuration options
• Best Practices: Production usage tips

Troubleshooting

Authentication Errors

# AWS: Check credentials
aws sts get-caller-identity

# Azure: Re-authenticate
az login

# GCP: Re-authenticate
gcloud auth application-default login

No Resources Found

• Verify you're scanning the correct region/resource group
• Check your credentials have read permissions
• Try scanning a specific service first

Permission Errors

Terraback requires read-only access to cloud APIs. Ensure your credentials include:

• AWS: ReadOnlyAccess policy or equivalent
• Azure: Reader role on the subscription/resource group
• GCP: Viewer role on the project