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
IAM	IAM	IAM	IAM
Container Registry	ECR	ACR	Artifact Registry
Resource Discovery	Resource Explorer + Tagging	Resource Graph	Cloud Asset Inventory

Plus DNS, Load Balancer, Notification, Event Bus, Cache, Secrets, and Logging (SDK-compat since v1.9.0), 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 →