Compute

Emulates managed virtual machines — the EC2 instance, Azure VM, or Compute Engine instance you'd launch to run a workload. You run instances from an image, then start, stop, reboot, and terminate them; the full VPC networking stack (subnets, security groups, gateways, volumes) is available alongside so instances have somewhere to live.

Reach for it when your code provisions capacity, waits on instance state, or reacts to lifecycle events — so you can exercise those paths without paying for real VMs or waiting on real boot times. Under the hood each instance is a state machine that walks the same pending → running → stopped → terminated transitions the real services enforce.

Run and manage instances#

Run cloudemu as a server and point the same client code you ship in production at it — only the endpoint changes. Start it with cloudemu serve (or docker run --rm -p 4566:4566 ghcr.io/stackshy/cloudemu), which serves the AWS API on http://localhost:4566:

cloudemu serve   # AWS API on http://localhost:4566

Then point the stock EC2 client at that endpoint. RunInstances launches capacity from an AMI; StopInstances moves them out of running without terminating, mirroring how EC2 lets you pause billing while keeping the instance:

import (
    "github.com/aws/aws-sdk-go-v2/service/ec2"
    "github.com/aws/aws-sdk-go-v2/service/ec2/types"
)

client := ec2.NewFromConfig(cfg, func(o *ec2.Options) {
    o.BaseEndpoint = aws.String("http://localhost:4566")
})

out, _ := client.RunInstances(ctx, &ec2.RunInstancesInput{
    ImageId:      aws.String("ami-0abcdef1234"),
    InstanceType: types.InstanceTypeT3Large,
    MinCount:     aws.Int32(1),
    MaxCount:     aws.Int32(3),
})

client.StopInstances(ctx, &ec2.StopInstancesInput{
    InstanceIds: []string{*out.Instances[0].InstanceId},
})

The same pattern works with armcompute for Azure and cloud.google.com/go/compute/apiv1 for GCP — only the endpoint changes. See the SDK-Compat Server.

In-process (Go unit tests)#

For Go unit tests written inside cloudemu-aware code, stand the same wire server up in-process with httptest.NewServer and point the client at ts.URL. The Drivers you pass name exactly the drivers this service needs:

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

cloud := cloudemu.NewAWS()
ts := httptest.NewServer(awsserver.New(awsserver.Drivers{
    EC2: cloud.EC2, VPC: cloud.VPC,
}))
defer ts.Close()
// point the same ec2 client at ts.URL instead of the running endpoint

Portable Go API#

Use the Portable API when you want direct in-process calls without the HTTP hop — handy for setting up fixtures fast. RunInstances takes a count as its last argument and returns the created instances; stop and terminate take instance IDs:

import computedriver "github.com/stackshy/cloudemu/v2/services/compute/driver"

instances, _ := aws.EC2.RunInstances(ctx, computedriver.InstanceConfig{
    ImageID: "ami-0abcdef1234", InstanceType: "t3.large",
}, 3)
aws.EC2.StopInstances(ctx, []string{instances[0].ID})
aws.EC2.TerminateInstances(ctx, []string{instances[0].ID})

Behavior & fidelity#

SDK-compat — Live#

Real ec2, armcompute, and compute/apiv1 clients drive the emulator end-to-end:

See SDK-Compat for the full per-operation list.