Commit 4fe44e97 authored by Ryan Goodfellow's avatar Ryan Goodfellow
Browse files

initial cut at e2e docs

Signed-off-by: Ryan Goodfellow's avatarRyan Goodfellow <>
parent a33db3cd
title: "End to End Tour"
linkTitle: "End to End Tour"
weight: 1
description: >
A guided tour of everything involved in creating, realizing and
materializing an experiment on Merge.
## Core Concepts
To get a sense for how Merge works, and in particular how experiments are
defined, realized and materialized, we need to go over a few core architectural
features of Merge that are pervasive throughout the platform.
### Model Driven Design
At the end of the day Merge is all about models. When a resource provider
commissions a new testbed facility, they do that by providing a _model_ of the
facility to a Merge portal. When a user creates a new revision of an experiment,
they do so by pushing a commit of their experiment model to a Git repository
that is tracked by a Merge portal. When a user goes to realize an experiment,
the Merge portal takes their experiment model, takes all the models it has of
registered testbed facilities and creates an aggregate interconnected testbed
model called the _resource internet_ and then computes an embedding of the users
experiment model onto the resource internet model.
### Reconcilers
Both the Merge portal and the Mars testbed kernel are built around a reconciler
architecture. Both have well defined API and an API server. When requests are
made to the API, the API server translates a request into desired state. For
both the Portal and Mars there are a collection of reconcilers running that
monitor desired state, and drive actual state toward the target state. As a
concrete example every Merge experiment comes with a Git repository. When a user
creates a new experiment through the CLI, the `mrg` CLI tool calls the Merge
Portal API which is implemented by the portal API server. The API server
translates that new experiment request into a set of desired states. One piece
of state in that set is having a Git repository associated with the new
experiment. The API server places the parameters of that Git repository in the
Portal's etcd data store. The Git reconciler running in the portal is monitoring
etcd for state updates pertaining to Git repos. When it sees this new state it
ensures that the Git repo is present and ready to go for that users experiment.
The same process happens when an experiment is deleted, except the Git
reconciler is now observing the removal of a target state and thus removes the
associated Git repository.
## Setting Up A Testing Environment
There are two major systems to set up for running an end to end test.
1. A Merge Portal appliance.
2. A virtual Merge testbed running Mars. In this tutorial we'll be using the
Phobos virtual testbed environment.
### Portal Appliance
The Portal appliance is a libvirt packaged virtual machine with a pre-installed
Merge portal system. It can be stood up as follows
curl -L | bash
More detailed instructions on the use and operation of the Merge portal
appliance are available
### Phobos
Instructions for setting up and running Phobos are
Follow them through the `mrs list net` point.
### Interconnection
Once the Appliance and Phobos are up, we need to make sure they can talk to each
other from the host machine.
Setup your local firewall rules to allow the Appliance and Phobos to talk
1. Lookup what interface phobos is on
virsh net-list
Locate the entry with the form `phobos_<n>_raven-infra` where `<n>` is an
integer. Display that network
virsh net-dumpxml phobos_<d>_raven-infra
this will contain an entry that looks like this
<bridge name='virbr<m>' stp='on' delay='0'/>
where `<m>` is an integer.
2. Add iptables forwarding rules.
sudo iptables -I FORWARD -o tt0 -i virbr<m> -j ACCEPT
sudo iptables -I FORWARD -i tt0 -o virbr<m> -j ACCEPT
3. Add a /etc/hosts entry on your local workstation
Look up the 172.22.x.x address on the `ops` host and add it to your workstation
`/etc/hosts` as follows.
## Testing
Now that we have a Merge portal and Mars-based facility running virtually on our
workstation, we can begin doing things through the Merge API using the `mrg`
command line tool.
First setup your `mrg` client to point at your Portal appliance
mrg config set server
Login using the credentials from the configuration that came with the appliance.
pw=`cat portal-genconf* | grep opspw | awk '{print $2}'`
mrg login ops $pw --nokeys
### Facility commissioning
Create a user and initialize a user that represents a testbed operator.
mrg logout
mrg register olive muffins1701
mrg login ops $pw --nokeys
mrg init olive
mrg active olive
mrg logout
Login as the testbed operator and commission the Phobos testbed facility.
mrg login olive muffins1701
curl -OL
mrg new fac phobos phobos.xir
mrg logout
### Experimentation
Create a user and initialize a user that represents a testbed user.
mrg logout
mrg register murphy muffins1701
mrg login ops $pw --nokeys
mrg init murphy
mrg active murphy
mrg logout
Login as the testbed user and follow the
[hello world](/docs/experimentation/hello-world)
Modify the experiment source to use bare-metal resources.
from mergexp import *
# Create a netwok topology object.
net = Network('hello-world')
# Create two nodes.
a,b = [net.node(name, metal == True) for name in ['a', 'b']]
# Create a link connecting the two nodes.
link = net.connect([a,b])
# Give IP addresses to the nodes on the link just created.
link[a].socket.addrs = ip4('')
link[b].socket.addrs = ip4('')
# Make this file a runnable experiment based on our two node topology.
Push an update to the experiment git repo, relinquish (`mrg relinquish` from the
CLI) the current realization and create a new one.
Now it's time to materialize
mrg materialize world.hello.murphy
This will kick off a materialization on the Phobos site. If you open up a
console to the Raven virtual machines that have been allocated by the
realization engine (`x0` and `x1` usually chosen in my experience) using the
`virt-manager` tool available on fedora, you will see that these nodes have been
rebooted and they will go through the imaging process.
Once the nodes come up in the default Debian based operating system, you can
login with the credentials user=test password=test. You can then setup addresses
on the experiment interfaces of the nodes and the should be able to ping each
other. At the time of writing the system that configures the nodes called
Foundry is not yet fully integrated, so things like user accounts and automatic
experiment network setup for things like addresses and routes is not there yet.
title: "Facility Architecture"
linkTitle: "Facility Architecture"
weight: 1
weight: 2
description: >
The Merge testbed facility architecture
title: "Portal Architecture"
linkTitle: "Portal Architecture"
weight: 2
weight: 3
description: >
The Merge portal architecture
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment