Skip to content

Commit 1c3a071

Browse files
ccasconeccascone
committed
Add Docker-based tutorial infrastructure
Includes: - Main README - Makefile - Mininet topo and netcfg - App implementation (from srv6 tutorial) - Utility script to run P4Runtime shell via docker
1 parent f4a393b commit 1c3a071

23 files changed

+4375
-1
lines changed

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.idea/
2+
tmp/
3+
p4src/build
4+
app/target
5+
app/src/main/resources/p4info.txt
6+
app/src/main/resources/bmv2.json

‎Makefile‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
ONOS_IMG := onosproject/onos:2.2.0
2+
P4RT_SH_IMG := p4lang/p4runtime-sh:latest
3+
P4C_IMG := opennetworking/p4c:stable
4+
MN_STRATUM_IMG := opennetworking/mn-stratum:latest
5+
MAVEN_IMG := maven:3.6.1-jdk-11-slim
6+
7+
ONOS_SHA := sha256:c1d18e6957a785d0234855eb8c70909bfc68849338f0567e12a6ae7ce6f4ba91
8+
P4RT_SH_SHA := sha256:6ae50afb5bde620acb9473ce6cd7b990ff6cc63fe4113cf5584c8e38fe42176c
9+
P4C_SHA := sha256:8f9d27a6edf446c3801db621359fec5de993ebdebc6844d8b1292e369be5dfea
10+
MN_STRATUM_SHA := sha256:ae7c59885509ece8062e196e6a8fb6aa06386ba25df646ed27c765d92d131692
11+
MAVEN_SHA := sha256:ca67b12d638fe1b8492fa4633200b83b118f2db915c1f75baf3b0d2ef32d7263
12+
13+
mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
14+
curr_dir := $(patsubst %/,%,$(dir $(mkfile_path)))
15+
curr_dir_sha := $(shell echo -n "$(curr_dir)" | shasum | cut -c1-7)
16+
17+
app_build_container_name := app-build-${curr_dir_sha}
18+
onos_url := http://localhost:8181/onos
19+
onos_curl := curl --fail -sSL --user onos:rocks --noproxy localhost
20+
app_name := org.p4.srv6-tutorial
21+
22+
default:
23+
$(error Please specify a make target (see README.md))
24+
25+
_docker_pull_all:
26+
docker pull ${ONOS_IMG}@${ONOS_SHA}
27+
docker pull ${P4RT_SH_IMG}@${P4RT_SH_SHA}
28+
docker pull ${P4C_IMG}@${P4C_SHA}
29+
docker pull ${MN_STRATUM_IMG}@${MN_STRATUM_SHA}
30+
docker pull ${MAVEN_IMG}@${MAVEN_SHA}
31+
32+
# Pul lall Docker images and build app to seed mvn repo inside container, i.e.
33+
# download deps
34+
pull-deps: _docker_pull_all _create_mvn_container _mvn_package
35+
36+
start:
37+
docker-compose up -d
38+
39+
stop:
40+
docker-compose down -t0
41+
42+
restart: stop start
43+
44+
onos-cli:
45+
$(info *** Connecting to the ONOS CLI... password: rocks)
46+
$(info *** Top exit press ctrl+D)
47+
@ssh -o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" -o LogLevel=ERROR -p 8101 onos@localhost
48+
49+
onos-log:
50+
docker-compose logs -f onos
51+
52+
onos-ui:
53+
open ${onos_url}/ui
54+
55+
mn-cli:
56+
$(info *** Attaching to Mininet CLI...)
57+
$(info *** To detach press ctrl+P ctrl+Q (Mininet will keep running))
58+
-@docker attach $(shell docker-compose ps -q mininet) || echo "*** Detached from Mininet CLI"
59+
60+
mn-log:
61+
docker-compose logs -f mininet
62+
63+
netcfg:
64+
$(info *** Pushing netcfg.json to ONOS...)
65+
${onos_curl} -X POST -H 'Content-Type:application/json' \
66+
${onos_url}/v1/network/configuration -d@./mininet/netcfg.json
67+
@echo
68+
69+
reset: stop
70+
-rm -rf ./tmp
71+
72+
clean: reset
73+
-rm -rf p4src/build
74+
-rm -rf app/target
75+
-docker container rm ${app_build_container_name}
76+
77+
p4-build:
78+
$(info *** Building P4 program...)
79+
@mkdir -p p4src/build
80+
docker run --rm -v ${curr_dir}:${curr_dir} -w ${curr_dir} ${P4C_IMG} \
81+
p4c-bm2-ss --arch v1model -o p4src/build/bmv2.json \
82+
--p4runtime-files p4src/build/p4info.txt --Wdisable=unsupported \
83+
p4src/main.p4
84+
85+
_create_mvn_container:
86+
@if ! docker container ls -a --format '{{.Names}}' | grep -q ${app_build_container_name} ; then \
87+
docker create -v ${curr_dir}/app:/mvn-src -w /mvn-src --name ${app_build_container_name} ${MAVEN_IMG} mvn clean package; \
88+
fi
89+
90+
_copy_p4c_out:
91+
$(info *** Copying p4c outputs to app resources...)
92+
cp -f p4src/build/p4info.txt app/src/main/resources/
93+
cp -f p4src/build/bmv2.json app/src/main/resources/
94+
95+
_mvn_package:
96+
$(info *** Building ONOS app...)
97+
@docker start -a -i ${app_build_container_name}
98+
99+
app-build: p4-build _copy_p4c_out _create_mvn_container _mvn_package
100+
$(info *** ONOS app .oar package created succesfully)
101+
@ls -1 app/target/*.oar
102+
103+
app-install:
104+
$(info *** Installing and activating app in ONOS...)
105+
${onos_curl} -X POST -HContent-Type:application/octet-stream \
106+
'${onos_url}/v1/applications?activate=true' \
107+
--data-binary @app/target/srv6-tutorial-1.0-SNAPSHOT.oar
108+
@echo
109+
110+
app-uninstall:
111+
$(info *** Uninstalling app from ONOS...)
112+
-${onos_curl} -X DELETE ${onos_url}/v1/applications/${app_name}
113+
@echo
114+
115+
app-reload: app-uninstall app-install

‎README.md‎

Lines changed: 155 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,155 @@
1-
# ngsdn-tutorial
1+
# Next-Gen SDN Tutorial
2+
3+
Welcome to Next-Gen SDN tutorial!
4+
5+
This tutorial is targeted to developers who want to learn the basics of the
6+
building blocks of the NG-SDN architecture, such as:
7+
8+
* Data plane programming and control via P4 and P4Runtime
9+
* Configuration via OpenConfig and gNMI
10+
* Stratum
11+
* ONOS
12+
13+
The tutorial is organized around a sequence of hands-on exercises that show how
14+
to build an IPv6-based leaf-spine data center fabric.
15+
16+
## Slides
17+
18+
TODO
19+
20+
Tutorial slides are available [online](ADD SLIDES URL). These slides provide an
21+
introduction to each exercise. We suggest you look at it before starting to work
22+
on the exercises.
23+
24+
## Tutorial VM
25+
26+
TODO
27+
28+
To complete the exercises, you will need to download and run this tutorial VM
29+
(XX GB):
30+
* ADD LINK TO VM
31+
32+
To run the VM you can use any modern x86 virtualization system. The VM has been
33+
tested with VirtualBox v6.0.6. To download VirtualBox and import the VM use the
34+
following links:
35+
36+
* https://www.virtualbox.org/wiki/Downloads
37+
* https://docs.oracle.com/cd/E26217_01/E26796/html/qs-import-vm.html
38+
39+
### Recommended system requirements
40+
41+
The VM is configured with 4 GB of RAM and 4 CPU cores, while the disk has size
42+
of approx. 8 GB. These are the recommended minimum requirements to be able to
43+
run Ubuntu along with a Mininet network of 1-10 BMv2 devices controlled by 1
44+
ONOS instance. For a flawless experience, we recommend running the VM on a host
45+
system that has at least the double of resources.
46+
47+
### Use Docker instead of VM
48+
49+
TODO Add instructions to skip downloading the VM but use Docker instead.
50+
51+
### VM user credentials
52+
53+
Use the following credentials to log in the Ubuntu system:
54+
55+
* **Username:** `sdn`
56+
* **Password:** `rocks`
57+
58+
### Get this tutorial repo
59+
60+
To work on the exercises you will need to clone this repo inside the VM:
61+
62+
cd ~
63+
git clone https://github.com/opennetworkinglab/ngsdn-tutorial
64+
65+
If the `tutorial` directory is already present, make sure to update its
66+
content:
67+
68+
cd ~/ngsdn-tutorial
69+
git pull origin master
70+
71+
### Download / upgrade dependencies
72+
73+
The VM may have shipped with an older version of the dependencies than we would
74+
like to use for the exercises. You can upgrade to the latest version used for
75+
the tutorial using the following command:
76+
77+
cd ~/ngsdn-tutorial
78+
make pull-deps
79+
80+
This command will download all necessary dependencies from the Internet,
81+
allowing you to work off-line on the exercises. For this reason, we recommend
82+
running this step ahead of the tutorial with a reliable Internet connection.
83+
84+
85+
## Using an IDE to work on the exercises
86+
87+
During the exercises you will need to write code in multiple languages such as
88+
P4, Python and Java. While the exercises do not prescribe the use of any
89+
specific IDE or code editor, the tutorial VM comes with Java IDE [IntelliJ IDEA
90+
Community Edition](https://www.jetbrains.com/idea/), already pre-loaded with
91+
plugins for P4 syntax highlighting and Python development. We suggest using
92+
IntelliJ IDEA especially when working on the ONOS app, as it provides code
93+
completion for all ONOS APIs.
94+
95+
## Repo structure
96+
97+
FIXME
98+
99+
This repo is structured as follows:
100+
101+
* `p4src/` P4 implementation
102+
* `app/` ONOS app Java implementation
103+
* `mininet/` Mininet script to emulate a 2x2 leaf-spine fabric topology of
104+
`stratum_bmv2` devices
105+
* `util/` Utilities (such as p4runtime-sh)
106+
107+
## Tutorial commands
108+
109+
To facilitate working on the exercises, we provide a set of make-based commands
110+
to control the different aspects of the tutorial. Commands will be introduced in
111+
the exercises, here's a quick reference:
112+
113+
| Make command | Description |
114+
|---------------------|------------------------------------------------------- |
115+
| `make pull-deps` | Pull all required dependencies |
116+
| `make p4-build ` | Build the P4 program |
117+
| `make app-build ` | Build ONOS app |
118+
| `make start` | Start containers (`mininet` and `onos`) |
119+
| `make stop` | Stop and remove all containers |
120+
| `make onos-cli` | Access the ONOS CLI (password: `rocks`, Ctrl+D to exit)|
121+
| `make onos-ui` | Open the ONOS Web UI (user `onos` password `rocks`) |
122+
| `make mn-cli` | Access the Mininet CLI (Ctrl+P Ctrl+Q to exit) |
123+
| `make onos-log` | Show the ONOS log |
124+
| `make mn-log` | Show the Mininet log (i.e., the CLI output) |
125+
| `make netcfg` | Push netcfg.json file (network config) to ONOS |
126+
| `make app-reload` | Install and activate the ONOS app |
127+
| `make reset` | Reset the tutorial environment (to start from scratch) |
128+
129+
### P4Runtime shell
130+
131+
TODO add description
132+
133+
Usage:
134+
135+
```bash
136+
./util/p4rt-sh --grpc-addr localhost:50001 --config p4src/build/p4info.txt,p4src/build/bmv2.json
137+
```
138+
139+
## Exercises
140+
141+
Click on the exercise name to see the instructions:
142+
143+
1. [P4 and P4Runtime basics](./EXERCISE-1.md)
144+
2. [OpenConfig and gNMI Basic](./EXERCISE-2.md)
145+
3. [Running ONOS](./EXERCISE-3.md)
146+
4. [Modify ONOS app](./EXERCISE-4.md)
147+
148+
## Solutions
149+
150+
TODO do we really need this?
151+
152+
You can find solutions for each exercise in the [solution](solution) directory.
153+
Feel free to compare your implementation to the reference one whenever you feel
154+
stuck. To use the solution code that is provided, simply use the same **make**
155+
commands in the solution directory.

0 commit comments

Comments
 (0)