Installation

Migrating to v2

As of v2.0.0, the module path is github.com/stackshy/cloudemu/v2 and the public packages are grouped by role. If you are upgrading from v1, see Migrating to v2 below.

Install the Package

Add cloudemu to your Go module:

go get github.com/stackshy/cloudemu/v2

This installs the library and all service packages. There are no external dependencies beyond the Go standard library.

Verify Installation

Create a simple test file to verify everything works:

main_test.go

package main

import (
    "context"
    "testing"

    "github.com/stackshy/cloudemu/v2"
)

func TestCloudemu(t *testing.T) {
    ctx := context.Background()
    aws := cloudemu.NewAWS()

    err := aws.S3.CreateBucket(ctx, "test-bucket")
    if err != nil {
        t.Fatal(err)
    }

    buckets, err := aws.S3.ListBuckets(ctx)
    if err != nil {
        t.Fatal(err)
    }

    if len(buckets) != 1 {
        t.Fatalf("expected 1 bucket, got %d", len(buckets))
    }
}

Run it:

go test -v ./...

If you see PASS, cloudemu is ready to use.

Import Paths

The main package and common sub-packages:

import (
    "github.com/stackshy/cloudemu/v2"                    // NewAWS, NewAzure, NewGCP
    "github.com/stackshy/cloudemu/v2/config"              // WithRegion, WithClock, etc.
    cerrors "github.com/stackshy/cloudemu/v2/errors"      // Error codes and helpers
    "github.com/stackshy/cloudemu/v2/services/compute/driver"      // Compute types
    "github.com/stackshy/cloudemu/v2/services/storage/driver"      // Storage types
    "github.com/stackshy/cloudemu/v2/services/database/driver"     // Database types
    "github.com/stackshy/cloudemu/v2/services/monitoring/driver"   // Monitoring types
)

Each service has its own driver sub-package containing the types and interfaces you need.

v2.0.0 reorganizes the repository by role so it stays legible as it grows. This changes public import paths, so the module is now github.com/stackshy/cloudemu/v2. Behavior is unchanged — the entrypoints (NewAWS, NewAzure, NewGCP), every driver, wire protocol, and error type are identical. Upgrading is a find-and-replace of the import prefix.

1. Update the dependency

go get github.com/stackshy/cloudemu/v2@v2.0.0

2. Rewrite import paths

Add the /v2 suffix and point service packages at their new homes:

// before
import "github.com/stackshy/cloudemu/storage"
// after
import "github.com/stackshy/cloudemu/v2/services/storage"

Where packages moved:

v1 location	v2 location
`<service>` (e.g. `storage`, `compute`, `kubernetes`, `cost`)	`services/<service>`
`chaos`, `recorder`, `metrics`, `ratelimit`, `inject`, `topology`	`features/<name>`
`statemachine`, `pagination`	`internal/<name>`
`providers/{aws,azure,gcp}`, `server/{aws,azure,gcp}`	unchanged (only the `/v2` prefix is added)

A quick way to update a whole codebase: replace the import prefix github.com/stackshy/cloudemu/ with github.com/stackshy/cloudemu/v2/, then move any bare service imports under services/ and the cross-cutting wrappers under features/.

Next Steps

Quick Start — build a complete example
Configuration — customize your providers

Installation

On this page