slice¶

Methods to manage FABRIC slices.

You would create and use a slice like so:

from ipaddress import IPv4Address
from fabrictestbed_extensions.fablib.fablib import FablibManager

fablib = FablibManager()

# Create a slice and add resources to it, creating a topology.
slice = fablib.new_slice(name="MySlice")
node1 = slice.add_node(name="node1", site="TACC")
net1 = slice.add_l2network(name="net1", subnet=IPv4Network("192.168.1.0/24"))

# Do more setup, and then run your experiment.

# Delete the slice after you are done.
slice.delete()

class fabrictestbed_extensions.fablib.slice.Slice(fablib_manager: FablibManager, name: str = None, user_only: bool = True)¶

Create a FABRIC slice, and set its state to be callable.

Parameters:: name (str) – the name of this fablib slice

__str__()¶

Creates a tabulated string describing the properties of the slice.

Intended for printing slice information.

Returns:: Tabulated string of slice information
Return type:: String

add_facility_port(name: str | None = None, site: str | None = None, vlan: str | list | None = None) → NetworkService¶

Adds a new L2 facility port to this slice

Parameters:

name (String) – name of the facility port
site (String) – site
vlan (String) – vlan

Returns:

a new L2 facility port

Return type:

NetworkService

add_l2network(name: str = None, interfaces: List[Interface] = [], type: str = None, subnet: ipaddress = None, gateway: ipaddress = None, user_data: dict = {}) → NetworkService¶

Adds a new L2 network service to this slice.

L2 networks types include:

L2Bridge: a local Ethernet on a single site with unlimited interfaces.
L2STS: a wide-area Ethernet on exactly two sites with unlimited interfaces.
Includes best effort performance and cannot, yet, support Basic NICs residing on a single physical.
L2PTP: a wide-area Ethernet on exactly two sites with exactly two interfaces.
QoS performance guarantees (coming soon!). Does not support Basic NICs. Traffic arrives with VLAN tag and requires the node OS to configure a VLAN interface.

If the type argument is not set, FABlib will automatically choose the L2 network type for you. In most cases the automatic network type is the one you want. You can force a specific network type by setting the type parameter to “L2Bridge”, “L2STS”, or “L2PTP”.

An exception will be raised if the set interfaces is not compatible with the specified network type or if there is not compatible network type for the given interface list.

Parameters:

name (String) – the name of the network service
interfaces (List[Interface]) – a list of interfaces to build the network with
type (String) – optional L2 network type “L2Bridge”, “L2STS”, or “L2PTP”
subnet (ipaddress)
gateway (ipaddress)

:param user_data :type user_data: dict :return: a new L2 network service :rtype: NetworkService

add_l3network(name: str | None = None, interfaces: List[Interface] = [], type: str = 'IPv4', user_data: dict = {}) → NetworkService¶

Adds a new L3 network service to this slice.

L3 networks types include:

IPv4: An IPv4 network on the FABNetv4 internet
IPv6: An IPv6 network on the FABNetv6 internet

The FABNet networks are internal IP internets that span the FABRIC testbed. Adding a new L3 network to your FABRIC slice creates an isolated network at a single site. FABRIC issues each isolated L3 network with an IP subnet (either IPv4 or IPv6) and a gateway used to route traffic to the FABNet internet.

Like the public Internet, all FABNet networks can send traffic to all other FABnet networks of the same type. In other words, FABNet networks can be used to communicate between your slices and slices owned by other users.

An exception will be raised if the set interfaces is not from a single FABRIC site. If you want to use L3 networks to connect slices that are distributed across many site, you need to create a separate L3 network for each site.

It is important to note that by all nodes come with a default gateway on a management network that use used to access your nodes (i.e. to accept ssh connections). To use an L3 dataplane network, you will need to add routes to your nodes that selectively route traffic across the new dataplane network. You must be careful to maintain the default gateway settings if you want to be able to access the node using the management network.

Parameters:

name (String) – the name of the network service
interfaces (List[Interface]) – a list of interfaces to build the network with
type (String) – L3 network type “IPv4” or “IPv6”

:param user_data :type user_data: dict

Returns:: a new L3 network service
Return type:: NetworkService

add_node(name: str, site: str | None = None, cores: int = 2, ram: int = 8, disk: int = 10, image: str | None = None, instance_type: str | None = None, host: str | None = None, user_data: dict = {}, avoid: List[str] = []) → Node¶

