This project shows how to instantiate a Powder experiment programmatically via the Powder portal API.
In powder/experiment.py, there is a class PowderExperiment, which serves as the main abstraction for starting, interacting with, and terminating a single Powder experiment. It relies on powder/rpc.py for interacting with the Powder RPC server
In start-profile.py, you can see how one might use it to instantiate a Powder experiment by specifying a given profile name
In order to run start-profile.py or otherwise use the tools in this project, you'll need a Powder account to which you've added your public ssh key. If you haven't already done this, you can find instructions here. You'll also need to download your Powder credentials. You'll find a button to do so in the drop-down menu accessed by clicking on your username after logging into the Powder portal. This will download a file called cloudlab.pem, which you will need later.
Due to a copyleft license issue, it needs to pull code directly from the repo https://gitlab.flux.utah.edu/powder-profiles/powder-control and add the powder/rpc.py to the XTesting/powder-control/powder directory from the it/test repo.
You will need to make sure the machine you are using has python3 installed, as well as the packages in requirements.txt. You can install the packages by doing
pip install -r requirements.txt
Whatever machine you are using to run start-profile.py, it will need a local copy of the cloudlab.pem file you downloaded earlier.
The RPC client that PowderExperiment relies on to interact with the Powder RPC server expects some environment variables to be set. If your private ssh key is encrypted, the key password needs to be set in an environment variable as well, unless you have already started ssh-agent.
If your ssh key is encrypted:
set +o history PROJECT=your_project_name PROFILE=your_profile_name \ USER=your_powder_username PWORD=your_powder_password \ CERT=/path/to/your/cloulab.pem KEYPWORD=your_ssh_key_password ./start-profile.py
If not:
set +o history PROJECT=your_project_name PROFILE=your_profile_name \ USER=your_powder_username PWORD=your_powder_password \ CERT=/path/to/your/cloulab.pem ./start-profile.py
The set +o history command will keep these passwords out of your bash history (assuming you're using bash). The PROJECT and PROFILE environment variables are optional, as by default it will use the 'osc' project which is dedicated to the OSC community usage, and 'ubuntu-20' profile for the widely used Ubuntu 20.04 image.
It can take more than 30 minutes for instantiating a profile provided to start-profile.py to complete, but you'll see intermittent messages on stdout indicating progress and logging results. In some cases, the Powder resources required by start-profile.py might not be available. If so, you'll see a log message that indicates as much and the script will exit; you can look at the Resource Availability page on the Powder portal to see the status of the required instance. After completion, the script will exit with a message about failure/success.