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 in tests 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#

The recommended path points the real SDK at the SDK-compat server, so the same client code you ship in production talks to the emulator. 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"
    "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,
}))

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

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.

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.