XTesting/powder-control/README.md

   1 # About
   2
   3 This project shows how to instantiate a Powder experiment
   4 programmatically via the Powder portal API.
   5
   6 In [powder/experiment.py](powder/experiment.py), there is a class
   7 `PowderExperiment`, which serves as the main abstraction for starting,
   8 interacting with, and terminating a single Powder experiment. It relies on
   9 [powder/rpc.py](powder/rpc.py) for interacting with the Powder RPC server
  10
  11 In [start-profile.py](start-profile.py), you can see how one might use it
  12 to instantiate a Powder experiment by specifying a given profile name
  13
  14 ## Getting Started
  15
  16 In order to run [start-profile.py](start-profile.py) or otherwise use the tools in this
  17 project, you'll need a Powder account to which you've added your public `ssh`
  18 key. If you haven't already done this, you can find instructions
  19 [here](https://docs.powderwireless.net/users.html#%28part._ssh-access%29).
  20 You'll also need to download your Powder credentials. You'll find a button to do
  21 so in the drop-down menu accessed by clicking on your username after logging
  22 into the Powder portal. This will download a file called `cloudlab.pem`, which
  23 you will need later.
  24
  25 Due to a copyleft license issue, it needs to pull code directly from the repo
  26 https://gitlab.flux.utah.edu/powder-profiles/powder-control and add the powder/rpc.py
  27 to the XTesting/powder-control/powder directory from the it/test repo.
  28
  29 You will need to make sure the machine you are using has `python3` installed, as well as
  30 the packages in [requirements.txt](requirements.txt). You can install the
  31 packages by doing
  32
  33 ```bash
  34 pip install -r requirements.txt
  35 ```
  36
  37 Whatever machine you are using to run [start-profile.py](start-profile.py), it will need a
  38 local copy of the `cloudlab.pem` file you downloaded earlier.
  39
  40 ### Running the Example
  41
  42 The RPC client that `PowderExperiment` relies on to interact with the Powder RPC
  43 server expects some environment variables to be set. If your private `ssh` key
  44 is encrypted, the key password needs to be set in an environment variable as
  45 well, unless you have already started `ssh-agent`.
  46
  47 If your ssh key is encrypted:
  48
  49 ```bash
  50 set +o history
  51 PROJECT=your_project_name PROFILE=your_profile_name \
  52 USER=your_powder_username PWORD=your_powder_password \
  53 CERT=/path/to/your/cloulab.pem KEYPWORD=your_ssh_key_password ./start-profile.py
  54 ```
  55
  56 If not:
  57
  58 ```bash
  59 set +o history
  60 PROJECT=your_project_name PROFILE=your_profile_name \
  61 USER=your_powder_username PWORD=your_powder_password \
  62 CERT=/path/to/your/cloulab.pem ./start-profile.py
  63 ```
  64
  65 The `set +o history` command will keep these passwords out of your `bash`
  66 history (assuming you're using `bash`). The PROJECT and PROFILE environment
  67 variables are optional, as by default it will use the 'osc' project which is
  68 dedicated to the OSC community usage, and 'ubuntu-20' profile for the widely
  69 used Ubuntu 20.04 image.
  70
  71 It can take more than 30 minutes for instantiating a profile provided to
  72 [start-profile.py](start-profile.py) to complete, but you'll see intermittent messages on
  73 `stdout` indicating progress and logging results. In some cases, the Powder
  74 resources required by [start-profile.py](start-profile.py) might not be available. If so,
  75 you'll see a log message that indicates as much and the script will exit; you
  76 can look at the [Resource Availability](https://www.powderwireless.net/resinfo.php)
  77 page on the Powder portal to see the status of the required instance. After
  78 completion, the script will exit with a message about failure/success.