From f04010b9d937a8914c528ae918b26b9036c8cd31 Mon Sep 17 00:00:00 2001 From: wtj Date: Thu, 27 Jul 2023 10:22:41 +0800 Subject: [PATCH 1/4] docs: add CloudLab getting started guide --- docs/cloudlab.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/cloudlab.md diff --git a/docs/cloudlab.md b/docs/cloudlab.md new file mode 100644 index 0000000000..2953f888cc --- /dev/null +++ b/docs/cloudlab.md @@ -0,0 +1,73 @@ +# CloudLab getting started guide + +## Create CloudLab experiments + +First, submit an account request to CloudLab (https://www.cloudlab.us/). Things to note: + +- Select "Join Existing Project" and type: `Sieve-Acto` +- The username and key you provide will be used for SSH login + +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). + +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**. + +Launch an experiment via the web dashboard: + +1. Click "Experiments" -- "Start Experiment". The default selected profile should be `small-lan`. "Next". +2. Enter/Choose parameters: + - "Select OS image": `UBUNTU 20.04` + - "Optional physical node type": `c6420` + - Leave other parameters as default. (Especially those regarding temporary filesystem -- we'll deal with it after provisioning using Ansible.) +3. "Next". Give your experiment a name. "Next". "Next". + +Wait for the provisioning to finish. The web dashboard will show you the server address, in the form of `clnodeXXX.clemson.cloudlab.us`. + +## Configure CloudLab machines + +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.) + +**On your local machine**: + +```shell +# +# Install Ansible +# + +# A Python virtual environment is encouraged, which is not detailed here though. +pip3 install ansible +ansible-galaxy collection install ansible.posix +ansible-galaxy collection install community.general + +# +# Checkout the repository +# + +cd ~ +git clone https://github.com/xlab-uiuc/acto.git +cd acto/ + +# +# Prepare the CloudLab machine(s) with Ansible +# + +cd scripts/ansible/ +# TODO: replace the placeholders with your real domain and user name you +# obtained or submitted in the previous section +domain="clnodeXXX.clemson.cloudlab.us" +user="alice" +echo "$domain ansible_connection=ssh ansible_user=$user ansible_port=22" > ansible_hosts +ansible-playbook -i ansible_hosts configure.yaml +``` + +## Run Acto + +Login onto **the CloudLab machine**, and run: + +```shell +cd ~/acto +pip install -r requirements.txt # FIXME: see #247 +make +python3 -m acto.reproduce \ + --reproduce-dir test/cassop-330/trial-demo \ + --config data/cass-operator/config.json +``` From 3aad0a658afd008354dd0350c356ed3dfa67cf00 Mon Sep 17 00:00:00 2001 From: wtj Date: Thu, 27 Jul 2023 10:22:41 +0800 Subject: [PATCH 2/4] docs: make instructions for Ansible consistent here and there --- scripts/ansible/README.md | 17 +++++++++++------ scripts/ansible/configure.sh | 13 ------------- 2 files changed, 11 insertions(+), 19 deletions(-) delete mode 100644 scripts/ansible/configure.sh diff --git a/scripts/ansible/README.md b/scripts/ansible/README.md index 78a9d218d8..649de815e6 100644 --- a/scripts/ansible/README.md +++ b/scripts/ansible/README.md @@ -1,23 +1,28 @@ -# Ansible playbook to automatically configure environment for Acto to run a baremetal machine +# Ansible playbook to automatically configure environment for Acto to run on a baremetal machine + To run the script, you first need an `ansible_hosts` file. Each line in the file should contain a worker in your cluster. See https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html for details. An example: + ```ini c220g5-110417.wisc.cloudlab.us ansible_connection=ssh ansible_user=tylergu ansible_port=22 c220g5-110418.wisc.cloudlab.us ansible_connection=ssh ansible_user=tylergu ansible_port=22 ``` -If you haven't installed `ansible playbook` on your control node, run +If you haven't installed `ansible-playbook` on your control node, run + ```sh pip3 install ansible ansible-galaxy collection install ansible.posix ansible-galaxy collection install community.general -``` - -Then just run ``` -bash configure.sh + +Then just run + +```sh +ansible-playbook -i ansible_hosts configure.yaml ``` + and the proper environment will be setup on the workers. diff --git a/scripts/ansible/configure.sh b/scripts/ansible/configure.sh deleted file mode 100644 index 64fff0438d..0000000000 --- a/scripts/ansible/configure.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/bin/bash -ansible-playbook tmpfs.yaml -i ansible_hosts -ansible-playbook go.yaml -i ansible_hosts -ansible-playbook docker.yaml -i ansible_hosts -ansible-playbook python.yaml -i ansible_hosts -ansible-playbook kind.yaml -i ansible_hosts -ansible-playbook kubectl.yaml -i ansible_hosts -ansible-playbook helm.yaml -i ansible_hosts -ansible-playbook sysctl.yaml -i ansible_hosts -ansible-playbook k3d.yaml -i ansible_hosts -ansible-playbook k9s.yaml -i ansible_hosts -ansible-playbook htop.yaml -i ansible_hosts -ansible-playbook acto.yaml -i ansible_hosts From cd14af35b2f1ea3643661760439b7fd498e15245 Mon Sep 17 00:00:00 2001 From: wtj Date: Thu, 27 Jul 2023 10:22:41 +0800 Subject: [PATCH 3/4] docs: install Ansible with apt --- docs/cloudlab.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/cloudlab.md b/docs/cloudlab.md index 2953f888cc..dda2c8c7d4 100644 --- a/docs/cloudlab.md +++ b/docs/cloudlab.md @@ -33,8 +33,10 @@ We are going to manage CloudLab machines with Ansible **from our local machine** # Install Ansible # -# A Python virtual environment is encouraged, which is not detailed here though. -pip3 install ansible +sudo apt update +sudo apt install software-properties-common +sudo add-apt-repository --yes --update ppa:ansible/ansible +sudo apt install ansible ansible-galaxy collection install ansible.posix ansible-galaxy collection install community.general From 6491920adfe2c9d176f6ad0f2e5ecf075d8b1287 Mon Sep 17 00:00:00 2001 From: ZHANG Wentao Date: Thu, 3 Aug 2023 17:31:21 +0800 Subject: [PATCH 4/4] docs: update cloudlab.md to reflect recent changes elsewhere --- docs/cloudlab.md | 120 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 86 insertions(+), 34 deletions(-) diff --git a/docs/cloudlab.md b/docs/cloudlab.md index dda2c8c7d4..1c516e4057 100644 --- a/docs/cloudlab.md +++ b/docs/cloudlab.md @@ -1,15 +1,23 @@ # CloudLab getting started guide -## Create CloudLab experiments +## 1 Prerequisites First, submit an account request to CloudLab (https://www.cloudlab.us/). Things to note: -- Select "Join Existing Project" and type: `Sieve-Acto` +- 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. - The username and key you provide will be used for SSH login 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). -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**. +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**. + +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). + +## 2 Manually set up the dependencies + +
Click to show details + +### 2.1 Create CloudLab experiments Launch an experiment via the web dashboard: @@ -17,59 +25,103 @@ Launch an experiment via the web dashboard: 2. Enter/Choose parameters: - "Select OS image": `UBUNTU 20.04` - "Optional physical node type": `c6420` - - Leave other parameters as default. (Especially those regarding temporary filesystem -- we'll deal with it after provisioning using Ansible.) -3. "Next". Give your experiment a name. "Next". "Next". + - Leave other parameters as default. (Especially those regarding temporary filesystem -- this will be handled after provisioning using Ansible.) +3. "Next". Give your experiment a name. "Next". "Finish". -Wait for the provisioning to finish. The web dashboard will show you the server address, in the form of `clnodeXXX.clemson.cloudlab.us`. +Wait for the provisioning to finish. The web dashboard will show you the server address, in the form of `..cloudlab.us`. E.g. `clnode123.clemson.cloudlab.us`. -## Configure CloudLab machines +### 2.2 Install the dependencies with Ansible -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.) +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. -**On your local machine**: +**On your controller node**: -```shell -# -# Install Ansible -# +Install Ansible: +```shell sudo apt update -sudo apt install software-properties-common +sudo apt -y install software-properties-common sudo add-apt-repository --yes --update ppa:ansible/ansible -sudo apt install ansible +sudo apt -y install ansible ansible-galaxy collection install ansible.posix ansible-galaxy collection install community.general +``` -# -# Checkout the repository -# +Clone the Ansible scripts: -cd ~ -git clone https://github.com/xlab-uiuc/acto.git -cd acto/ +```shell +git clone https://github.com/xlab-uiuc/acto-cloudlab.git /tmp/acto-cloudlab +``` -# -# Prepare the CloudLab machine(s) with Ansible -# +Set up `ansible_hosts` file (**remember to replace the placeholders with your real domain and user name**): -cd scripts/ansible/ -# TODO: replace the placeholders with your real domain and user name you -# obtained or submitted in the previous section +```shell domain="clnodeXXX.clemson.cloudlab.us" user="alice" + +cd /tmp/acto-cloudlab/scripts/ansible/ echo "$domain ansible_connection=ssh ansible_user=$user ansible_port=22" > ansible_hosts +``` + +> If the controller is a CloudLab machine too, this step can be automated: +> +> ```shell +> sudo apt -y install xmlstarlet +> +> component_name=$( geni-get portalmanifest | xmlstarlet sel -N x="http://www.geni.net/resources/rspec/3" -t -v "//x:node/@component_id" ) +> cluster_domain=$( echo $component_name | cut -d '+' -f 2 ) +> node_subdomain=$( echo $component_name | cut -d '+' -f 4 ) +> domain="${node_subdomain}.${cluster_domain}" +> user=$( geni-get user_urn | rev | cut -d '+' -f -1 | rev ) +> +> cd /tmp/acto-cloudlab/scripts/ansible/ +> echo "$domain ansible_connection=ssh ansible_user=$user ansible_port=22" > ansible_hosts +> ``` +> +> Or even simpler, use `127.0.0.1` directly: +> +> ```shell +> cd /tmp/acto-cloudlab/scripts/ansible/ +> echo 127.0.0.1 > ansible_hosts +> ``` + +(Only if the controller is a CloudLab machine too) work around the key authentication: + +```shell +ssh-keygen -b 2048 -t rsa -f ~/.ssh/id_rsa -q -N "" && cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys +``` + +Finally, run the Ansible scripts to install dependencies: + +```shell ansible-playbook -i ansible_hosts configure.yaml ``` -## Run Acto +
+ +(Only if the controller is a CloudLab machine too) log out before jumping to section 4 and logging in again. + +Go to [section 4](#4-run-acto). + +## 3 Automatically set up the dependencies + +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. + +Launch an experiment via the web dashboard: + +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". +2. "Next". Give your experiment a name. "Next". "Finish". + +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 `..cloudlab.us`. E.g. `clnode123.clemson.cloudlab.us`. + +## 4 Run Acto + +Log in to the CloudLab machine, and run: -Login onto **the CloudLab machine**, and run: + ```shell -cd ~/acto -pip install -r requirements.txt # FIXME: see #247 +cd ~/workdir/acto make -python3 -m acto.reproduce \ - --reproduce-dir test/cassop-330/trial-demo \ - --config data/cass-operator/config.json +python3 reproduce_bugs.py --bug-id rdoptwo-287 ```