chi.network
The chi.network
module exposes a functional interface for interacting
with the various networking capabilities of the testbed.
- chi.network.add_port_to_router_by_name(router_name, port_name)[source]
Add a port to a router, referencing the router and port by name.
- chi.network.add_subnet_to_router_by_name(router_name, subnet_name)[source]
Add a subnet to a router, referencing the router and subnet by name.
- chi.network.bind_floating_ip(ip_address, port_id=None, fixed_ip_address=None)[source]
Directly assign a Floating IP to an existing port/address.
Note
If you just want to attach a Floating IP to a server instance, the
chi.server.associate_floating_ip()
function is simpler.
- chi.network.create_network(network_name, of_controller_ip=None, of_controller_port=None, vswitch_name=None, provider='physnet1', port_security_enabled=True) dict [source]
Create a network.
For an OpenFlow network include the IP and port of an OpenFlow controller on Chameleon or accessible through the public Internet. Include a virtual switch name if you plan to add additional private VLANs to this switch. Additional VLANs can be connected using a dedicated port corresponding to the VLAN tag and can be conrolled using a valid OpenFlow controller.
- Parameters:
network_name (str) – The new network name.
of_controller_ip (str) – the IP of the optional OpenFlow controller. The IP must be accessible on the public Internet.
of_controller_port (str) – the port of the optional OpenFlow controller.
vswitch_name (str) – The virtual switch to use name.
provider (str) – the provider network to use when specifying stitchable VLANs (i.e. ExoGENI). Default: ‘physnet1’
- chi.network.create_port(port_name, network_id, fixed_ips=None, subnet_id=None, ip_address=None, port_security_enabled=True) dict [source]
Create a new port on a network.
This function has a short-form and a long-form invocation. In the short form, you can specify
subnet_id
andip_address
to give the port a single assignment on a subnet. In the long form you can specifyfixed_ips
to define multiple assignments.- Parameters:
port_name (str) – The name to give the new port.
network_id (str) – The ID of the network that the port will be connected to.
fixed_ips (list[dict]) – A list of IP assignments to give to the port on various subnets. Each assignment must at minimum have a
subnet_id
defined. An optionalip_address
can be included on an assignment to specify the exact IP address to assign. Otherwise, one is chosen automatically from the available IPs on the subnet. There can be multiple assignments (i.e., IPs) on a single subnet.subnet_id (str) –
The ID of the subnet that the port will be allocated on. The port will be automatically assigned an IP address on this subnet, unless the
ip_address
parameter is provided.Note
This parameter is ignored if
fixed_ips
is set.ip_address (str) –
The IP address to assign the port, if a specific IP address is desired. By default an IP address is automatically picked from the target subnet.
Note
This parameter is ignored if
fixed_ips
is set.port_security_enabled (bool) – Whether to enable port security. In general this should be kept on. (Default True).
- Returns:
The created port representation.
- chi.network.create_router(router_name, gw_network_name=None) dict [source]
Create a router, with or without a public gateway.
- chi.network.create_subnet(subnet_name, network_id, cidr='192.168.1.0/24', allocation_pool_start=None, allocation_pool_end=None, gateway_ip=None) dict [source]
Create a subnet on a network.
- Parameters:
subnet_name (str) – The name to give the new subnet.
network_id (str) – The network to associate the subnet with ID.
cidr (str) – The subnet’s IPv4 CIDR range. (Default 192.168.1.0/24)
gateway_ip (str) – The subnet’s gateway address. If not defined, the first address in the subnet will be automatically chosen as the gateway.
- Returns:
The new subnet representation.
- chi.network.delete_network(network_id)[source]
Delete the network.
Note
This does not perform a full teardown of the network, including removing subnets and ports. It will only succeed if the network does not have any attached entities. See
nuke_network()
for a more complete teardown function.- Parameters:
network_id (str) – The network ID.
- chi.network.delete_router(router_id)[source]
Delete the router.
- Parameters:
router_id (str) – The router ID.
- chi.network.delete_subnet(subnet_id)[source]
Delete the subnet.
- Parameters:
subnet_id (str) – The subnet ID.
- chi.network.get_floating_ip(ip_address) dict [source]
Get the floating IP representation for an IP address.
- Parameters:
ip_address (str) – The IP address of the floating IP.
- Returns:
The floating IP representation.
- chi.network.get_free_floating_ip(allocate=True) dict [source]
Get the first unallocated floating IP available to your project.
- Parameters:
allocate (bool) – Whether to allocate a new floating IP if there are no Floating IPs currently free in your project. Defaults to True.
- Returns:
The free floating IP representation.
- chi.network.get_network(ref) dict [source]
Get a network by its name or ID.
- Parameters:
ref (str) – The name or ID of the network.
- Returns:
The network representation.
- Raises:
RuntimeError – If the network could not be found, or multiple networks were returned for the search term.
- chi.network.get_network_id(name) str [source]
Look up a network’s ID from its name.
- Parameters:
name (str) – The network name.
- Returns:
The network’s ID, if found.
- Raises:
RuntimeError – If the network could not be found, or multiple networks were returned for the search term.
- chi.network.get_port(ref) dict [source]
Get a port by its name or ID.
- Parameters:
ref (str) – The name or ID of the port.
- Returns:
The port representation.
- Raises:
RuntimeError – If the port could not be found, or multiple ports were returned for the search term.
- chi.network.get_port_id(name) str [source]
Look up a port’s ID from its name.
- Parameters:
name (str) – The port name.
- Returns:
The port’s ID, if found.
- Raises:
RuntimeError – If the port could not be found, or multiple ports were returned for the search term.
- chi.network.get_router(ref) dict [source]
Get a router by its name or ID.
- Parameters:
ref (str) – The name or ID of the router.
- Returns:
The router representation.
- Raises:
RuntimeError – If the router could not be found, or multiple routers were returned for the search term.
- chi.network.get_router_id(name) str [source]
Look up a router’s ID from its name.
- Parameters:
name (str) – The router name.
- Returns:
The router’s ID, if found.
- Raises:
RuntimeError – If the router could not be found, or multiple routers were returned for the search term.
- chi.network.get_subnet(ref) dict [source]
Get a subnet by its name or ID.
- Parameters:
ref (str) – The name or ID of the subnet.
- Returns:
The subnet representation.
- Raises:
RuntimeError – If the subnet could not be found, or multiple subnets were returned for the search term.
- chi.network.get_subnet_id(name) str [source]
Look up a subnet’s ID from its name.
- Parameters:
name (str) – The subnet name.
- Returns:
The subnet’s ID, if found.
- Raises:
RuntimeError – If the subnet could not be found, or multiple subnets were returned for the search term.
- chi.network.list_floating_ips() list[dict] [source]
List all floating ips associated with the current project.
- Returns:
A list of all the found floating ips.
- chi.network.list_networks() list[dict] [source]
List all networks associated with the current project.
- Returns:
A list of all the found networks.
- chi.network.list_ports() list[dict] [source]
List all ports associated with the current project.
- Returns:
A list of all the found ports.
- chi.network.list_routers() list[dict] [source]
List all routers associated with the current project.
- Returns:
A list of all the found routers.
- chi.network.list_subnets() list[dict] [source]
List all subnets associated with the current project.
- Returns:
A list of all the found subnets.
- chi.network.nuke_network(network_ref: str)[source]
Completely tear down the network.
Cleanly tearing down an OpenStack network representation involves a few separate steps:
Detach the network’s subnets from the router.
Delete the router.
Delete the subnet(s).
Delete the network.
This function performs all of those steps for you.
Note
This function will not work well for very advance networks, perhaps those connected to multiple routers. You should perform your own cleanup if your network’s subnets are attached to multiple routers.
- Parameters:
network_ref (str) – The network name or ID.
- chi.network.remove_all_routes_from_router(router_id)[source]
Remove all routes from the router.
- Parameters:
router_id (str) – The router ID.
- chi.network.remove_route_from_router(router_id, cidr, nexthop)[source]
Remove a single route from the router.
- chi.network.remove_routes_from_router(router_id, routes)[source]
Remove a set of routes from a router.
- chi.network.remove_subnet_from_router(router_id, subnet_id)[source]
Remove a subnet from the router.
Wizards
There are additionally some functions that tie together several common tasks.
- class chi.network.wizard[source]
A collection of “wizard” functions.
These utility functions are very opinionated but can reduce boilerplate.
- static create_network(name_prefix, of_controller_ip=None, of_controller_port=None, gateway=False)[source]
Create a network and subnet, and connect the subnet to a new router.
- Parameters:
name_prefix (str) – The common name prefix for all created entities.
of_controller_ip (str) – The OpenFlow controller IP, if using.
of_controller_port (int) – The OpenFlow controller port, if using.
gateway (bool) – Whether to add a WAN gateway to the router. Routers with a WAN gateway are able to NAT to the Internet.
- Returns:
The created network representation.