Creates a new node on this fablib slice.

Parameters:

name (String) – Name of the new node
site (String) – (Optional) Name of the site to deploy the node on. Default to a random site.
cores (int) – (Optional) Number of cores in the node. Default: 2 cores
ram (int) – (Optional) Amount of ram in the node. Default: 8 GB
disk (int) – (Optional) Amount of disk space n the node. Default: 10 GB
image (String) – (Optional) The image to uese for the node. Default: default_rocky_8
instance_type (String)
host (String) – (Optional) The physical host to deploy the node. Each site has worker nodes numbered 1, 2, 3, etc. Host names follow the pattern in this example of STAR worker number 1: “star-w1.fabric-testbed.net”. Default: unset

:param user_data :type user_data: dict

Parameters:: avoid (List[String]) – (Optional) A list of sites to avoid is allowing random site.
Returns:: a new node
Return type:: Node

add_port_mirror_service(name: str, mirror_interface_name: str, receive_interface: Interface | None = None, mirror_direction: str = 'both') → NetworkService¶

Adds a special PortMirror service.

It receives data from the dataplane switch interface specified by mirror_interface into an interface specified by receive_interface.

Parameters:

name – Name of the service
mirror_interface_name – Name of the interface on the dataplane switch to mirror
receive_interface – Interface in the topology belonging to a SmartNIC component
mirror_direction – String ‘rx’, ‘tx’ or ‘both’ defaulting to ‘both’ which receives the data

build_error_exception_string() → str¶

Not intended for API use

Formats one string with all the error information on this slice’s nodes.

Returns:: a string with all the error information relevant to this slice
Return type:: str

delete()¶

Deletes this slice off of the slice manager and removes its topology.

Raises:: Exception – if deleting the slice fails

get_components() → List[Component]¶

Gets all components in this slice.

Returns:: List of all components in this slice
Return type:: List[Component]

get_error_messages() → List[dict]¶

Gets the error messages found in the sliver notices.

Returns:: a list of error messages
Return type:: List[Dict[String, String]]

get_fim_topology() → ExperimentTopology¶

Not recommended for most users.

Gets the slice’s FABRIC Information Model (fim) topology. This method is used to access data at a lower level than FABlib.

Returns:: FABRIC experiment topology
Return type:: ExperimentTopology

get_interface(name: str | None = None) → Interface¶

Gets a particular interface from this slice.

Parameters:: name (str) – the name of the interface to search for
Raises:: Exception – if no interfaces with name are found
Returns:: an interface on this slice
Return type:: Interface

get_interfaces() → List[Interface]¶

Gets all interfaces in this slice.

Returns:: a list of interfaces on this slice
Return type:: List[Interface]

get_l2network(name: str | None = None) → NetworkService¶

Gets a particular L2 network service from this slice.

Parameters:: name (str) – the name of the network service to search for
Returns:: a particular network service
Return type:: NetworkService

get_l2networks() → List[NetworkService]¶

Gets a list of the L2 network services on this slice.

Returns:: network services on this slice
Return type:: list[NetworkService]

get_l3network(name: str | None = None) → NetworkService¶

Gets a particular L3 network service from this slice.

Parameters:: name (String) – Name network
Returns:: network services on this slice
Return type:: list[NetworkService]

get_l3networks() → List[NetworkService]¶

Gets all L3 networks services in this slice

Returns:: List of all network services in this slice
Return type:: List[NetworkService]

get_lease_end() → str¶

Gets the timestamp at which the slice lease ends.

Returns:: timestamp when lease ends
Return type:: String

get_lease_start() → str¶

Gets the timestamp at which the slice lease starts.

Returns:: timestamp when lease starts
Return type:: String

get_name() → str¶

Gets the slice’s name.

Returns:: the slice name
Return type:: String

get_network(name: str | None = None) → NetworkService¶

Gest a particular network service from this slice.

Parameters:: name (str) – the name of the network service to search for
Returns:: a particular network service
Return type:: NetworkService

get_network_services() → List[NetworkService]¶

Not intended for API use. See: slice.get_networks()

Gets all network services (L2 and L3) in this slice

Returns:: List of all network services in this slice
Return type:: List[NetworkService]

get_networks() → List[NetworkService]¶

Gets all network services (L2 and L3) in this slice

