CORD : M-CORD Developer Environment for CORD 3.0

We can setup different environments for development work. So far, we have two choices, one is cord-in-a-box (CiaB), another is just a single VM for local development.

Choice 1: Setup CiaB based development environment.

Download and run the script on the target server. The script's output is displayed and also saved to ~/cord/install.out:

Download Script and run
$ curl -o ~/
$ bash ~/ -p mcord

The script takes a long time (at least two hours) to run. Be patient! If it hasn't completely failed yet, then assume all is well!

Development Workflow on CiaB

CORD-in-a-Box is a useful environment for integration testing and debugging. A typical scenario is to find a problem, and then rebuild and redeploy some XOS containers (e.g., a service synchronizer) to verify a fix. A workflow for quickly rebuilding and redeploying the XOS containers from source is:

Make changes in your source tree, under:


Login to the corddev VM by using

$ ssh corddev


$ cd /cord/build

First, if you made any changes to a profile (e.g., you added a new service), you'll need to re-sync the configuration from the build node to the head node. To do this run:

$ ./gradlew -PdeployConfig=config/mcord_in_a_box.yml PIprepPlatform

Then re-build and re-publish new images:

$ ./gradlew -PdeployConfig=config/mcord_in_a_box.yml :platform-install:buildImages
$ ./gradlew -PdeployConfig=config/mcord_in_a_box.yml :platform-install:publish
$ ./gradlew -PdeployConfig=config/mcord_in_a_box.yml :orchestration:xos:publish

Now the new XOS images should be published to the registry on prod. To bring them up, login to the prod VM and define these aliases:

CORD_PROFILE=$( cat /opt/cord_profile/profile_name )
alias xos-pull="docker-compose -p $CORD_PROFILE -f /opt/cord_profile/docker-compose.yml pull"
alias xos-up="docker-compose -p $CORD_PROFILE -f /opt/cord_profile/docker-compose.yml up -d --remove-orphans"
alias xos-teardown="pushd /opt/cord/build/platform-install; ansible-playbook -i inventory/head-localhost --extra-vars @/opt/cord/build/genconfig/config.yml teardown-playbook.yml; popd"
alias xos-launch="pushd /opt/cord/build/platform-install; ansible-playbook -i inventory/head-localhost --extra-vars @/opt/cord/build/genconfig/config.yml launch-xos-playbook.yml; popd"
alias compute-node-refresh="pushd /opt/cord/build/platform-install; ansible-playbook -i /etc/maas/ansible/pod-inventory --extra-vars=@/opt/cord/build/genconfig/config.yml compute-node-refresh-playbook.yml; popd"

To pull new images from the database and launch the containers, while retaining the existing XOS database, run:

$ xos-pull; xos-up

Alternatively, to remove the XOS database and reinitialize XOS from scratch, run:

$ xos-teardown; xos-pull; xos-launch; compute-node-refresh

Adding Tenants and Instances in TOSCA

You must onboard any tenant or instance TOSCA definitions separately from the rest of your service definitions. This is because in the build sequence above, the compute node is reprovisioned last, meaning that any instances that you define will not have any compute node to host them at the time the TOSCA is compiled. Therefore, for proper functionality/behavior, it is recommended that any TOSCA tenants or instances are defined in cord/build/platform-install/roles/test-mcord-tenants-config/templates/onboard-mcord-tenants.yaml.j2. To onboard this file, simply add and run the ansible playbook alias below from the prod VM.

$ alias deploy-tenants="pushd /opt/cord/build/platform-install; ansible-playbook -i inventory/head-localhost --extra-vars @/opt/cord/build/genconfig/config.yml mcord-tenant-playbook.yml; popd"
$ deploy-tenants

Choice 2: Deploy Locally on a VM

If you are doing work that does not involve OpenStack you can create a development environment inside a VM on your local machine. This environment is mostly designed to do GUI, APIs and modeling related work. It can also be useful to test a synchronizer whose job is synchronizing data using REST APIs.

*Note - This quick start guide has only been tested against Vagrant (v1.9.5) and VirtualBox (v5.1.22), specifically on MacOS.

The following dependencies/prerequisites are required to implement this approach:

  • Vagrant
  • VirtualBox
  • repo

Installing the Dependencies

The latest versions of each software can be found on their support pages, however homebrew can do it for us:

Install Dependencies
$ brew cask install vagrant
$ brew cask install virtualbox
$ brew install repo

If you do not have homebrew available, please download Vagrant and VirtualBox. Below are instructions on how to pull repo's source code directly.  Since CORD consists of 40+ repositories and changes can easily span multiple repositories, we use the repo tool to help us manage this complexity.

