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, name=None, user_only=True, sm_slice=None)[source]

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

Parameters:

name (str) – the name of this fablib slice

add_attestable_switch(name, site=None, cores=4, ram=8, disk=50, image='crease_ubuntu_22', ports=None, instance_type=None, host=None, user_data={}, avoid=[], validate=False, raise_exception=False, from_raw_image=False, setup_and_configure=True)[source]

Creates a new attestable switch on this fablib slice.

Return type:

Attestable_Switch

add_facility_port(name=None, site=None, vlan=None, labels=None, peer_labels=None, bandwidth=None, mtu=None)[source]

Adds a new L2 facility port to this slice

Parameters:

  • name (String) – name of the facility port

  • site (String) – site

  • vlan (String) – vlan

  • labels (Labels) – labels for the facility port such as VLAN, ip sub net

  • peer_labels (Labels) – peer labels for the facility port such as VLAN, ip sub net, bgp key - used for AL2S Peering

  • bandwidth (int) – bandwidth

  • mtu (int) – MTU size

Type:

labels: Labels

Type:

peer_labels: Labels

Type:

bandwidth: int

Type:

mtu: int

Returns:

a new L2 facility port

Return type:

NetworkService

add_l2network(name=None, interfaces=[], type=None, subnet=None, gateway=None, user_data={})[source]

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)

  • user_data (dict)

Returns:

a new L2 network service

Return type:

NetworkService

add_l3network(name=None, interfaces=[], type='IPv4', user_data={}, technology=None, subnet=None, site=None)[source]

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”

  • user_data (dict)

  • technology (str) – Specify the technology used should be set to AL2S when using for AL2S peering; otherwise None

  • subnet (ipaddress.ip_network) – Request a specific subnet for FabNetv4, FabNetv6 or FabNetv6Ext services. It’s ignored for any other services.

  • site (str) – Site

Returns:

a new L3 network service

Return type:

NetworkService

add_node(name, site=None, cores=2, ram=8, disk=10, image=None, instance_type=None, host=None, user_data={}, avoid=[], validate=False, raise_exception=False, storage=False, storage_cluster=None)[source]

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 in the node. Default: 10 GB

  • image (String) – (Optional) The image to use for the node. Default: default_rocky_9

  • 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

  • user_data (dict)

  • avoid (List[String]) – (Optional) A list of sites to avoid is allowing random site.

  • validate (bool) – Validate node can be allocated w.r.t available resources

  • raise_exception (bool) – Raise exception in case of Failure

  • storage (bool) – (Optional) Enable CephFS storage on this node. Adds a FABNetv4 network and configures CephFS mount during post-boot. Default: False

  • storage_cluster (str) – (Optional) Ceph cluster name for storage. When None, the first available cluster is auto-discovered.

Returns:

a new node

Return type:

Node

add_port_mirror_service(name, mirror_interface_name, receive_interface=None, mirror_interface_vlan=None, mirror_direction='both')[source]

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 (str) – Name of the service

  • mirror_interface_name (str) – Name of the interface on the dataplane switch to mirror

  • mirror_interface_vlan (Optional[str]) – Vlan of the interface

  • receive_interface (Optional[Interface]) – Interface in the topology belonging to a SmartNIC component

  • mirror_direction (Optional[str]) – String ‘rx’, ‘tx’ or ‘both’ defaulting to ‘both’ which receives the data

Return type:

NetworkService

add_switch(name, site=None, user_data=None, avoid=None, validate=False, raise_exception=False)[source]

Creates a new switch on this fablib slice.

Parameters:

  • name (String) – Name of the new switch

  • site (String) – (Optional) Name of the site to deploy the node on. Default to a random site.

  • user_data (dict)

  • avoid (List[String]) – (Optional) A list of sites to avoid is allowing random site.

  • validate (bool) – Validate node can be allocated w.r.t available resources

  • raise_exception (bool) – Raise exception in case of Failure

Returns:

a new node

Return type:

Node

build_error_exception_string()[source]

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

close_ssh()[source]

Close all cached SSH connections for nodes in this slice.

Iterates through all nodes and closes their cached bastion and node SSH connections. Safe to call multiple times.

delete()[source]

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

Raises:

Exception – if deleting the slice fails

execute_on_all_nodes(command, **kwargs)[source]

Execute a command on all nodes in parallel.