Returns:: List of all network services in this slice
Return type:: List[NetworkService]

get_node(name: str) → Node¶

Gets a node from the slice by name.

Parameters:: name (String) – Name of the node
Returns:: a fablib node
Return type:: Node

get_nodes() → List[Node]¶

Gets a list of all nodes in this slice.

Returns:: a list of fablib nodes
Return type:: List[Node]

get_notices() → Dict[str, str]¶

Gets a dictionary all sliver notices keyed by reservation id.

Returns:: dictionary of node IDs to error messages
Return type:: dict[str, str]

get_object_by_reservation(reservation_id: str) → Node | NetworkService | Interface | None¶

Gets an object associated with this slice by its reservation ID.

Parameters:: reservation_id – the ID to search for
Returns:: Object

get_private_key_passphrase() → str¶

Gets the slice private key passphrase.

Important! Slice key management is underdevelopment and this functionality will likely change going forward.

Returns:: the private key passphrase
Return type:: String

get_project_id() → str¶

Gets the project id of the slice.

Returns:: project id
Return type:: String

static get_slice(fablib_manager: FablibManager, sm_slice: OrchestratorSlice = None, user_only: bool = True)¶

Not intended for API use.

Gets an existing fablib slice using a slice manager slice :param fablib_manager: :param sm_slice: :param user_only: True indicates return own slices; False indicates return project slices :type user_only: bool :return: Slice

get_slice_id() → str¶

Gets the slice’s ID.

Returns:: the slice ID
Return type:: String

get_slice_private_key() → str¶

Gets the string representing the slice private key.

Returns:: public key
Return type:: String

get_slice_private_key_file() → str¶

Gets the path to the slice private key file.

Important! Slice key management is underdevelopment and this functionality will likely change going forward.

Returns:: path to private key file
Return type:: String

get_slice_public_key() → str¶

Gets the slice public key.

Important! Slice key management is underdevelopment and this functionality will likely change going forward.

Returns:: the public key
Return type:: String

get_slice_public_key_file() → str¶

Gets the path to the slice public key file.

Important! Slice key management is underdevelopment and this functionality will likely change going forward.

Returns:: path to public key file
Return type:: String

get_state() → str¶

Gets the slice state.

Returns:: the slice state
Return type:: str

isStable() → bool¶

Tests is the slice is stable. Stable means all requests for to add/remove/modify slice resources have completed. Both successful and failed slice requests are considered to be completed.

Returns:: True if slice is stable, False otherwise
Return type:: Bool

list_components(output: str | None = None, fields: List[str] | None = None, quiet: bool = False, filter_function=None, pretty_names=True)¶

Lists all the components in the slice with their attributes.

There are several output options: “text”, “pandas”, and “json” that determine the format of the output that is returned and (optionally) displayed/printed.

output: ‘text’: string formatted with tabular: ‘pandas’: pandas dataframe ‘json’: string in json format

fields: json output will include all available fields/columns.

Example: fields=[‘Name’,’Model’]

filter_function: A lambda function to filter data by field values.

Example: filter_function=lambda s: s[‘Model’] == ‘NIC_Basic’

Parameters:

output (str) – output format
fields (List[str]) – list of fields (table columns) to show
quiet (bool) – True to specify printing/display
filter_function (lambda) – lambda function
pretty_names (bool)

Returns:

table in format specified by output parameter

Return type:

Object

list_interfaces(output: str | None = None, fields: List[str] | None = None, quiet: bool = False, filter_function=None, pretty_names=True)¶

Lists all the interfaces in the slice with their attributes.

There are several output options: “text”, “pandas”, and “json” that determine the format of the output that is returned and (optionally) displayed/printed.

output: ‘text’: string formatted with tabular: ‘pandas’: pandas dataframe ‘json’: string in json format

fields: json output will include all available fields/columns.

Example: fields=[‘Name’,’Type’, ‘State’]

filter_function: A lambda function to filter data by field values.

Example: filter_function=lambda s: s[‘Type’] == ‘FABNetv4’

Parameters:

output (str) – output format
fields (List[str]) – list of fields (table columns) to show
quiet (bool) – True to specify printing/display
filter_function (lambda) – lambda function
pretty_names (bool)

Returns:

table in format specified by output parameter

Return type:

Object

list_networks(output=None, fields=None, colors=False, quiet=False, filter_function=None, pretty_names=True)¶

