Docs / Export

Export

Preview

Build infrastructure locally, export it to deployable Terraform or CloudFormation, and run terraform plan against real AWS to validate. apply works for the 74 services and 513 resource types in the coverage matrix; expect to edit the output for naming, tags, and account-specific constraints before production.

Preview feature. The pipeline and the 513-resource coverage suite are real, but the intermediate representation is not frozen and known lossy mappings exist (Lambda code staging, IAM inline-vs-attached normalization, secret redaction). Expect refactoring of the emitted HCL shape post-1.0 without a semver-major bump.

What Export does

Export takes the resources currently running on a LocalEmu instance, runs them through per-service collectors that produce an intermediate representation, and emits a portable artifact in one of three formats:

• Terraform HCL, deployable against real AWS via terraform apply.
• CloudFormation JSON/YAML, deployable via aws cloudformation deploy.
• Generic JSON snapshot, re-applied with localemu import to replay state into another LocalEmu instance.

Coverage

AWS services with Terraform fixtures in the coverage suite.

513

Distinct (service, resource_type) pairs the exporter can emit.

Services covered: ACM, Amplify, API Gateway (v1+v2), AppConfig, App Mesh, App Runner, AppSync, Backup, Batch, CloudFormation, CloudFront, CloudTrail, CloudWatch, CodeArtifact, CodeBuild, CodeCommit, CodeDeploy, CodePipeline, Cognito, Config, DataSync, Detective, DMS, DynamoDB, EC2, ECR, ECS, EKS, ElastiCache, ELBv2, EMR, EventBridge, Firehose, FSx, Global Accelerator, Glue, GuardDuty, IAM, Inspector2, IoT, MSK (Kafka), Kinesis, KMS, Lake Formation, Lambda, CloudWatch Logs, Macie2, MQ, Neptune, OpenSearch, Organizations, Pipes, RDS, Redshift, Resource Groups, Route53, Route53 Resolver, S3, S3 Control, SageMaker, Scheduler, Secrets Manager, Service Catalog, SES, Shield, SNS, SQS, SSM, Step Functions, SWF, Transcribe, WAFv2.

Source: tests/unit/export/realaws/test_service_coverage.py enforces these 513 pairs by synthesising a sample IR resource for each and asserting terraform validate succeeds.

CLI

Two top-level commands: localemu export (also aliased as awsemu export) and localemu import. Snapshot everything, or narrow with --service:

Terminal

# Snapshot everything as Terraform
$ localemu export --format terraform \
    --aws-account-id 123456789012 \
    --output ./my-infra

# Or just a subset of services (JSON snapshot only)
$ localemu export --format json \
    --services lambda,sqs,sns \
    --output ./my-infra

# Verify post-export with `terraform plan` against real AWS
$ localemu export --format terraform \
    --aws-account-id 123456789012 \
    --verify plan \
    --output ./my-infra

# CloudFormation output
$ localemu export --format cloudformation \
    --aws-account-id 123456789012 \
    --output ./my-stack

# Replay a JSON snapshot back into LocalEmu (or another endpoint)
$ localemu import --input ./my-infra/snapshot.json

Options reference

Flag	Description
--format {terraform,cloudformation,json}	Output format. Required. `terraform` and `cloudformation` produce real-AWS deployable output; `json` produces the legacy raw snapshot.
-o, --output PATH	Output directory. Defaults to `./localemu-export-<timestamp>/`.
--aws-account-id ID	Target AWS account id. Required for `terraform` / `cloudformation`.
--aws-region REGION	Target AWS region. Defaults to `us-east-1`.
--aws-profile NAME	Named AWS profile for preflight + verification.
--aws-access-key-id / --aws-secret-access-key	Static credentials (must be supplied together).
--aws-session-token TOKEN	Optional STS session token.
--verify {plan,apply,skip}	Post-export verification. Defaults to `plan`. `apply` requires a sandbox account.
--localemu-endpoint URL	Endpoint to read state from. Defaults to `http://localhost:4566`.
--services LIST	JSON-format only. Comma-separated services to include.
--regions LIST	JSON-format only. Comma-separated regions.
--include-secrets	JSON-format only. Include sensitive attributes. Use with care.
--include-data	JSON-format only. Include bulk payloads.
--dry-run	JSON-format only. Collect and render but do not write the output file.

Output fidelity

Export emits structurally-correct, terraform validate-clean HCL. It is not byte-identical to what a human Terraform author would write: naming is auto-derived from the LocalEmu resource's Id/ARN, and attribute ordering follows the exporter's template. Where real AWS requires a property LocalEmu does not model, the exporter either omits the property (Terraform applies the default) or raises a named warning.

Known lossy mappings

• Lambda code is staged into a side-directory; the exported Terraform references an archive path, not an inlined blob. The output Terraform depends on the filesystem layout you exported to.
• IAM inline vs attached policies normalization is not guaranteed round-trip identical.
• Secrets and sensitive values are redacted, not exported verbatim. Use --include-secrets on the JSON path only, and only when you know what you are doing.

Round-trip: LocalEmu → Terraform → real AWS

The pipeline is built for it. The orchestrator does pre-flight credential checks before any AWS-side calls, and the default --verify plan smoke-tests the export by running terraform plan against your real AWS account. An opt-in end-to-end suite under tests/integration/export_realaws/ (gated by LOCALEMU_EXPORT_E2E_AWS=1) exercises the full apply path against AWS.

A workflow built around Export's actual behaviour:

Stand resources up on LocalEmu (CLI, Terraform-against-LocalEmu, or boto3).
localemu export --format terraform --aws-account-id ... --verify plan
Read the diff. Adjust the output for tags, naming, account-specific constraints.
Commit the cleaned-up Terraform to your IaC repo, then terraform apply from CI as usual.

← IAM Enforcement API Coverage →