☁️ Fakecloud AWS Sandbox: API Gateway + Lambda Terraform POC

A production-ready Proof-of-Concept (PoC) demonstrating how to use Fakecloud as a fast, free, local AWS emulator sandbox to test terraform plan and terraform apply before promoting infrastructure changes to your real AWS environment.

This project provisions an AWS REST API Gateway integrated with a Python AWS Lambda function via AWS_PROXY, and includes automated integration testing using the official first-party Fakecloud Python SDK (fakecloud) and pytest.

---

🏗️ Architecture Overview

graph LR
    subgraph Local Environment
        User[Developer / CI Pipeline] -->|terraform apply| TF[Terraform AWS Provider]
        TF -->|http://localhost:4566| FC[Fakecloud AWS Emulator]
        
        FC -->|Provisions| APIGW[REST API Gateway\n/hello]
        FC -->|Deploys Container| Lambda[AWS Lambda Container\nPython 3.11]
        FC -->|Configures| IAM[IAM Roles & Policies]
        
        User -->|HTTP GET/POST| APIGW
        APIGW -->|AWS_PROXY Integration| Lambda
        Lambda -->|HTTP 200 JSON Response| User
        
        Pytest[Fakecloud Test SDK / pytest] -.->|Introspects Invocations| FC
    end

Loading

---

🌟 Why Fakecloud?

• 100% Free & Open-Source: Free forever with no accounts, no auth tokens, and no commercial paywalls.
• Deep Conformance: Conformance validated directly against AWS Smithy API models.
• Real Container Execution: Executes Lambda functions inside real isolated AWS Lambda runtime containers (public.ecr.aws/lambda/python:3.11).
• First-Party Test SDK: Deep introspection of emulator internals (Lambda invocation payloads, warm container pools, health metrics) without flaky log parsing.

---

📋 Prerequisites

• Docker (or Docker Desktop / WSL2 on Windows)
• Terraform (>= 1.0.0)
• Python (>= 3.9) with pip
• Git

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/emocado/fakecloud-apigw.git
cd fakecloud-apigw

2. Start the Fakecloud Sandbox

Start Fakecloud in Docker with host-gateway networking:

docker-compose up -d

Or on Windows PowerShell:

.\start-fakecloud.ps1

Verify Fakecloud is running:

curl http://localhost:4566/_fakecloud/health

3. Initialize & Deploy with Terraform

# Initialize providers
terraform init

# Review execution plan
terraform plan

# Apply infrastructure to Fakecloud sandbox
terraform apply -auto-approve

---

🧪 Testing the Integration

Option A: Automated First-Party SDK Test Suite (Recommended)

Install test dependencies:

pip install fakecloud pytest requests boto3

Run the pytest suite:

pytest

Or with PowerShell helper:

.\run-tests.ps1

What the SDK tests verify:

1. ✅ test_fakecloud_health: Verifies emulator status and active service registrations (apigateway, lambda, iam).
2. ✅ test_apigateway_get_request: Sends HTTP GET via API Gateway and asserts exact payload captured inside Fakecloud with fc.lambda_.get_invocations().
3. ✅ test_apigateway_post_request: Sends HTTP POST with JSON body and asserts proxy payload forwarding.
4. ✅ test_boto3_direct_lambda_invocation: Verifies direct Lambda execution using the standard AWS Boto3 SDK against Fakecloud.
5. ✅ test_fakecloud_warm_containers: Introspects the warm container pool using fc.lambda_.get_warm_containers().

---

Option B: Manual Testing with cURL / PowerShell

# Run the PowerShell test script
.\test-endpoint.ps1

Or test with curl:

# Get the API ID from Terraform outputs
API_ID=$(terraform output -raw api_id)

# Test GET Request
curl -i -H "Host: ${API_ID}.execute-api.us-east-1.amazonaws.com" \
  "http://localhost:4566/dev/hello?name=Developer"

# Test POST Request
curl -i -X POST -H "Host: ${API_ID}.execute-api.us-east-1.amazonaws.com" \
  -H "Content-Type: application/json" \
  -d '{"message":"testing from curl"}' \
  "http://localhost:4566/dev/hello"

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{
  "status": "success",
  "message": "Hello from Lambda running in Fakecloud sandbox!",
  "timestamp": "2026-08-30T15:09:20.079123Z",
  "environment": "dev",
  "request": {
    "httpMethod": "GET",
    "path": "/dev/hello",
    "queryStringParameters": {
      "name": "Developer"
    },
    "body": {}
  }
}

---

🔄 Switching Between Fakecloud and Real AWS

The Terraform configuration in provider.tf is fully dynamic:

In terraform.tfvars:

# For Local Sandbox (Fakecloud)
use_fakecloud      = true
fakecloud_endpoint = "http://localhost:4566"

# For Real AWS Deployment
# use_fakecloud    = false

When use_fakecloud = false, Terraform automatically disables local endpoint overrides, skips mock credentials, and deploys directly to your real AWS account using standard AWS credentials (~/.aws/credentials or AWS environment variables).

---

📁 Repository Structure

├── apigateway.tf          # REST API Gateway resources, methods, and integrations
├── docker-compose.yml     # Docker Compose config for Fakecloud
├── iam.tf                 # IAM Lambda execution role & policy attachment
├── lambda.tf              # Lambda packaging & deployment definition
├── outputs.tf             # Output values (API ID, stage, invoke URLs, host headers)
├── provider.tf            # Dynamic AWS provider with conditional local endpoints
├── pytest.ini             # Pytest configuration
├── README.md              # Project documentation
├── run-tests.ps1          # Test runner script
├── start-fakecloud.ps1    # Startup helper script
├── variables.tf           # Input variable declarations
├── versions.tf            # Terraform and provider version constraints
├── src/
│   └── lambda/
│       └── index.py       # Python Lambda proxy handler
└── tests/
    └── test_apigw_lambda.py # SDK integration test suite

---

📄 License

This project is licensed under the MIT License.