Welcome to fabrictestbed-extensions documentation!#

fabrictestbed-extensions, otherwise known as “FABlib”, is an implementation of a Python API for interacting with FABRIC testbed. You would typically call FABlib APIs from your Jupyter notebooks or from your Python code. FABRIC project runs an instance of JupyterHub at https://jupyter.fabric-testbed.net.

If you are new to FABRIC, it would be helpful to begin by reading the articles at https://learn.fabric-testbed.net. If you have questions or run into trouble, you can discuss them at FABRIC forums: https://learn.fabric-testbed.net/forums/.

Installing FABlib#

You can install released versions of FABlib from PyPI:

$ pip install fabrictestbed-extensions

If you need the current development version of FABlib, install it from the git repository:

$ pip install git+https://github.com/fabric-testbed/fabrictestbed-extensions@main

Installing FABlib will also install a number of dependencies, so you might want to install FABlib in a virtual environment.

FABlib’s “hello world”#

Here’s a quick example of some code that uses FABlib:

from fabrictestbed_extensions.fablib.fablib import FablibManager

try:
    fablib = FablibManager()
    fablib.show_config()
except Exception as e:
    print(f"Exception: {e}")

However, please note that the above example will not work out of the box. Some configuration is required for the code above to work as expected. Configuration can come from either environment variables or from a file, usually placed at ~/work/fabric_config/fabric_rc.

More examples of FABlib usage can be found in the notebooks available at FABRIC project’s JupyterLab instance, which are also maintained at https://github.com/fabric-testbed/jupyter-examples.

Configuring FABlib#

In order to interact with FABRIC testbed, FABlib will need to know these things:

  • FABRIC orchestrator host’s address

  • FABRIC credential manager host’s address

  • FABRIC bastion host’s address

  • Your FABRIC project ID

  • Path to your FABRIC token

  • Your username for FABRIC bastion host

  • Your ssh private key to use with FABRIC bastion host

  • Your ssh public and private keys to use with FABRIC slices

  • And, optionally, the passphrases to the private keys

In FABRIC project’s JupyterLab, this configuration is usually done by running a “Configure your Jupyter Environment” notebook that you will need to run, when you sign in there for the first time.

If you are running code in another machine, you must set some environment variables, like so:

export FABRIC_CREDMGR_HOST=cm.fabric-testbed.net
export FABRIC_ORCHESTRATOR_HOST=orchestrator.fabric-testbed.net

# Find your real project ID from FABRIC portal: https://portal.fabric-testbed.net/.
export FABRIC_PROJECT_ID=a429da84-20cd-449d-bcb6-5e2c4ac269c0

# Download FABRIC token from FABRIC credential manager: https://cm.fabric-testbed.net/.
export FABRIC_TOKEN_LOCATION=/path/to/token.json

export FABRIC_BASTION_HOST=bastion.fabric-testbed.net
# Find your real FABRIC bastion host username at https://portal.fabric-testbed.net/user.
export FABRIC_BASTION_USERNAME=you_0000010534

export FABRIC_BASTION_KEY_LOCATION=/home/fabric/work/fabric_config/fabric_bastion_key
# If your bastion private key is protected, export its passphrase.
export FABRIC_BASTION_KEY_PASSPHRASE=s00p3rs3kr3t

export FABRIC_SLICE_PRIVATE_KEY_FILE=/home/fabric/work/fabric_config/slice_key
export FABRIC_SLICE_PUBLIC_KEY_FILE=/home/fabric/work/fabric_config/slice_key.pub
export FABRIC_SLICE_PRIVATE_KEY_PASSPHRASE=maj0rs3kr3t

The fabric_rc configuration file also follows the same format as above. Currently, contents of the configuration file will override values set using environment variables.

FABLib classes#

Most of FABLib’s functionality comes wrapped in these classes:

Indices and tables#