Lists all the networks in the slice.

There are several output options: “text”, “pandas”, and “json” that determine the format of the output that is returned and (optionally) displayed/printed.

output: ‘text’: string formatted with tabular ‘pandas’: pandas dataframe ‘json’: string in json format

fields: json output will include all available fields/columns.

Example: fields=[‘Name’,’State’]

filter_function: A lambda function to filter data by field values.

Example: filter_function=lambda s: s[‘State’] == ‘Active’

Parameters:

output (str) – output format
fields (List[str]) – list of fields (table columns) to show
colors (bool) – True to add colors to the table when possible
quiet (bool) – True to specify printing/display
filter_function (lambda) – lambda function
pretty_names (bool) – Use “nicer” names in column headers. Default is True.

Returns:

table in format specified by output parameter

Return type:

Object

list_nodes(output=None, fields=None, colors=False, quiet=False, filter_function=None, pretty_names=True)¶

Lists all the nodes in the slice.

There are several output options: “text”, “pandas”, and “json” that determine the format of the output that is returned and (optionally) displayed/printed.

output: ‘text’: string formatted with tabular: ‘pandas’: pandas dataframe ‘json’: string in json format

fields: json output will include all available fields/columns.

Example: fields=[‘Name’,’State’]

filter_function: A lambda function to filter data by field values.

Example: filter_function=lambda s: s[‘State’] == ‘Active’

Parameters:

output (str) – output format
fields (List[str]) – list of fields (table columns) to show
quiet (bool) – True to specify printing/display
filter_function (lambda) – lambda function
colors (bool) – True to add colors to the table when possible
pretty_names (bool)

Returns:

table in format specified by output parameter

Return type:

Object

list_slivers(output=None, fields=None, colors=False, quiet=False, filter_function=None, pretty_names=True)¶

Lists all the slivers in the slice.

There are several output options: “text”, “pandas”, and “json” that determine the format of the output that is returned and (optionally) displayed/printed.

output: ‘text’: string formatted with tabular: ‘pandas’: pandas dataframe ‘json’: string in json format

fields: json output will include all available fields/columns.

Example: fields=[‘Name’,’State’]

filter_function: A lambda function to filter data by field values.

Example: filter_function=lambda s: s[‘State’] == ‘Active’

Parameters:

output (str) – output format
fields (List[str]) – list of fields (table columns) to show
quiet (bool) – True to specify printing/display
filter_function (lambda) – lambda function
colors (bool) – True to add colors to the table when possible
pretty_names (bool)

Returns:

table in format specified by output parameter

Return type:

Object

load(filename)¶

Loads a slice request topology from file. The file can be loaded to create a new slice with the same topology as a previously saved slice.

Parameters:: filename (String) – path to the file to save the slice.

modify(wait: int = True, wait_timeout: int = 600, wait_interval: int = 10, progress: bool = True, wait_jupyter: str = 'text', post_boot_config: bool = True)¶

Submits a modify slice request to FABRIC.

Can be blocking or non-blocking.

Blocking calls can, optionally,configure timeouts and intervals.

Blocking calls can, optionally, print progress info.

Parameters:

wait – indicator for whether to wait for the slice’s resources to be active
wait_timeout – how many seconds to wait on the slice resources
wait_interval – how often to check on the slice resources
progress – indicator for whether to show progress while waiting
wait_jupyter – Special wait for jupyter notebooks.
post_boot_config – Flag indicating if post boot config should be applied

modify_accept()¶: Submits an accept to accept the last modify slice request to FABRIC.

static new_slice(fablib_manager: FablibManager, name: str = None)¶: Create a new slice :param fablib_manager: :param name: :return: Slice

post_boot_config()¶

Run post boot configuration. Typically, this is run automatically during a blocking call to submit.

Only use this method after a non-blocking submit call and only call it once.

renew(end_date: str | None = None, days: int | None = None)¶

Renews the FABRIC slice’s lease to the new end date.

Date is in UTC and of the form: “%Y-%m-%d %H:%M:%S %z”

Example of formatting a date for 1 day from now:

end_date = (datetime.datetime.now() + datetime.timedelta(days=1)).strftime(“%Y-%m-%d %H:%M:%S %z”)

Parameters:

end_date – String
days – Integer

Raises:

Exception – if renewal fails

save(filename)¶

