Skip to content

Commit 6491920

Browse files
whentojumpwhentojump
committed
docs: update cloudlab.md to reflect recent changes elsewhere
1 parent cd14af3 commit 6491920

File tree

1 file changed

+86
-34
lines changed

1 file changed

+86
-34
lines changed

‎docs/cloudlab.md

+86-34
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,127 @@
11
# CloudLab getting started guide
22

3-
## Create CloudLab experiments
3+
## 1 Prerequisites
44

55
First, submit an account request to CloudLab (https://www.cloudlab.us/). Things to note:
66

7-
- Select "Join Existing Project" and type: `Sieve-Acto`
7+
- If you're an internal member, select "Join Existing Project" and type: `Sieve-Acto`. Otherwise, you'll have to join other existing projects or create a new one, which is not detailed here.
88
- The username and key you provide will be used for SSH login
99

1010
Wait for the admin to approve your account. Once you are able to login, familiarize yourself with the web-based dashboard, and [the concept of *profiles* and *experiments*](https://docs.cloudlab.us/basic-concepts.html).
1111

12-
Although you should be able to login onto any machine instantiated by your project collaborators (i.e. a Linux user will be automatically created for you on every machine with `authorized_keys` set up), our current practice is to let everyone run code **on their own experiments**.
12+
Although you should be able to log in to any machine instantiated by your project collaborators (i.e. a Linux user will be automatically created for you on every machine with `authorized_keys` set up), for us (`Sieve-Acto`), the current practice is to let everyone run code **on their own experiments**.
13+
14+
Next you'll prepare the dependencies either manually ([section 2](#2-manually-set-up-the-dependencies)) or automatically ([section 3](#3-automatically-set-up-the-dependencies), recommended).
15+
16+
## 2 Manually set up the dependencies
17+
18+
<details><summary>Click to show details</summary>
19+
20+
### 2.1 Create CloudLab experiments
1321

1422
Launch an experiment via the web dashboard:
1523

1624
1. Click "Experiments" -- "Start Experiment". The default selected profile should be `small-lan`. "Next".
1725
2. Enter/Choose parameters:
1826
- "Select OS image": `UBUNTU 20.04`
1927
- "Optional physical node type": `c6420`
20-
- Leave other parameters as default. (Especially those regarding temporary filesystem -- we'll deal with it after provisioning using Ansible.)
21-
3. "Next". Give your experiment a name. "Next". "Next".
28+
- Leave other parameters as default. (Especially those regarding temporary filesystem -- this will be handled after provisioning using Ansible.)
29+
3. "Next". Give your experiment a name. "Next". "Finish".
2230

23-
Wait for the provisioning to finish. The web dashboard will show you the server address, in the form of `clnodeXXX.clemson.cloudlab.us`.
31+
Wait for the provisioning to finish. The web dashboard will show you the server address, in the form of `<node>.<cluster>.cloudlab.us`. E.g. `clnode123.clemson.cloudlab.us`.
2432

25-
## Configure CloudLab machines
33+
### 2.2 Install the dependencies with Ansible
2634

27-
We are going to manage CloudLab machines with Ansible **from our local machine**. (Ideally this "local machine" can be a CloudLab one too. However, the scripts were not designed to do so and may mess things up. For the time being, minor tweaks are needed in order to let them function properly in such cases.)
35+
You are going to manage CloudLab machines with Ansible from a controller node. This "controller" can be your local machine, or one of the CloudLab machines themselves.
2836

29-
**On your local machine**:
37+
**On your controller node**:
3038

31-
```shell
32-
#
33-
# Install Ansible
34-
#
39+
Install Ansible:
3540

41+
```shell
3642
sudo apt update
37-
sudo apt install software-properties-common
43+
sudo apt -y install software-properties-common
3844
sudo add-apt-repository --yes --update ppa:ansible/ansible
39-
sudo apt install ansible
45+
sudo apt -y install ansible
4046
ansible-galaxy collection install ansible.posix
4147
ansible-galaxy collection install community.general
48+
```
4249

43-
#
44-
# Checkout the repository
45-
#
50+
Clone the Ansible scripts:
4651

47-
cd ~
48-
git clone https://github.com/xlab-uiuc/acto.git
49-
cd acto/
52+
```shell
53+
git clone https://github.com/xlab-uiuc/acto-cloudlab.git /tmp/acto-cloudlab
54+
```
5055

51-
#
52-
# Prepare the CloudLab machine(s) with Ansible
53-
#
56+
Set up `ansible_hosts` file (**remember to replace the placeholders with your real domain and user name**):
5457

55-
cd scripts/ansible/
56-
# TODO: replace the placeholders with your real domain and user name you
57-
# obtained or submitted in the previous section
58+
```shell
5859
domain="clnodeXXX.clemson.cloudlab.us"
5960
user="alice"
61+
62+
cd /tmp/acto-cloudlab/scripts/ansible/
6063
echo "$domain ansible_connection=ssh ansible_user=$user ansible_port=22" > ansible_hosts
64+
```
65+
66+
> If the controller is a CloudLab machine too, this step can be automated:
67+
>
68+
> ```shell
69+
> sudo apt -y install xmlstarlet
70+
>
71+
> component_name=$( geni-get portalmanifest | xmlstarlet sel -N x="http://www.geni.net/resources/rspec/3" -t -v "//x:node/@component_id" )
72+
> cluster_domain=$( echo $component_name | cut -d '+' -f 2 )
73+
> node_subdomain=$( echo $component_name | cut -d '+' -f 4 )
74+
> domain="${node_subdomain}.${cluster_domain}"
75+
> user=$( geni-get user_urn | rev | cut -d '+' -f -1 | rev )
76+
>
77+
> cd /tmp/acto-cloudlab/scripts/ansible/
78+
> echo "$domain ansible_connection=ssh ansible_user=$user ansible_port=22" > ansible_hosts
79+
> ```
80+
>
81+
> Or even simpler, use `127.0.0.1` directly:
82+
>
83+
> ```shell
84+
> cd /tmp/acto-cloudlab/scripts/ansible/
85+
> echo 127.0.0.1 > ansible_hosts
86+
> ```
87+
88+
(Only if the controller is a CloudLab machine too) work around the key authentication:
89+
90+
```shell
91+
ssh-keygen -b 2048 -t rsa -f ~/.ssh/id_rsa -q -N "" && cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
92+
```
93+
94+
Finally, run the Ansible scripts to install dependencies:
95+
96+
```shell
6197
ansible-playbook -i ansible_hosts configure.yaml
6298
```
6399
64-
## Run Acto
100+
</details>
101+
102+
(Only if the controller is a CloudLab machine too) log out before jumping to section 4 and logging in again.
103+
104+
Go to [section 4](#4-run-acto).
105+
106+
## 3 Automatically set up the dependencies
107+
108+
Everything needed to install the dependencies (see section 2) is included in [a CloudLab profile](https://github.com/xlab-uiuc/acto-cloudlab), by which the same environment can be set up without manually entering any command.
109+
110+
Launch an experiment via the web dashboard:
111+
112+
1. Open this link: https://www.cloudlab.us/p/Sieve-Acto/acto-cloudlab?refspec=refs/heads/main. The default selected profile should be `acto-cloudlab`. "Next".
113+
2. "Next". Give your experiment a name. "Next". "Finish".
114+
115+
Wait for provisioning and startup both to finish (i.e. under the "List View" tab, "Status" is `ready` and "Startup" is `Finished`). The web dashboard will show you the server address, in the form of `<node>.<cluster>.cloudlab.us`. E.g. `clnode123.clemson.cloudlab.us`.
116+
117+
## 4 Run Acto
118+
119+
Log in to the CloudLab machine, and run:
65120
66-
Login onto **the CloudLab machine**, and run:
121+
<!-- TODO this is now sosp-ae because of Ansible scripts in acto-cloudlab -->
67122
68123
```shell
69-
cd ~/acto
70-
pip install -r requirements.txt # FIXME: see #247
124+
cd ~/workdir/acto
71125
make
72-
python3 -m acto.reproduce \
73-
--reproduce-dir test/cassop-330/trial-demo \
74-
--config data/cass-operator/config.json
126+
python3 reproduce_bugs.py --bug-id rdoptwo-287
75127
```

0 commit comments

Comments
 (0)