This tutorial guide walks through the steps to bring up a demonstration CORD "POD", running in virtual machines on a single physical server. The purpose of this demonstration POD is to enable those interested in understanding how CORD works to examine and interact with a running CORD environment. It is a good place for novice CORD users to start.
NOTE: If you are looking for instructions on how to install a multi-node POD, you will find them in quickstart_physical.md.
Specifically, the tutorial covers the following:
You will need a build host (e.g., your laptop) and a target server. The build host will run a development environment in a Vagrant VM that will be used to deploy CORD to the target server.
Build host requirements:
git (2.5.4 or later)Vagrant (1.8.1 or later)Target server requirements:
ubuntu user)If you do not have a target server available that meets the above requirements, you can borrow one on CloudLab. Sign up for an account using your organization's email address and choose "Join Existing Project"; for "Project Name" enter cord-testdrive.
NOTE: CloudLab is supporting CORD as a courtesy. It is expected that you will not use CloudLab resources for purposes other than evaluating CORD. If, after a week or two, you wish to continue using CloudLab to experiment with or develop CORD, then you must apply for your own separate CloudLab project.
Once your account is approved, start an experiment using the OnePC-Ubuntu14.04.4 profile on either the Wisconsin or Clemson cluster. This will provide you with a temporary target server meeting the above requirements.
Refer to the CloudLab documentation for more information.
Make sure you have a bin directory in your home directory and that it is included in your path:
mkdir ~/bin PATH=~/bin:$PATH
(of course you can put repo wherever you want)
Download the Repo tool and ensure that it is executable:
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo
To clone the repository, on your OtP build host issue the git command:
mkdir opencord && cd opencord repo init -u https://gerrit.opencord.org/manifest -b master -g build,onos
Fetch the opencord source code
repo sync
When this is complete, a listing (ls) of this directory should yield output similar to:
ls build
The development environment is required for the tasks in this repository. This environment leverages Vagrant to install the tools required to build and deploy the CORD software.
To create the development machine the following Vagrant command can be used. This will create an Ubuntu 14.04 LTS based virtual machine and install some basic required packages, such as Docker, Docker Compose, and Oracle Java 8.
cd build vagrant up corddev
NOTE: It may takes several minutes for the first command vagrant up corddev to complete as it will include creating the VM as well as downloading and installing various software packages.
Once the Vagrant VM is created and provisioned, you will see output ending with:
==> corddev: PLAY RECAP ********************************************************************* ==> corddev: localhost : ok=29 changed=25 unreachable=0 failed=0 ==> corddev: Configuring cache buckets...
To connect to the development machine the following vagrant command can be used.
vagrant ssh corddev
Once connected to the Vagrant machine, you can find the deployment artifacts in the /cord directory on the VM.
cd /cord
Gradle is the build tool that is used to help orchestrate the build and deployment of a POD. A launch script is included in the Vagrant machine that will automatically download and install gradle. The script is called gradlew and the download / install will be invoked on the first use of this script; thus the first use may take a little longer than subsequent invocations and requires a connection to the internet.
Once you have created and connected to the development environment this task is complete. The cord repository files can be found on the development machine under /cord. This directory is mounted from the host machine so changes made to files in this directory will be reflected on the host machine and vice-versa.
The fetching phase of the deployment pulls Docker images from the public repository down to the local machine as well as clones any git submodules that are part of the project. This phase can be initiated with the following command:
./gradlew fetch
Once the fetch command has successfully been run, this step is complete. After this command completes you should be able to see the Docker images that were downloaded using the docker images command on the development machine:
docker images REPOSITORY TAG IMAGE ID CREATED SIZE python 2.7-alpine 836fa7aed31d 5 days ago 56.45 MB consul <none> 62f109a3299c 2 weeks ago 41.05 MB registry 2.4.0 8b162eee2794 9 weeks ago 171.1 MB abh1nav/dockerui latest 6e4d05915b2a 19 months ago 469.5 MB
Edit the configuration file /cord/platform-install/config/default.yml. Add the IP address of your target server as well as the username / password for accessing the server. You can skip adding the password if you can SSH to the target server from inside the Vagrant VM as username without one (e.g., by running ssh-agent).
If you are planning on deploying the single-node POD to a CloudLab host, uncomment the following lines in the configuration file:
#extraVars: # - 'on_cloudlab=True'
This will signal the install process to set up extra disk space on the CloudLab node for use by CORD.
Before proceeding, verify that you can SSH to the target server from the development environment using the IP address, username, and password that you entered into the configuration file. Also verify that the user account can sudo without a password.
Deploy the CORD software to the the target server and configure it to form a running POD.
./gradlew -PdeployConfig=/cord/platform-install/config/default.yml deploySingle
What this does:
This command uses an Ansible playbook (cord-single-playbook.yml) to install OpenStack services, ONOS, and XOS in VMs on the target server. It also brings up a compute node as a VM.
This step usually takes at least an hour to complete. Be patient!
This step is completed once the Ansible playbook finishes without errors. If an error is encountered when running this step, the first thing to try is just running the above gradlew command again.
Once the step completes, two instances of ONOS are running, in the onos-cord-1 and onos-fabric-1 VMs, though only onos-cord-1 is used in the single-node install. OpenStack is also running on the target server with a virtual compute node called nova-compute-1. Finally, XOS is running inside the xos-1 VM and is controlling ONOS and OpenStack. You can get a deeper understanding of the configuration of the target server by visiting head_node_services.md.
You can access the CORD GUI (provided by XOS) by pointing your browser to URL http://<target-server>, using username padmin@vicci.org and password letmein.
The state of the system is that all CORD services have been onboarded to XOS (you can see them in the GUI by clicking Services at left), but no CORD subscribers have been created yet. To create a sample subscriber, proceed to the next step.
After the single-node POD is set up, you can execute basic health tests on the platform by running this command:
./gradlew -PdeployConfig=/cord/platform-install/config/default.yml postDeployTests
This tests the E2E connectivity of the POD by performing the following steps:
ping in the client to a public IP address in the InternetSuccess means that traffic is flowing between the subscriber household and the Internet via the vSG. If it succeeds, you should see some lines like these in the output:
TASK [test-vsg : Output from ping test] ****************************************
Thursday 28 July 2016 15:00:17 -0600 (0:00:03.367) 0:01:20.075 *********
ok: [localhost] => {
"pingtest.stdout_lines": [
"nova-compute-1 | SUCCESS | rc=0 >>",
"PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.",
"64 bytes from 8.8.8.8: icmp_seq=1 ttl=45 time=5.30 ms",
"64 bytes from 8.8.8.8: icmp_seq=2 ttl=45 time=5.29 ms",
"64 bytes from 8.8.8.8: icmp_seq=3 ttl=45 time=5.36 ms",
"",
"--- 8.8.8.8 ping statistics ---",
"3 packets transmitted, 3 received, 0% packet loss, time 2003ms",
"rtt min/avg/max/mdev = 5.295/5.320/5.365/0.031 ms"
]
}
This test builds on test-vsg by loading the exampleservice described in the Tutorial on Assembling and On-Boarding Services. The purpose of the exampleservice is to demonstrate how new subscriber-facing services can be easily deployed to a CORD POD. This test performs the following steps:
curl from the subscriber test client, through the vSG, to the Apache server.Success means that the Apache server launched by the exampleservice tenant is fully configured and is reachable from the subscriber client via the vSG. If it succeeds, you should see some lines like these in the output:
TASK [test-exampleservice : Output from curl test] *****************************
Thursday 28 July 2016 15:01:43 -0600 (0:00:01.441) 0:02:46.634 *********
ok: [localhost] => {
"curltest.stdout_lines": [
"nova-compute-1 | SUCCESS | rc=0 >>",
"ExampleService",
" Service Message: \"hello\"",
" Tenant Message: \"world\""
]
}
Once you are finished deploying the single-node POD, you can exit from the development environment on the build host and destroy it:
exit vagrant destroy -f
If you got this far, you successfully built, deployed, and tested your first CORD POD.
You are now ready to bring up a multi-node POD with a real switching fabric and multiple physical compute nodes. The process for doing so is described in quickstart_physical.md.