Saves the slice topology to a file. The file can be loaded to create a new slice with the same topology.

The slice topology can be saved before the original request has been submitted or after. If the slice is saved after it is instantiated, only the topology is saved. Any configuration of nodes is not included.

Parameters:: filename (String) – path to the file to save the slice.

show(fields=None, output=None, quiet=False, colors=False, pretty_names=True)¶

Show a table containing the current slice attributes.

There are several output options: “text”, “pandas”, and “json” that determine the format of the output that is returned and (optionally) displayed/printed.

output: ‘text’: string formatted with tabular: ‘pandas’: pandas dataframe ‘json’: string in json format

fields: json output will include all available fields.

Example: fields=[‘Name’,’State’]

Parameters:

output (str) – output format
fields (List[str]) – list of fields to show
quiet (bool) – True to specify printing/display
colors (bool) – True to specify state colors for pandas output
pretty_names (bool)

Returns:

table in format specified by output parameter

Return type:

Object

submit(wait: bool = True, wait_timeout: int = 1800, wait_interval: int = 20, progress: bool = True, wait_jupyter: str = 'text', post_boot_config: bool = True, wait_ssh: bool = True, extra_ssh_keys: List[str] | None = None, lease_in_days: int | None = None) → str¶

Submits a slice request to FABRIC.

Can be blocking or non-blocking.

Blocking calls can, optionally,configure timeouts and intervals.

Blocking calls can, optionally, print progress info.

Parameters:

wait – indicator for whether to wait for the slice’s resources to be active
wait_timeout – how many seconds to wait on the slice resources
wait_interval – how often to check on the slice resources
progress – indicator for whether to show progress while waiting
wait_jupyter – Special wait for jupyter notebooks.
post_boot_config
wait_ssh
extra_ssh_keys – Optional list of additional SSH public keys to be installed in the slivers of this slice
lease_in_days – Optional lease duration in days, by default the slice is active for 24 hours i.e 1 day, only used for create.

Returns:

slice_id

test_ssh() → bool¶

Tests all nodes in the slices are accessible via ssh.

Returns:: result of testing if all VMs in the slice are accessible via ssh
Return type:: bool

toDict(skip=[])¶

Returns the slice attributes as a dictionary

Returns:: slice attributes as dictionary
Return type:: dict

toJson()¶

Returns the slice attributes as a json string

Returns:: slice attributes as json string
Return type:: str

update()¶

(re)Query the FABRIC services for updated information about this slice.

Raises:: Exception – if updating topology fails

update_slice()¶

Not recommended for most users. See Slice.update() method.

Updates this slice manager slice to store the most up-to-date slice manager slice

Raises:: Exception – if slice manager slice no longer exists

update_slivers()¶

Not recommended for most users. See Slice.update() method.

Updates the slivers with the current slice manager.

Raises:: Exception – if topology could not be gotten from slice manager

update_topology()¶

Not recommended for most users. See Slice.update() method.

Updates the fabric slice topology with the slice manager slice’s topology

Raises:: Exception – if topology could not be gotten from slice manager

validIPAddress(IP: str) → str¶: Not intended as a API call.

wait(timeout: int = 360, interval: int = 10, progress: bool = False)¶

Waits for the slice on the slice manager to be in a stable, running state.

Parameters:

timeout (int) – how many seconds to wait on the slice
interval (int) – how often in seconds to check on slice state
progress (bool) – indicator for whether to print wait progress

Raises:

Exception – if the slice state is undesirable, or waiting times out

Returns:

the stable slice on the slice manager

Return type:

SMSlice

wait_jupyter(timeout: int = 1800, interval: int = 30, verbose=False)¶

Waits for the slice to be in a stable and displays jupyter compliant tables of the slice progress.

Parameters:

timeout (int) – how many seconds to wait on the slice
interval (int) – how often in seconds to check on slice state
verbose (bool)

Raises:

Exception – if the slice state is undesirable, or waiting times out

Returns:

the stable slice on the slice manager

Return type:

SMSlice

wait_ssh(timeout: int = 1800, interval: int = 20, progress: bool = False)¶

Waits for all nodes to be accessible via ssh.

Parameters:

timeout (int) – how long to wait on slice ssh
interval (int) – how often to check on slice ssh
progress (bool) – indicator for verbose output

Raises:

Exception – if timeout threshold reached

Returns:

true when slice ssh successful

Return type:

bool