Networking

Emulates cloud virtual networks — the VPC, VNet, subnets, and security groups you wire up so instances can (or can't) talk to each other. You build the topology with the real SDKs, then the drivers hold the same relationships real clouds track: which subnet sits in which VPC, which rules a security group carries, which peerings are active.

Reach for it when your code provisions network scaffolding, or when you want to assert reachability — "can this instance reach that one on 443?" — without deploying anything. The topology engine answers those questions by walking the same drivers, the way real cloud reachability analyzers do.

Drive it with the real SDK#

Run cloudemu as a server and point the real SDK at it. 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. A VPC gives you an address space; subnets carve it up; a security group is the rule set you attach to instances — build them in that order because each references the last. AWS VPC is served by the EC2 handler, so one server serves both instances and their networks:

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

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

vpc, _ := client.CreateVpc(ctx, &ec2.CreateVpcInput{CidrBlock: aws.String("10.0.0.0/16")})
client.CreateSubnet(ctx, &ec2.CreateSubnetInput{
    VpcId: vpc.Vpc.VpcId, CidrBlock: aws.String("10.0.1.0/24"),
})
client.CreateSecurityGroup(ctx, &ec2.CreateSecurityGroupInput{
    VpcId: vpc.Vpc.VpcId, GroupName: aws.String("web-sg"),
    Description: aws.String("Web traffic"),
})

Azure (armnetwork.NewVirtualNetworksClient) and GCP (gcpcompute.NewNetworksRESTClient) follow the same endpoint-only-changes pattern — 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

Call the driver directly#

Skip the HTTP hop for cloudemu-only setup code. CreateVPC returns the VPC whose ID you feed into CreateSubnet — the same parent/child wiring the SDK enforces:

import netdriver "github.com/stackshy/cloudemu/v2/services/networking/driver"

vpc, _ := aws.VPC.CreateVPC(ctx, netdriver.VPCConfig{CIDRBlock: "10.0.0.0/16"})
subnet, _ := aws.VPC.CreateSubnet(ctx, netdriver.SubnetConfig{
    VPCID: vpc.ID, CIDRBlock: "10.0.1.0/24",
})

The core driver covers all three clouds — VPCs, subnets, security groups, peering, NAT gateways, flow logs, route tables, network ACLs, and internet gateways — plus elastic IPs, VPC endpoints, VPC attributes, route-table associations, and network interfaces. Two behaviors are worth calling out:

• Main route table. Every VPC is born with one; a subnet with no explicit association is governed by it, and DescribeRouteTables is the only way to discover an association ID.
• ENI drain. An attached network interface can't be deleted — a NAT gateway holds one for its whole life, so a caller draining a VPC learns from the failure that the drain isn't finished.

AWS-specific networking#

AWS models several networking resources that don't map cleanly across clouds. These are AWS-only optional capability interfaces — discovered by type assertion on aws.VPC, implemented by the AWS VPC provider, and served by the EC2 handler (no Azure/GCP stubs).

IPAM's cross-account and live-network features are modeled against the emulator's own single-account state. It also publishes derived CloudWatch metrics under the AWS/IPAM namespace — pool and scope utilization, public-IP insights, and per-resource IP usage, all computed live from IPAM plus VPC/subnet/EIP state.

Query connectivity#

Once the network is built, the topology engine answers "can A reach B?" over the same drivers — so you can assert that a security-group change actually opens (or blocks) a path without launching traffic:

import "github.com/stackshy/cloudemu/v2/features/topology"

topo := topology.New(cloud.EC2, cloud.VPC, cloud.Route53)
result, _ := topo.CanConnect(ctx, topology.ConnectivityQuery{
    SrcInstanceID: "i-00000001", DstInstanceID: "i-00000002",
    Port: 443, Protocol: "tcp",
})
fmt.Println(result.Allowed, result.Reason)

Behavior & fidelity#

SDK-compat — Live#

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

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