Submits the command to each node’s SSH thread pool and waits for all results. Additional keyword arguments are passed through to Node.execute().

Parameters:

command (str) – command to execute on each node

Returns:

dict mapping node name to (stdout, stderr) tuple

Return type:

dict

get_attestable_switch(name)[source]

Get reference to an attestable switch in the fablib slice.

Parameters:

name (str) – Name of the attestable switch

Returns:

The attestable switch

Return type:

Attestable_Switch

get_attestable_switches()[source]

Get list of attestable switches in the fablib slice.

Return type:

List[Attestable_Switch]

get_components(refresh=False)[source]

Gets all components in this slice.

Parameters:

refresh (bool) – Refresh the components with latest Fim info

Returns:

List of all components in this slice

Return type:

List[Component]

get_email()[source]

Gets the owner’s email of the slice.

Returns:

email

Return type:

String

get_error_messages()[source]

Gets the error messages found in the sliver notices.

Returns:

a list of error messages

Return type:

List[Dict[String, String]]

get_fablib_manager()[source]

Return the associated FablibManager instance.

Return type:

FablibManager

get_facilities(refresh=False)[source]

Gets a list of all nodes in this slice.

Returns:

a list of fablib nodes

Return type:

List[FacilityPort]

get_facility(name)[source]

Gets a facility port from the slice by name.

Parameters:

name (String) – Name of the facility Port

Returns:

a fablib FacilityPort

Return type:

FacilityPort

get_fim()[source]

Get FABRIC Information Model (fim) object for the slice.

Return type:

ExperimentTopology

get_fim_topology()[source]

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=None, refresh=False)[source]

Gets a particular interface from this slice.

Parameters:

  • name (str) – the name of the interface to search for

  • refresh (bool) – Refresh the interface object with latest Fim info

Raises:

Exception – if no interfaces with name are found

Returns:

an interface on this slice

Return type:

Interface

get_interfaces(include_subs=True, refresh=False, output='list')[source]

Gets all interfaces in this slice.

Parameters:

  • include_subs (bool) – Flag indicating if sub interfaces should be included

  • refresh (bool) – Refresh the interface object with latest Fim info

  • output (str) – Specify how the return type is expected; Possible values: list or dict

Returns:

a list of interfaces on this slice

Return type:

Union[dict[str, Interface], list[Interface]]

get_l2network(name=None)[source]

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()[source]

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

Returns:

network services on this slice

Return type:

list[NetworkService]

get_l3network(name=None)[source]

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()[source]

Gets all L3 networks services in this slice

Returns:

List of all network services in this slice

Return type:

List[NetworkService]

get_lease_end()[source]

Gets the timestamp at which the slice lease ends.

Returns:

timestamp when lease ends

Return type:

String

get_lease_start()[source]

Gets the timestamp at which the slice lease starts.

Returns:

timestamp when lease starts

Return type:

String

get_name()[source]

Gets the slice’s name.

Returns:

the slice name

Return type:

String

get_network(name=None, raise_exception=None)[source]

Gets a particular network service from this slice.

Parameters:

  • name (str) – the name of the network service to search for

  • raise_exception (bool) – if True, raise ResourceNotFoundError when the network is not found; if False, return None. When None (default), falls back to the global FablibManager.raise_on_not_found setting.

Returns:

a particular network service or None

Return type:

Optional[NetworkService]

Raises:

ResourceNotFoundError – if the network is not found and raising is enabled

get_network_services(force_refresh=False)[source]

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

Gets all network services (L2 and L3) in this slice. Results are cached for performance.

Parameters:

force_refresh (bool) – Force refresh from topology even if cached

Returns:

List of all network services in this slice

Return type:

List[NetworkService]

get_networks(refresh=True, output='list')[source]

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

Results are cached for performance.

Returns:

List of all network services in this slice

Return type:

List[NetworkService]

get_node(name)[source]

Gets a node from the slice by name.

Parameters:

name (String) – Name of the node

Returns:

a fablib node

Return type:

Node

get_nodes(refresh=False, site=None, filter_function=None)[source]

Gets a list of nodes in this slice, optionally filtered.

Parameters:

  • refresh (bool) – force refresh from FIM topology

  • site (str) – filter nodes by site name (e.g. “RENC”)

  • filter_function (callable) – custom filter function taking a Node and returning bool (e.g. lambda n: n.get_cores() >= 4)

Returns:

a list of fablib nodes

Return type:

List[Node]

get_notices()[source]

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)[source]

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

Parameters:

reservation_id (str) – the ID to search for

Return type:

Union[Node, NetworkService, Interface, None]

Returns:

Object

static get_pretty_names_dict()[source]

Return the mapping of field names to display-friendly names.

get_private_key_passphrase()[source]

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()[source]

Gets the project id of the slice.

Returns:

project id

Return type:

String

static get_slice(fablib_manager, sm_slice, user_only=True)[source]

Not intended for API use.

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

get_slice_id()[source]

Gets the slice’s ID.

Returns:

the slice ID

Return type:

String

get_slice_private_key()[source]

Gets the string representing the slice private key.

Returns:

public key

Return type:

String

get_slice_private_key_file()[source]

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()[source]

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()[source]

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_sliver(reservation_id)[source]

Returns the sliver associated with the reservation ID.

Uses a dict cache for O(1) lookups instead of filtering the full sliver list on each call.

Return type:

SliverDTO

get_slivers()[source]

Returns slivers associated with the slice.

Return type:

List[SliverDTO]

get_state()[source]

Gets the slice state.

Returns:

the slice state

Return type:

str

get_template_context(base_object=None, skip=None)[source]

Build a Jinja2 template context for this slice and its nodes.

get_user_data()[source]

Retrieve user data associated with the slice.

get_user_id()[source]

Gets the owner’s user id of the slice.

Returns:

user id

Return type:

String

isReady(update=False)[source]

Returns True if the slice is ready; else returns False.

Return type:

bool

isStable()[source]

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

is_advanced_allocation()[source]

Checks if slice is requested in future

Returns:

True if slice is Allocated and starts in future, False otherwise

Return type:

Bool

is_allocated()[source]

Tests is the slice is in Allocated State.

Returns:

True if slice is Allocated, False otherwise

Return type:

Bool

is_dead_or_closing()[source]

Tests is the slice is Dead or Closing state.

Returns:

True if slice is Dead or Closing state, False otherwise

Return type:

Bool

list_components(output=None, fields=None, quiet=False, filter_function=None, pretty_names=True, refresh=False)[source]

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)

  • refresh (bool) – Refresh the interface object with latest Fim info

Returns:

table in format specified by output parameter

Return type:

Object

list_facilities(output=None, fields=None, colors=False, quiet=False, filter_function=None, pretty_names=True)[source]

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_interfaces(output=None, fields=None, quiet=False, filter_function=None, pretty_names=True, refresh=False)[source]

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)

  • refresh (bool) – Refresh the interface object with latest Fim info

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)[source]

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)[source]

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)[source]

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)[source]

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=True, wait_timeout=600, wait_interval=10, progress=True, wait_jupyter='text', post_boot_config=True)[source]

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 (int) – indicator for whether to wait for the slice’s resources to be active

  • wait_timeout (int) – how many seconds to wait on the slice resources

  • wait_interval (int) – how often to check on the slice resources

  • progress (bool) – indicator for whether to show progress while waiting

  • wait_jupyter (str) – Special wait for jupyter notebooks.

  • post_boot_config (bool) – Flag indicating if post boot config should be applied

modify_accept()[source]

Submits an accept to accept the last modify slice request to FABRIC.

static new_slice(fablib_manager, name=None, storage=False, storage_cluster=None)[source]

Create a new slice

Parameters:

  • fablib_manager (FablibManager)

  • name (str)

  • storage (bool) – Enable CephFS storage on every node added to this slice. Default: False

  • storage_cluster (str) – Ceph cluster name. When None, the first available cluster is auto-discovered at post-boot time.

Returns:

Slice

post_boot_config()[source]

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.

Raises:

RuntimeError – if no_ssh mode is enabled

renew(end_date=None, days=None, **kwargs)[source]

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 (str) – String

  • days (int) – Integer

Raises:

Exception – if renewal fails

save(filename)[source]

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)[source]

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=True, wait_timeout=1800, wait_interval=20, progress=True, wait_jupyter='text', post_boot_config=True, wait_ssh=True, extra_ssh_keys=None, lease_start_time=None, lease_end_time=None, lease_in_hours=None, validate=False)[source]

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 (bool) – indicator for whether to wait for the slice’s resources to be active

  • wait_timeout (int) – how many seconds to wait on the slice resources

  • wait_interval (int) – how often to check on the slice resources

  • progress (bool) – indicator for whether to show progress while waiting

  • wait_jupyter (str) – Special wait for jupyter notebooks.

  • post_boot_config (bool)

  • wait_ssh (bool)

  • extra_ssh_keys (List[str]) – Optional list of additional SSH public keys to be installed in the slivers of this slice

  • lease_start_time (datetime) – Optional lease start time in UTC format: %Y-%m-%d %H:%M:%S %z. Specifies the beginning of the time range to search for available resources valid for lease_in_hours.

  • lease_end_time (datetime) – Optional lease end time in UTC format: %Y-%m-%d %H:%M:%S %z. Specifies the end of the time range to search for available resources valid for lease_in_hours.

  • lease_in_hours (int) – Optional lease duration in hours. By default, the slice remains active for 24 hours (1 day). This parameter is only applicable during creation.

  • validate (bool) – Validate node can be allocated w.r.t available resources

Return type:

str

Returns:

slice_id

test_ssh()[source]

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=None)[source]

Returns the slice attributes as a dictionary

Parameters:

skip (list) – list of keys to exclude

Returns:

slice attributes as dictionary

Return type:

dict

toJson()[source]

Returns the slice attributes as a json string

Returns:

slice attributes as json string

Return type:

str

update()[source]

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

Raises:

Exception – if updating topology fails

update_slice()[source]

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()[source]

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()[source]

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)[source]

Not intended as a API call.

Return type:

str

validate(raise_exception=True)[source]

Validate the slice w.r.t available resources before submission.

Fetches resources once and delegates to NodeValidator.validate_nodes() for batch validation.

Parameters:

raise_exception (bool) – raise exception if validation fails

Returns:

Tuple indicating status for validation and dictionary of the errors corresponding to each requested node

Return type:

Tuple[bool, Dict[str, str]]

wait(timeout=360, interval=10, progress=False)[source]

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=1800, interval=30, verbose=False, post_boot_config=True)[source]

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)

  • post_boot_config (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=1800, interval=20, progress=False)[source]

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:
Returns:

true when slice ssh successful

Return type:

bool

class fabrictestbed_extensions.fablib.slice.Slice(fablib_manager, name=None, user_only=True, sm_slice=None)[source]

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

Parameters:

name (str) – the name of this fablib slice

__str__()[source]

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_attestable_switch(name, site=None, cores=4, ram=8, disk=50, image='crease_ubuntu_22', ports=None, instance_type=None, host=None, user_data={}, avoid=[], validate=False, raise_exception=False, from_raw_image=False, setup_and_configure=True)[source]

Creates a new attestable switch on this fablib slice.

Return type:

Attestable_Switch

add_facility_port(name=None, site=None, vlan=None, labels=None, peer_labels=None, bandwidth=None, mtu=None)[source]

Adds a new L2 facility port to this slice

Parameters:

  • name (String) – name of the facility port

  • site (String) – site

  • vlan (String) – vlan

  • labels (Labels) – labels for the facility port such as VLAN, ip sub net

  • peer_labels (Labels) – peer labels for the facility port such as VLAN, ip sub net, bgp key - used for AL2S Peering

  • bandwidth (int) – bandwidth

  • mtu (int) – MTU size

Type:

labels: Labels

Type:

peer_labels: Labels

Type:

bandwidth: int

Type:

mtu: int

Returns:

a new L2 facility port

Return type:

NetworkService

add_l2network(name=None, interfaces=[], type=None, subnet=None, gateway=None, user_data={})[source]

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)

  • user_data (dict)

Returns:

a new L2 network service

Return type:

NetworkService

add_l3network(name=None, interfaces=[], type='IPv4', user_data={}, technology=None, subnet=None, site=None)[source]

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”

  • user_data (dict)

  • technology (str) – Specify the technology used should be set to AL2S when using for AL2S peering; otherwise None

  • subnet (ipaddress.ip_network) – Request a specific subnet for FabNetv4, FabNetv6 or FabNetv6Ext services. It’s ignored for any other services.

  • site (str) – Site

Returns:

a new L3 network service

Return type:

NetworkService

add_node(name, site=None, cores=2, ram=8, disk=10, image=None, instance_type=None, host=None, user_data={}, avoid=[], validate=False, raise_exception=False, storage=False, storage_cluster=None)[source]

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 in the node. Default: 10 GB

  • image (String) – (Optional) The image to use for the node. Default: default_rocky_9

  • 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

  • user_data (dict)

  • avoid (List[String]) – (Optional) A list of sites to avoid is allowing random site.

  • validate (bool) – Validate node can be allocated w.r.t available resources

  • raise_exception (bool) – Raise exception in case of Failure

  • storage (bool) – (Optional) Enable CephFS storage on this node. Adds a FABNetv4 network and configures CephFS mount during post-boot. Default: False

  • storage_cluster (str) – (Optional) Ceph cluster name for storage. When None, the first available cluster is auto-discovered.

Returns:

a new node

Return type:

Node

add_port_mirror_service(name, mirror_interface_name, receive_interface=None, mirror_interface_vlan=None, mirror_direction='both')[source]

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 (str) – Name of the service

  • mirror_interface_name (str) – Name of the interface on the dataplane switch to mirror

  • mirror_interface_vlan (Optional[str]) – Vlan of the interface

  • receive_interface (Optional[Interface]) – Interface in the topology belonging to a SmartNIC component

  • mirror_direction (Optional[str]) – String ‘rx’, ‘tx’ or ‘both’ defaulting to ‘both’ which receives the data

Return type:

NetworkService

add_switch(name, site=None, user_data=None, avoid=None, validate=False, raise_exception=False)[source]

Creates a new switch on this fablib slice.

Parameters:

  • name (String) – Name of the new switch

  • site (String) – (Optional) Name of the site to deploy the node on. Default to a random site.

  • user_data (dict)

  • avoid (List[String]) – (Optional) A list of sites to avoid is allowing random site.

  • validate (bool) – Validate node can be allocated w.r.t available resources

  • raise_exception (bool) – Raise exception in case of Failure

Returns:

a new node

Return type:

Node

build_error_exception_string()[source]

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

close_ssh()[source]

Close all cached SSH connections for nodes in this slice.

Iterates through all nodes and closes their cached bastion and node SSH connections. Safe to call multiple times.

delete()[source]

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

Raises:

Exception – if deleting the slice fails

execute_on_all_nodes(command, **kwargs)[source]

Execute a command on all nodes in parallel.

Submits the command to each node’s SSH thread pool and waits for all results. Additional keyword arguments are passed through to Node.execute().

Parameters:

command (str) – command to execute on each node

Returns:

dict mapping node name to (stdout, stderr) tuple

Return type:

dict

get_attestable_switch(name)[source]

Get reference to an attestable switch in the fablib slice.

Parameters:

name (str) – Name of the attestable switch

Returns:

The attestable switch

Return type:

Attestable_Switch

get_attestable_switches()[source]

Get list of attestable switches in the fablib slice.

Return type:

List[Attestable_Switch]

get_components(refresh=False)[source]

Gets all components in this slice.

Parameters:

refresh (bool) – Refresh the components with latest Fim info

Returns:

List of all components in this slice

Return type:

List[Component]

get_email()[source]

Gets the owner’s email of the slice.

Returns:

email

Return type:

String

get_error_messages()[source]

Gets the error messages found in the sliver notices.

Returns:

a list of error messages

Return type:

List[Dict[String, String]]

get_fablib_manager()[source]

Return the associated FablibManager instance.

Return type:

FablibManager

get_facilities(refresh=False)[source]

Gets a list of all nodes in this slice.

Returns:

a list of fablib nodes

Return type:

List[FacilityPort]

get_facility(name)[source]

Gets a facility port from the slice by name.

Parameters:

name (String) – Name of the facility Port

Returns:

a fablib FacilityPort

Return type:

FacilityPort

get_fim()[source]

Get FABRIC Information Model (fim) object for the slice.

Return type:

ExperimentTopology

get_fim_topology()[source]

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=None, refresh=False)[source]

Gets a particular interface from this slice.

Parameters:

  • name (str) – the name of the interface to search for

  • refresh (bool) – Refresh the interface object with latest Fim info

Raises:

Exception – if no interfaces with name are found

Returns:

an interface on this slice

Return type:

Interface

get_interfaces(include_subs=True, refresh=False, output='list')[source]

Gets all interfaces in this slice.

Parameters:

  • include_subs (bool) – Flag indicating if sub interfaces should be included

  • refresh (bool) – Refresh the interface object with latest Fim info

  • output (str) – Specify how the return type is expected; Possible values: list or dict

