SDK-Compatible Server

Point a real aws-sdk-go-v2, azure-sdk-for-go, cloud.google.com/go, or oci-go-sdk client at cloudemu and run production code unchanged. The HTTP servers speak each provider's actual wire protocol; the custom endpoint is the only change.

Nothing to mock. No cloud accounts. No bills. The same SDK calls you'd run against real cloud APIs hit a cloudemu server and get back SDK-decodable responses. This page shows the in-process form (httptest.NewServer) for Go tests; to integrate an existing app, run the Standalone Server and override your SDK endpoint.

Why#

cloudemu's Portable API works well for new code you write for testing. But most real apps already use the official cloud SDKs directly. Rewriting those call sites just to test against an emulator is friction. The SDK-compat server removes that friction — change the endpoint, done.

Quick start (AWS)#

package main

import (
    "context"
    "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()

    cloud := cloudemu.NewAWS()
    srv := 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,
    })

    ts := httptest.NewServer(srv)
    defer ts.Close()

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

    // Use the REAL aws-sdk-go-v2 client — only the endpoint changes.
    client := s3.NewFromConfig(cfg, func(o *s3.Options) {
        o.BaseEndpoint = aws.String(ts.URL)
        o.UsePathStyle = true
    })

    client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String("my-bucket")})
    // ... full SDK API works
}

Region and credentials can be any dummy values — the server doesn't validate signatures.

Quick start (Azure)#

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azcore"
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/arm"
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/cloud"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute/v5"

    "github.com/stackshy/cloudemu/v2"
    azureserver "github.com/stackshy/cloudemu/v2/server/azure"
)

cp := cloudemu.NewAzure()
srv := 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,
})

// Azure SDK refuses bearer tokens over plain HTTP — use TLS.
ts := httptest.NewTLSServer(srv)

opts := &arm.ClientOptions{
    ClientOptions: azcore.ClientOptions{
        Cloud: cloud.Configuration{
            Services: map[cloud.ServiceName]cloud.ServiceConfiguration{
                cloud.ResourceManager: {
                    Endpoint: ts.URL,
                    Audience: "https://management.azure.com",
                },
            },
        },
        Transport: ts.Client(),
    },
}

client, _ := armcompute.NewVirtualMachinesClient("sub-1", fakeCred{}, opts)

Quick start (GCP)#

import (
    gcpcompute "cloud.google.com/go/compute/apiv1"
    "github.com/stackshy/cloudemu/v2"
    gcpserver "github.com/stackshy/cloudemu/v2/server/gcp"
    "google.golang.org/api/option"
)

cp := cloudemu.NewGCP()
srv := 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,
})

ts := httptest.NewServer(srv)

opts := []option.ClientOption{
    option.WithEndpoint(ts.URL),
    option.WithoutAuthentication(),
    option.WithHTTPClient(ts.Client()),
}

client, _ := gcpcompute.NewInstancesRESTClient(ctx, opts...)

Quick start (OCI)#

import (
    "github.com/oracle/oci-go-sdk/v65/common"
    "github.com/oracle/oci-go-sdk/v65/objectstorage"
    "github.com/stackshy/cloudemu/v2"
    ociserver "github.com/stackshy/cloudemu/v2/server/oci"
)

ts := httptest.NewServer(ociserver.New(ociserver.DriversFrom(cloudemu.NewOCI())))

// Signatures aren't checked, so any key works.
cp := common.NewRawConfigurationProvider(
    "ocid1.tenancy.oc1..aaaaaaaacloudemulocaltenancy", "ocid1.user.oc1..test",
    "us-ashburn-1", "aa:bb", privateKeyPEM, nil)

client, _ := objectstorage.NewObjectStorageClientWithConfigurationProvider(cp)
client.Host = ts.URL

Every OCI service is on the one server, so each client's Host is the same URL. The tenancy OCID is also the root compartment. Mutations OCI runs asynchronously answer with an opc-work-request-id that the SDK's work request client can poll.

Currently supported#

