Quick Start

The fastest path to using cloudemu: spin up the SDK-compat HTTP server, point a real aws-sdk-go-v2 (or Azure / GCP equivalent) client at it, and call your existing production code unchanged.

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

1. Install

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

2. 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"
    awsserver "github.com/stackshy/cloudemu/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()

3. 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.

    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, ~10ms per call.

What just happened

your test code
   │
   ▼
real aws-sdk-go-v2 client  ──HTTP──▶  awsserver.New (httptest)
                                          │
                                          ▼
                            cloudemu in-memory backend

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:

// Azure — TLS required, the SDK rejects bearer tokens over plain HTTP.
import azureserver "github.com/stackshy/cloudemu/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 — REST endpoint via google.golang.org/api or the cloud.google.com/go SDKs.
import gcpserver "github.com/stackshy/cloudemu/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.

Currently SDK-compat-shipped

7 service domains have 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	DynamoDB	Cosmos DB	Firestore
Networking	(in EC2)	VNet	VPC + Firewalls
Monitoring	CloudWatch	Azure Monitor	Cloud Monitoring
Serverless	Lambda	Functions	Cloud Functions
Message Queue	SQS	Service Bus	Pub/Sub

The remaining 9 domains (IAM, DNS, Load Balancer, Notification, Event Bus, Container Registry, Cache, Secrets, Logging) are available today via the Portable Go API; SDK-compat handlers ship in lockstep across all 3 providers as each domain lands.

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

Quick Start

On this page