Returns:

a list of interfaces on this slice

Return type:

Union[dict[str, Interface], list[Interface]]

get_l2network(name=None)[source]

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()[source]

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

Returns:

network services on this slice

Return type:

list[NetworkService]

get_l3network(name=None)[source]

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()[source]

Gets all L3 networks services in this slice

Returns:

List of all network services in this slice

Return type:

List[NetworkService]

get_lease_end()[source]

Gets the timestamp at which the slice lease ends.

Returns:

timestamp when lease ends

Return type:

String

get_lease_start()[source]

Gets the timestamp at which the slice lease starts.

Returns:

timestamp when lease starts

Return type:

String

get_name()[source]

Gets the slice’s name.

Returns:

the slice name

Return type:

String

get_network(name=None, raise_exception=None)[source]

Gets a particular network service from this slice.

Parameters:

  • name (str) – the name of the network service to search for

  • raise_exception (bool) – if True, raise ResourceNotFoundError when the network is not found; if False, return None. When None (default), falls back to the global FablibManager.raise_on_not_found setting.

Returns:

a particular network service or None

Return type:

Optional[NetworkService]

Raises:

ResourceNotFoundError – if the network is not found and raising is enabled

get_network_services(force_refresh=False)[source]

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

Gets all network services (L2 and L3) in this slice. Results are cached for performance.

Parameters:

force_refresh (bool) – Force refresh from topology even if cached

Returns:

List of all network services in this slice

Return type:

List[NetworkService]

get_networks(refresh=True, output='list')[source]

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

Results are cached for performance.

Returns:

List of all network services in this slice

Return type:

List[NetworkService]

get_node(name)[source]

Gets a node from the slice by name.

Parameters:

name (String) – Name of the node

Returns:

a fablib node

Return type:

Node

get_nodes(refresh=False, site=None, filter_function=None)[source]

Gets a list of nodes in this slice, optionally filtered.

Parameters:

  • refresh (bool) – force refresh from FIM topology

  • site (str) – filter nodes by site name (e.g. “RENC”)

  • filter_function (callable) – custom filter function taking a Node and returning bool (e.g. lambda n: n.get_cores() >= 4)

Returns:

a list of fablib nodes

Return type:

List[Node]

get_notices()[source]

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)[source]

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

Parameters:

reservation_id (str) – the ID to search for

Return type:

Union[Node, NetworkService, Interface, None]

Returns:

Object

static get_pretty_names_dict()[source]

Return the mapping of field names to display-friendly names.

get_private_key_passphrase()[source]

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()[source]

Gets the project id of the slice.

Returns:

project id

Return type:

String

static get_slice(fablib_manager, sm_slice, user_only=True)[source]

Not intended for API use.

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

get_slice_id()[source]

Gets the slice’s ID.

Returns:

the slice ID

Return type:

String

get_slice_private_key()[source]

Gets the string representing the slice private key.

Returns:

public key

Return type:

String

get_slice_private_key_file()[source]

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()[source]

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()[source]

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_sliver(reservation_id)[source]

Returns the sliver associated with the reservation ID.

Uses a dict cache for O(1) lookups instead of filtering the full sliver list on each call.

Return type:

SliverDTO

get_slivers()[source]

Returns slivers associated with the slice.

Return type:

List[SliverDTO]

get_state()[source]

Gets the slice state.

Returns:

the slice state

Return type:

str

get_template_context(base_object=None, skip=None)[source]

Build a Jinja2 template context for this slice and its nodes.

get_user_data()[source]

Retrieve user data associated with the slice.

get_user_id()[source]

Gets the owner’s user id of the slice.

Returns:

user id

Return type:

String

isReady(update=False)[source]

Returns True if the slice is ready; else returns False.

Return type:

bool

isStable()[source]

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

is_advanced_allocation()[source]

Checks if slice is requested in future

Returns:

True if slice is Allocated and starts in future, False otherwise

Return type:

Bool

is_allocated()[source]

Tests is the slice is in Allocated State.

Returns:

True if slice is Allocated, False otherwise

Return type:

Bool

is_dead_or_closing()[source]

Tests is the slice is Dead or Closing state.

Returns:

True if slice is Dead or Closing state, False otherwise

Return type:

Bool