AWS handlers#

Azure handlers#

All speak ARM JSON over HTTPS unless noted.

GCP handlers#

All speak REST + JSON.

OCI handlers#

All speak OCI's REST + JSON, with opc-request-id on every response and opc-next-page paging.

Vault's KMS crypto operations (encrypt, decrypt, sign and so on) return 501 for now.

Any operation not in these tables returns 501 Not Implemented or the provider's native error code (UnknownOperation, NotImplemented, NOT_FOUND).

Kubernetes data plane (shared across providers)#

EKS, AKS, and GKE each issue kubeconfigs that point at a single shared in-memory Kubernetes API server (kubernetes.NewAPIServer(), passed as K8sAPI to each provider's Drivers). Real client-go / kubectl drive it end-to-end: Namespace, Pod, Service, ConfigMap, Secret, ServiceAccount, Deployment support Create/Get/List/Update/Delete/Patch (JSON-merge) + Watch streaming; Endpoints are read-only. API groups core/v1 and apps/v1. See the Kubernetes service page for what's intentionally out of scope (no scheduler, controllers, RBAC, or PV/PVC).

Multi-region isolation (AWS)#

The AWS wire server routes every request to a per-region backend, keyed by the region in the caller's SigV4 credential scope (Credential=AKID/DATE/REGION/SERVICE/aws4_request). A region's provider is built lazily on its first request and cached from then on; an unsigned request, or one whose scope names the server's default region, routes to the pre-built default backend — so a single-region workload never touches the mux at all.

• Regional state is isolated per region. DynamoDB tables, SQS queues, EC2 instances/VPCs, Lambda functions, and every other regional service each get a fresh, independent backend per region.
• Global services are shared across every region. IAM, STS (one session store, so an ASIA credential minted in one region verifies in another), Route 53, CloudFront, and Global Accelerator all read and write the same underlying state no matter which region's endpoint a request hits — mirroring real AWS, where these services aren't regional. The S3 bucket-name namespace is shared the same way, so bucket names stay globally unique across regions even though each region's S3 backend is otherwise independent.
• Cost and Resource Explorer aggregate across every region that's been touched so far, not just the default one.

The testable behavior: a resource created against a us-east-1-scoped request is invisible to a list call scoped to eu-west-1 — and vice versa — while an IAM user, role, or hosted zone created in either region is visible from both.

How it works#

The server is a tiny core plus a plugin-per-service model. Each service is a self-contained package under server/.

server/
├── server.go                    # core: Handler interface + dispatcher (~80 LOC)
├── wire/
│   ├── wire.go                  # shared XML/JSON helpers
│   ├── awsquery/                # AWS query-protocol decoder + XML envelope
│   ├── azurearm/                # ARM URL parser + JSON helpers + error envelope
│   ├── gcprest/                 # GCP REST URL parser + Operation LRO helpers
│   └── ocirest/                 # OCI REST helpers: opc-request-id, paging, errors
├── aws/
│   ├── aws.go                   # awsserver.New(Drivers{...})
│   ├── s3/  ec2/  dynamodb/  lambda/  sqs/  cloudwatch/  rds/  redshift/
│   ├── eks/  iam/  ecr/  ecs/  ssm/  sts/  bedrock/  sagemaker/
│   ├── bedrockagent/  bedrockagentruntime/  keyspaces/  memorydb/  networkfirewall/
│   ├── route53/  elbv2/  elasticache/  secretsmanager/  cloudwatchlogs/  sns/  eventbridge/
│   └── resourceexplorer2/  resourcegroupstaggingapi/
├── azure/
│   ├── azure.go                 # azureserver.New(Drivers{...})
│   ├── virtualmachines/  disks/  snapshots/  images/  sshpublickeys/
│   ├── blobstorage/  cosmosdb/  cosmosaccount/  vnet/  monitor/  functions/  servicebus/  queue/
│   ├── sql/  postgresflex/  mysqlflex/  cosmospostgresql/  managedcassandra/  aks/  iam/  acr/
│   ├── dns/  loadbalancer/  cache/  keyvault/  loganalytics/  notificationhubs/  eventgrid/
│   ├── ai/  search/  tablestorage/  storageaccount/  subscriptions/  resourcegroups/
│   ├── databricks/              # ARM + workspace data plane (dbfs, repos, uc, …)
│   └── resourcegraph/
└── gcp/
    ├── gcp.go                   # gcpserver.New(Drivers{...})
    ├── compute/  vpc/  gcs/  firestore/  monitoring/  lro/  servicenetworking/
    ├── cloudfunctions/  pubsub/  cloudsql/  gke/  iam/  alloydb/  bigtable/
    ├── clouddns/  loadbalancer/  memorystore/  secretmanager/  cloudlogging/  fcm/  eventarc/
    └── artifactregistry/  vertexai/  cloudasset/
└── oci/
    ├── oci.go                   # ociserver.New(ociserver.DriversFrom(cloudemu.NewOCI()))
    ├── identity/  vcn/  compute/  objectstorage/  nosql/  vault/
    └── logging/  monitoring/  notifications/  workrequest/

Each handler implements a two-method interface:

type Handler interface {
    Matches(r *http.Request) bool                    // detect by header/path/form
    ServeHTTP(w http.ResponseWriter, r *http.Request)
}

server.Server iterates registered handlers and dispatches to the first that claims the request. Adding a new service is one new package + one Register call. The core never changes.

Protocol detection#

Each handler uses a different signal so dispatch is unambiguous within a provider:

The newer handlers follow the same per-provider scheme: AWS RDS/Redshift use the query protocol (Action=…), Bedrock/SageMaker/Resource Explorer dispatch on X-Amz-Target or their REST path prefix; Azure SQL/Postgres/MySQL/AKS/ACR/Resource Graph match their Microsoft.<Provider>/<Type> ARM path, and Databricks data-plane calls match the /api/2.x/ prefix; GCP Cloud SQL, GKE, Vertex AI, and Cloud Asset match their REST path prefixes.

Registration order matters when handlers share a path prefix — the provider factories register more-specific handlers ahead of catch-alls (S3, Blob, GCS, Firestore) so first-match-wins resolves correctly.

Coverage status#

Every core service domain now ships an SDK-compat handler across AWS, Azure, and GCP — including DNS, Load Balancer, Cache, Secrets, Logging, Notification, and Event Bus, which were the last cross-cloud domains to land. OCI covers a smaller set; a service it doesn't emulate yet (Functions, Queue, Load Balancer, DNS, Container Registry, Cache, Events, MySQL/PostgreSQL, OKE) has no handler. New services continue to drop in as self-contained handler packages without touching the core.

Writing your own handler#

If you need a service we don't cover yet, implement the server.Handler interface in your own package and register it:

type MyHandler struct{ /* driver */ }

func (*MyHandler) Matches(r *http.Request) bool {
    // your detection logic
}

func (h *MyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // your logic
}

srv := server.New()
srv.Register(&MyHandler{...})

The Handler interface is the only contract — no registration is needed in core cloudemu. If the handler is generally useful, a PR to add it under server/<provider>/<service> is welcome.

Limitations#

• Signature validation is off by default. With no flags, requests are accepted regardless of AWS SigV4 / Azure AAD / GCP OAuth signatures, so local development just works. Opt in with --enforce-auth — see Auth Enforcement for exactly what's verified per provider and its non-guarantees.
• No AMQP for Azure Service Bus. The modern azservicebus SDK uses AMQP exclusively for data plane. ARM control plane is fully supported via armservicebus; tests that need send/receive can use the raw-HTTP REST data plane.
• GCS direct-media downloads assume path-style URLs.
• DynamoDB / Cosmos / Firestore filters and queries support common patterns but are not full DSL parsers.
• Pagination tokens are honored where present in the SDK contract; some list operations short-circuit to a single page.

When a client hits an unsupported operation, the server responds with the provider's native error code so failures are easy to diagnose.