Building and Installing CORD
Starting points
If this is your first encounter with CORD, we suggest you start by bringing up an Virtual Pod, which installs CORD on a set of virtual machines running on a single physical server: Installing a Virtual Pod (CORD-in-a-Box).
You can also install CORD on a physical POD, as would be done in a production environment, which involves first assembling a set of servers and switches, and then pointing the build system at that target hardware: Installing a Physical POD.
If you are interested in developing a new CORD service, working on the XOS GUI, or performing other development tasks, see Developing for CORD.
If you've run into trouble or want to know more about the CORD build process, please see Troubleshooting and Build Internals.
Required Tools
CORD has a unified build system for development and deployment which uses the following tools:
And either:
- Docker, for local build scenarios, tested with Community Edition version 17.06
- Vagrant, for all other scenarios
tested with version 2.0.1, requires specific plugins and modules if using
with libvirt, see
cord-bootstrap.sh
for more details
You can manually install these on your development system - see Getting the Source Code for a more detailed instructions for checking out the CORD source tree.
cord-bootstrap.sh script
If you're working on an cleanly installed Ubuntu 14.04 system, you can use the
cord-bootstrap.sh
script to install these tools and check out the CORD source
tree to ~/cord
.
curl -o ~/cord-bootstrap.sh https://raw.githubusercontent.com/opencord/cord/cord-5.0/scripts/cord-bootstrap.sh
chmod +x cord-bootstrap.sh
NOTE: Change the
master
path component in the URL to your desired version branch (ex:cord-5.0
) if required.
The bootstrap script has the following options:
Usage for ./cord-bootstrap.sh:
-d Install Docker for local scenario.
-h Display this help message.
-p <project:change/revision> Download a patch from gerrit. Can be repeated.
-t <target> Run 'make -j4 <target>' in cord/build/. Can be repeated.
-v Install Vagrant for mock/virtual/physical scenarios.
Using the -v
option is required to install Vagrant for running a Virtual Pod
(CiaB) or Physical Pod, whereas -d
is required to install Docker for a Local Workflow.
The -p
option downloads a patch from gerrit, and the syntax for this is
<project path>:<changeset>/<revision>
. It can be used multiple
time. For example:
./cord-bootstrap.sh -p build/platform-install:1233/4 -p orchestration/xos:1234/2
checks out the platform-install
repo with changeset 1233, patchset 4, and
xos
repo changeset 1234, revision 2.
You can find the project path in the repo
manifest file:
manifest/default.xml.
You can also run make targets with the -t
option; -t build
is the same as
running cd ~/cord/build ; make -j4 build
after the rest of the installations
and downloads have completed.
In some cases, you may see a message like this if you install software that adds you to a group and you aren't already a member:
You are not in the group: libvirtd, please logout/login.
You are not in the group: docker, please logout/login.
In such cases, please logout and login to the system to gain the proper group membership. Another way to tell if you're in the right groups:
~$ groups
xos-PG0 root
~$ vagrant status
Call to virConnectOpen failed: Failed to connect socket to '/var/run/libvirt/libvirt-sock': Permission denied
~$ logout
~$ ssh node_name.cloudlab.us
~$ groups
xos-PG0 root libvirtd
Note that if you aren't in the right group, any patches specified by -p
will
be downloaded, but no make targets specified by -t
will be run - you will
need to cd ~/cord/build
and run those targets manually.
Configuring a Build
The CORD build process is designed to be modular and configurable with only a handful of YAML files.
POD Config
Each CORD use-case (e.g., R-CORD, M-CORD, E-CORD) has its own repository
containing configuration files for that type of POD. All of these repositories
appear in the source tree under orchestration/profiles/
. For example,
R-CORD's repository is
orchestration/profiles/rcord.
The top level configuration for a build is the POD config file, a YAML file
stored in each use-case repository's podconfig
subdirectory. Each Pod config
file contains a list of variables that control how the build proceeds, and can
override the configuration of the rest of the build. A minimal POD config file
must define two variables:
cord_scenario
- the name of the scenario to use, which is defined in a
directory under build/scenarios.
cord_profile
- the name of a profile to use, defined as a YAML file at the
top level of the use-case repository - ex:
mcord-ng40.yml.
The naming convention for POD configs stored in the use case repository is
<profile>-<scenario>.yml
- ex:
mcord-ng40-virtual.yml builds the virtual
scenario using the
mcord-ng40
profile. All such POD configs can be specified during a build
using the PODCONFIG
variable:
make PODCONFIG=rcord-virtual.yml config
POD configs with arbitrary names can be specified using
PODCONFIG_PATH
. This will override the PODCONFIG
variable.
make PODCONFIG_PATH=./podconfig/my-pod-config.yml config
Profiles
The set of services that XOS on-boards into CORD -- the Service Graph, and other per-profile configuration for a CORD deployment. These are located in build/platform-install/profile_manifests.
Scenarios
Scenarios define the physical or virtual environment that CORD will be
installed into, a default mapping of ansible groups to nodes, the set of Docker
images that can be built, and software and platform features are installed onto
those nodes. Scenarios are subdirectories of the
build/scenarios directory, and consist of a config.yaml
file and possibly VM's
specified in a Vagrantfile
.
The current set of scenarios:
local
: Minimal set of containers running locally on the development hostmock
: Creates a single Vagrant VM with containers and DNS set up, without synchronizerssingle
: Creates a single Vagrant VM with containers and DNS set up, with synchronizers and optional ElasticStack/ONOScord
: Physical or virtual multi-node CORD pod, with MaaS and OpenStackopencloud
: Physical or virtual multi-node OpenCloud pod, with OpenStack
The scenario is specified in the POD config's cord_scenario
line.