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

Build a network#

The recommended path points the real SDK at the SDK-compat server. 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:

import (
    "github.com/aws/aws-sdk-go-v2/service/ec2"
    "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)
})

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.

Portable Go API#

Use the Portable API for direct in-process calls without the HTTP hop. CreateVPC returns the VPC whose ID you feed into CreateSubnet — the same parent/child wiring the SDK enforces, minus the request round-trip:

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",
})

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. CanConnect walks peering, security groups, route tables, and ACLs, then returns whether the flow is allowed and, if not, why:

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#

• Parent/child integrity is enforced. Subnets belong to a VPC, rules belong to a security group; the drivers track those relationships so a connectivity query resolves them exactly as the real control plane would.
• Connectivity is evaluated, not simulated. CanConnect reasons over VPC peering, security-group ingress/egress, route tables, and network ACLs — it returns Allowed plus a human-readable Reason (and the SG verdict), so a blocked flow tells you which layer stopped it.
• AWS VPC is served by the EC2 handler. VPC operations share the EC2 SDK-compat endpoint, so one server serves both instances and their networks.
• SDK-compat status — Live. Real ec2, armnetwork, and compute/apiv1 clients drive the emulator. AWS covers VPCs, Subnets, Security Groups + ingress/egress rules, Internet Gateways, Route Tables + Routes, NAT Gateways, VPC Peering Connections, Flow Logs, and Network ACLs; Azure covers virtual networks + subnets CRUD via ARM; GCP covers Networks, Subnetworks, Firewalls, and Routes via REST with LRO envelopes.