Skip to content

Commit ffe0371

Browse files
whentojumpwhentojump
authored
Add Cloudlab docs (#250)
* docs: add CloudLab getting started guide * docs: make instructions for Ansible consistent here and there * docs: install Ansible with apt * docs: update cloudlab.md to reflect recent changes elsewhere
1 parent 142995f commit ffe0371

File tree

3 files changed

+138
-19
lines changed

3 files changed

+138
-19
lines changed

‎docs/cloudlab.md

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# CloudLab getting started guide
2+
3+
## 1 Prerequisites
4+
5+
First, submit an account request to CloudLab (https://www.cloudlab.us/). Things to note:
6+
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.
8+
- The username and key you provide will be used for SSH login
9+
10+
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).
11+
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
21+
22+
Launch an experiment via the web dashboard:
23+
24+
1. Click "Experiments" -- "Start Experiment". The default selected profile should be `small-lan`. "Next".
25+
2. Enter/Choose parameters:
26+
- "Select OS image": `UBUNTU 20.04`
27+
- "Optional physical node type": `c6420`
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".
30+
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`.
32+
33+
### 2.2 Install the dependencies with Ansible
34+
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.
36+
37+
**On your controller node**:
38+
39+
Install Ansible:
40+
41+
```shell
42+
sudo apt update
43+
sudo apt -y install software-properties-common
44+
sudo add-apt-repository --yes --update ppa:ansible/ansible
45+
sudo apt -y install ansible
46+
ansible-galaxy collection install ansible.posix
47+
ansible-galaxy collection install community.general
48+
```
49+
50+
Clone the Ansible scripts:
51+
52+
```shell
53+
git clone https://github.com/xlab-uiuc/acto-cloudlab.git /tmp/acto-cloudlab
54+
```
55+
56+
Set up `ansible_hosts` file (**remember to replace the placeholders with your real domain and user name**):
57+
58+
```shell
59+
domain="clnodeXXX.clemson.cloudlab.us"
60+
user="alice"
61+
62+
cd /tmp/acto-cloudlab/scripts/ansible/
63+
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
97+
ansible-playbook -i ansible_hosts configure.yaml
98+
```
99+
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:
120+
121+
<!-- TODO this is now sosp-ae because of Ansible scripts in acto-cloudlab -->
122+
123+
```shell
124+
cd ~/workdir/acto
125+
make
126+
python3 reproduce_bugs.py --bug-id rdoptwo-287
127+
```

‎scripts/ansible/README.md

+11-6
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,28 @@
1-
# Ansible playbook to automatically configure environment for Acto to run a baremetal machine
1+
# Ansible playbook to automatically configure environment for Acto to run on a baremetal machine
2+
23
To run the script, you first need an `ansible_hosts` file. Each line in the file should contain
34
a worker in your cluster. See https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
45
for details.
56

67
An example:
8+
79
```ini
810
c220g5-110417.wisc.cloudlab.us ansible_connection=ssh ansible_user=tylergu ansible_port=22
911
c220g5-110418.wisc.cloudlab.us ansible_connection=ssh ansible_user=tylergu ansible_port=22
1012
```
1113

12-
If you haven't installed `ansible playbook` on your control node, run
14+
If you haven't installed `ansible-playbook` on your control node, run
15+
1316
```sh
1417
pip3 install ansible
1518
ansible-galaxy collection install ansible.posix
1619
ansible-galaxy collection install community.general
17-
```
18-
19-
Then just run
2020
```
21-
bash configure.sh
21+
22+
Then just run
23+
24+
```sh
25+
ansible-playbook -i ansible_hosts configure.yaml
2226
```
27+
2328
and the proper environment will be setup on the workers.

‎scripts/ansible/configure.sh

-13
This file was deleted.

0 commit comments

Comments
 (0)