Install repo
$ cd /usr/bin
$ sudo wget
$ sudo chmod a+x /usr/bin/repo

Setting Up the Environment

Create a dedicated directory for the CORD source code and use repo to pull the source code from gerrit

Pull Source Code
$ mkdir cord && cd cord
$ repo init -u -b cord-3.0
$ repo sync

Start & Connect to the Head-Node VM

We provide a Vagrant VM where a container housing the XOS orchestrator resides. In the Cord-in-a-Box implementation, we can also start containers for ONOS, OpenStack, and MAAS (Metal-as-a-Service), however CiaB installation can take upwards of 2 hours to complete. This guide is meant for GUI, service profiles, and API related development to avoid the unnecessary overhead of the other components. The Vagrantfile for this VM is located in the build/platform-install directory. Below are the results after running 'vagrant status':

Starting the VM
$ cd build/platform-install
$ vagrant status
Current machine states:
head-node							not created (virtualbox)

The environment has not yet been created. Run `vagrant up` to
create the environment. If a machine is not created, only the
default provider will be shown. So if a provider is not listed,
then the machine is not created for that environment.

Once the VM is up and provisioned, vagrant status will look like:

Starting the VM
$ vagrant up
$ vagrant status
Current machine states:
head-node							running (virtualbox)
The VM is running. To stop this VM, you can run `vagrant halt` to
shut it down forcefully, or you can run `vagrant suspend` to simply
suspend the virtual machine. In either case, to restart it again,
simply run `vagrant up`

Now, we can connect to the VM

Starting the VM
$ vagrant ssh head-node
Welcome to Ubuntu 14.04.5 LTS (GNU/Linux 3.13.0-119-generic x86_64)

 * Documentation:

  System information as of Thu Jun  8 22:06:16 UTC 2017

  System load:                    0.0
  Usage of /:                     22.6% of 39.34GB
  Memory usage:                   18%
  Swap usage:                     0%
  Processes:                      126
  Users logged in:                0
  IP address for eth0:  
  IP address for eth1:  
  IP address for docker0:
  IP address for br-f125dd900ed3:

  Graph this data and manage this system at:

  Get cloud support with Ubuntu Advantage Cloud Guest:

0 packages can be updated.
0 updates are security updates.

New release '16.04.2 LTS' available.
Run 'do-release-upgrade' to upgrade to it.

Last login: Thu Jun  8 22:06:18 2017 from

Start the XOS Container w/ M-CORD Profile

Most profiles are run by specifying an inventory file when running ansible-playbook. For most frontend or mock profiles, you'll want to run the deploy-xos-playbook.yml playbook. To run the M-CORD profile, run:

Launching M-CORD Profile
$ cd cord/build/platform-install
$ ansible-playbook -i inventory/mock-mcord deploy-xos-playbook.yml

More information on deploying other CORD profiles can be found here:

Not in `docker` Usergroup

Your user may not be a member of the `docker` user group when you first connect to the head-node VM. This can cause a permissions error with regards to the Dockerfile inside the head-node. To be added to the user group, simply log out, and log back into the VM. You can verify your membership by running the `groups` command.

Connecting to the GUI

Deploying the M-CORD profile for the first time will take close to 20 minutes in order to set up the development environment. Once complete, you can connect to the XOS GUI running in the head-node. In the Vagrantfile, note that the VM's IP address is You can also confirm this using 'ifconfig' in the VM.

VM IP Address
$ ifconfig
eth1      Link encap:Ethernet  HWaddr 08:00:27:82:75:9a  
          inet addr:  Bcast:  Mask:
          inet6 addr: fe80::a00:27ff:fe82:759a/64 Scope:Link
          RX packets:4873 errors:0 dropped:0 overruns:0 frame:0
          TX packets:4480 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:597993 (597.9 KB)  TX bytes:4211482 (4.2 MB)

Your host machine and the VM are connected using a VirtualBox network interface created upon the launch of the VM. This means that you can connect to the XOS GUI by pointing your host machine's browser to The username is, and the password is auto generated in the /cord/build/platform-install/credentials/ file. The main page for the XOS GUI will look like this after log-in.


XOS Login Page


As you can see, the M-CORD profile has clearly been launched. Also, note that the service dependency graph is empty. This is because, as explained earlier, this is meant to be a bare installation of M-CORD. Should you want to proceed to a full CiaB run-through, see choice 1 above or use this guide,

When you are done using the VM, tear down the profile, exit the VM, and shut it down.

Tearing Down M-CORD Profile
$ ansible-playbook -i inventory/mock-mcord teardown-playbook.yml
$ exit
Connection to closed.
$ vagrant halt












Untitled.png (image/png)