list_components(output=None, fields=None, quiet=False, filter_function=None, pretty_names=True, refresh=False)[source]

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)

  • refresh (bool) – Refresh the interface object with latest Fim info

Returns:

table in format specified by output parameter

Return type:

Object

list_facilities(output=None, fields=None, colors=False, quiet=False, filter_function=None, pretty_names=True)[source]

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_interfaces(output=None, fields=None, quiet=False, filter_function=None, pretty_names=True, refresh=False)[source]

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)

  • refresh (bool) – Refresh the interface object with latest Fim info

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)[source]

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)[source]

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)[source]

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)[source]

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=True, wait_timeout=600, wait_interval=10, progress=True, wait_jupyter='text', post_boot_config=True)[source]

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 (int) – indicator for whether to wait for the slice’s resources to be active

  • wait_timeout (int) – how many seconds to wait on the slice resources

  • wait_interval (int) – how often to check on the slice resources

  • progress (bool) – indicator for whether to show progress while waiting

  • wait_jupyter (str) – Special wait for jupyter notebooks.

  • post_boot_config (bool) – Flag indicating if post boot config should be applied

modify_accept()[source]

Submits an accept to accept the last modify slice request to FABRIC.

static new_slice(fablib_manager, name=None, storage=False, storage_cluster=None)[source]

Create a new slice

Parameters:

  • fablib_manager (FablibManager)

  • name (str)

  • storage (bool) – Enable CephFS storage on every node added to this slice. Default: False

  • storage_cluster (str) – Ceph cluster name. When None, the first available cluster is auto-discovered at post-boot time.

Returns:

Slice

post_boot_config()[source]

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.

Raises:

RuntimeError – if no_ssh mode is enabled

renew(end_date=None, days=None, **kwargs)[source]

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 (str) – String

  • days (int) – Integer

Raises:

Exception – if renewal fails

save(filename)[source]

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)[source]

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=True, wait_timeout=1800, wait_interval=20, progress=True, wait_jupyter='text', post_boot_config=True, wait_ssh=True, extra_ssh_keys=None, lease_start_time=None, lease_end_time=None, lease_in_hours=None, validate=False)[source]

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 (bool) – indicator for whether to wait for the slice’s resources to be active

  • wait_timeout (int) – how many seconds to wait on the slice resources

  • wait_interval (int) – how often to check on the slice resources

  • progress (bool) – indicator for whether to show progress while waiting

  • wait_jupyter (str) – Special wait for jupyter notebooks.

  • post_boot_config (bool)

  • wait_ssh (bool)

  • extra_ssh_keys (List[str]) – Optional list of additional SSH public keys to be installed in the slivers of this slice

  • lease_start_time (datetime) – Optional lease start time in UTC format: %Y-%m-%d %H:%M:%S %z. Specifies the beginning of the time range to search for available resources valid for lease_in_hours.

  • lease_end_time (datetime) – Optional lease end time in UTC format: %Y-%m-%d %H:%M:%S %z. Specifies the end of the time range to search for available resources valid for lease_in_hours.

  • lease_in_hours (int) – Optional lease duration in hours. By default, the slice remains active for 24 hours (1 day). This parameter is only applicable during creation.

  • validate (bool) – Validate node can be allocated w.r.t available resources

Return type:

str

Returns:

slice_id

test_ssh()[source]

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=None)[source]

Returns the slice attributes as a dictionary

Parameters:

skip (list) – list of keys to exclude

Returns:

slice attributes as dictionary

Return type:

dict

toJson()[source]

Returns the slice attributes as a json string

Returns:

slice attributes as json string

Return type:

str

update()[source]

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

Raises:

Exception – if updating topology fails

update_slice()[source]

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()[source]

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()[source]

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)[source]

Not intended as a API call.

Return type:

str

validate(raise_exception=True)[source]

Validate the slice w.r.t available resources before submission.

Fetches resources once and delegates to NodeValidator.validate_nodes() for batch validation.

Parameters:

raise_exception (bool) – raise exception if validation fails

Returns:

Tuple indicating status for validation and dictionary of the errors corresponding to each requested node

Return type:

Tuple[bool, Dict[str, str]]

wait(timeout=360, interval=10, progress=False)[source]

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=1800, interval=30, verbose=False, post_boot_config=True)[source]

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)

  • post_boot_config (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=1800, interval=20, progress=False)[source]

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:
Returns:

true when slice ssh successful

Return type:

bool