Quick Start

Stand up the SDK-compat HTTP server, point a real aws-sdk-go-v2 client at it, run production code unchanged.

No mocks. No Docker. No cloud accounts. Just go get and an httptest.NewServer.

Install#

go get github.com/stackshy/cloudemu/v2
go get github.com/aws/aws-sdk-go-v2/service/s3

Stand up cloudemu over HTTP#

package main

import (
    "bytes"
    "context"
    "fmt"
    "net/http/httptest"

    "github.com/aws/aws-sdk-go-v2/aws"
    awsconfig "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"

    "github.com/stackshy/cloudemu/v2"
    awsserver "github.com/stackshy/cloudemu/v2/server/aws"
)

func main() {
    ctx := context.Background()

    // Create the in-memory cloud + the SDK-compat HTTP server in front of it.
    cloud := cloudemu.NewAWS()
    ts := httptest.NewServer(awsserver.New(awsserver.Drivers{
        S3:         cloud.S3,
        DynamoDB:   cloud.DynamoDB,
        EC2:        cloud.EC2,
        VPC:        cloud.VPC,
        Lambda:     cloud.Lambda,
        SQS:        cloud.SQS,
        CloudWatch: cloud.CloudWatch,
    }))
    defer ts.Close()

Use the real `aws-sdk-go-v2` client#

The only thing that changes vs. real AWS is BaseEndpoint. Every other line of your production code stays identical.

main.go

    cfg, _ := awsconfig.LoadDefaultConfig(ctx,
        awsconfig.WithRegion("us-east-1"),
        awsconfig.WithCredentialsProvider(
            credentials.NewStaticCredentialsProvider("test", "test", ""),
        ),
    )

    client := s3.NewFromConfig(cfg, func(o *s3.Options) {
        o.BaseEndpoint = aws.String(ts.URL)
        o.UsePathStyle = true
    })

    // ↓ This is your real production code, unchanged. ↓

    client.CreateBucket(ctx, &s3.CreateBucketInput{
        Bucket: aws.String("app-deployments"),
    })

    client.PutObject(ctx, &s3.PutObjectInput{
        Bucket: aws.String("app-deployments"),
        Key:    aws.String("v1.0/config.yaml"),
        Body:   bytes.NewReader([]byte("db: rds-prod\nport: 8080")),
    })

    out, _ := client.GetObject(ctx, &s3.GetObjectInput{
        Bucket: aws.String("app-deployments"),
        Key:    aws.String("v1.0/config.yaml"),
    })
    defer out.Body.Close()
    fmt.Println("Object retrieved.")
}

go run main.go

Done. Real SDK, in-memory backend, ~10 ms per call.

What just happened#

one request, end to end — ~10ms

The server speaks the actual AWS wire protocol (S3 REST + XML, DynamoDB JSON-RPC, EC2 query, SQS AwsJson1_0, CloudWatch Smithy CBOR, Lambda REST). The SDK can't tell the difference between this and s3.amazonaws.com.

Same pattern, every provider#

The Azure and GCP servers are drop-in replacements. The tabs below stay in sync across the whole site — pick your provider once.

aws_server.go

import awsserver "github.com/stackshy/cloudemu/v2/server/aws"

cloud := cloudemu.NewAWS()
ts := httptest.NewServer(awsserver.New(awsserver.Drivers{
    S3: cloud.S3, DynamoDB: cloud.DynamoDB, EC2: cloud.EC2,
    Lambda: cloud.Lambda, SQS: cloud.SQS, CloudWatch: cloud.CloudWatch,
}))
// s3.NewFromConfig with o.BaseEndpoint = ts.URL → done.

azure_server.go

// TLS required — the SDK rejects bearer tokens over plain HTTP.
import azureserver "github.com/stackshy/cloudemu/v2/server/azure"

cp := cloudemu.NewAzure()
ts := httptest.NewTLSServer(azureserver.New(azureserver.Drivers{
    VirtualMachines: cp.VirtualMachines, BlobStorage: cp.BlobStorage,
    CosmosDB: cp.CosmosDB, Network: cp.VNet, Monitor: cp.Monitor,
    Functions: cp.Functions, ServiceBus: cp.ServiceBus,
}))
// armcompute.NewVirtualMachinesClient with ts.URL → done.

gcp_server.go

// REST endpoint via google.golang.org/api or the cloud.google.com/go SDKs.
import gcpserver "github.com/stackshy/cloudemu/v2/server/gcp"

cp := cloudemu.NewGCP()
ts := httptest.NewServer(gcpserver.New(gcpserver.Drivers{
    Compute: cp.GCE, Storage: cp.GCS, Firestore: cp.Firestore,
    Networking: cp.VPC, Monitoring: cp.CloudMonitoring,
    CloudFunctions: cp.CloudFunctions, PubSub: cp.PubSub,
}))
// option.WithEndpoint(ts.URL) on any cloud.google.com/go client → done.

SDK-compat coverage#

Every domain ships HTTP wire-format handlers across all 3 providers:

Domain	AWS	Azure	GCP
Storage	S3	Blob	GCS
Compute	EC2 + full VPC stack	Virtual Machines + Disks/Snapshots/Images	Compute Engine + Disks/Snapshots/Images
Database (NoSQL)	DynamoDB	Cosmos DB	Firestore
Relational DB	RDS + Redshift	SQL + Postgres/MySQL Flex	Cloud SQL
Networking	(in EC2)	VNet	VPC + Firewalls
Monitoring	CloudWatch	Azure Monitor	Cloud Monitoring
Serverless	Lambda	Functions	Cloud Functions
Kubernetes	EKS	AKS	GKE
Message Queue	SQS	Service Bus	Pub/Sub
Logging	CloudWatch Logs	Log Analytics	Cloud Logging
DNS	Route 53	Azure DNS	Cloud DNS
Load Balancer	ELBv2	Load Balancer	Cloud Load Balancing
Cache	ElastiCache	Azure Cache	Memorystore
Secrets	Secrets Manager	Key Vault	Secret Manager
Notification	SNS	Notification Hubs	FCM
Event Bus	EventBridge	Event Grid	Eventarc
IAM	IAM	IAM	IAM
Container Registry	ECR	ACR	Artifact Registry
Resource Discovery	Resource Explorer + Tagging	Resource Graph	Cloud Asset Inventory

Plus provider-specific Generative AI (Bedrock + SageMaker on AWS, Vertex AI on GCP) and Databricks (Azure). Kubernetes also ships a shared in-memory data plane that client-go / kubectl drive end-to-end.

Everything is equally reachable through the Portable Go API when you'd rather skip HTTP.

Next steps#

SDK-Compatible Server — full coverage tables, protocol detection, registration ordering
Architecture — how SDK-compat wraps the driver layer
Chaos Engineering — inject failures while real SDKs are talking to cloudemu
Portable Go API — the alternative path when you want to skip HTTP entirely

← Installation Configuration →