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#

• State machine enforces valid transitions. Instances walk pending → running → stopped → terminated; illegal transitions return errors, so a test that stops a terminated instance fails the same way real EC2 would.
• Lifecycle metrics are emitted automatically. RunInstances pushes CPU, Network, and Disk metrics to the monitoring service, and every Start/Stop/Reboot/Terminate writes matching values — so you can assert on metric-driven alarms end-to-end.
• Full VPC stack alongside compute. Subnets, Security Groups, Internet/NAT Gateways, Route Tables, Peering, Flow Logs, ACLs, EBS Volumes, Key Pairs, Snapshots, AMIs, Spot Instances, Launch Templates, and Auto Scaling Groups are all available on aws.EC2 / aws.VPC — see Networking.
• SDK-compat status — Live. Real ec2, armcompute, and compute/apiv1 clients drive the emulator. EC2 covers RunInstances, DescribeInstances (filters: instance-id, instance-type, instance-state-name, tag:*), Start/Stop/Reboot/Terminate, and ModifyInstanceAttribute; Azure covers VM CreateOrUpdate/Get/List/Delete plus start/powerOff/restart and full Disks/Snapshots/Images/SSHPublicKeys CRUD; GCP covers Instances/Disks/Snapshots/Images insert/get/list/delete with LRO envelopes.