Build Process Internals
All configuration in CORD is driven off of YAML files which contain variables used by Ansible, make, and Vagrant to build development and production environments. A glossary of build system variables is available which describes these variables and where they are used.
When a command to generate config such as
config is run, the following steps happen:
The POD Config file is read, in this case orchestration/profiles/rcord/podconfig/rcord-mock.yml, which specifies the scenario and profile. In virtual cases, frequently no further information is required, but in a physical POD, at least the inventory configuration must be specified.
The Scenario config file is read, in this case build/scenarios/mock/config.yml. The scenario determines which sets of components of CORD are installed, by controlling which make targets are run. It also contains a default inventory, which is used for development and testing of the scenario with virtual machines.
The Profile config file is read, in this case orchestration/profiles/rcord/rcord.yml. The profile contains the use-case Service_Graph and additional configuration specific to the configuration.
The contents of these three files are combined into a master config variable. The Scenario overwrites any config set in the Profile, and the POD Config overwrites any config set in the Scenario or Profile.
The entire master config is written to
inventory_groupsvariable is used to generate an ansible inventory file and put in
Various variables are used to generate the makefile config file
genconfig/config.mk. This sets the targets invoked by
make build, which is the
NOTE: The combination of the POD config, Scenario config, and Profile config in step #4 is not a union or merge. If you define an item in the root of the POD Config that is complex and has subkeys, it will overwrite every subkey defined in the Scenario or Profile.
This is most noticeable when setting the
docker_image_whitelistvariable. If you are creating a change in a POD Config, you must recreate the entire structure or list.
This may seem inconvenient, but other list or tree merging strategies available in Ansible lack a way to remove items from a tree structure, which is an incomplete solution.
Build Process Steps
The build process is driven by running
make. The two most common makefile
build, but there are also utility targets that are
handy to use during development.
config make target
config requires a
PODCONFIG argument, which is the name of a file in
PODCONFIG defaults to
invalid, so if you get errors claiming an invalid config, you probably didn't
make config step, or set it to a filename or
use-case path that
doesn't exist. Additionally, a
PODCONFIG_PATH variable can be used, which
takes an arbitrary path, when the podconfig is not within the use-case
PODCONFIG if both are set.
make PODCONFIG=rcord-local.yml config
make PODCONFIG=opencloud-mock.yml config
build make target
make build performs the build process, and usualy takes no arguments. The
targets run are specified in the scenario in the
Most of the build targets in the Makefile don't leave artifacts behind, so we
write a placeholder file (aka "sentinels" or "empty targets") in the
See adding targets to the Makefile for Makefile development information.
Utility make targets
There are various utility targets:
printconfig: Prints the configured scenario and profile.
xos-teardown: Stop and remove a running set of XOS docker containers, removing the database.
xos-update-images: Rebuild the images used by XOS, without tearing down running XOS containers.
collect-diag: Collect detailed diagnostic information on a deployed head and compute nodes, into
diag-<datestamp>directory on the head node.
compute-node-refresh: Reload compute nodes brought up by MaaS into XOS, useful in the cord virtual and physical scenarios
pod-test: Run the
platform-install/pod-test-playbook.yml, testing the virtual/physical cord scenario.
vagrant-destroy: Destroy Vagrant containers (for mock/virtual/physical installs)
clean-images: Have containers rebuild during the next build cycle. Does not actually delete any images, just causes imagebuilder to be run again.
clean-genconfig: Deletes the
make configgenerated config files in
genconfig, useful when switching between POD configs
clean-onos: Stops the ONOS containers on the head node
clean-openstack: Cleans up and deletes all instances and networks created in OpenStack.
clean-profile: Deletes the
clean-profiletargets, removes all milestones. Good for resetting a dev environment back to an unconfigured state.
clean-allbut for the
localscenario - Runs
clean-profiletargets, removes local milestones.
clean-* utility targets should modify the contents of the milestones
directory appropriately to cause the steps they clean up after to be rerun on
make build cycle.
Updating XOS Container Images on a running POD
To rebuild and update XOS container images, run:
make xos-update-images make -j4 build
This will build new copies of all the images, then when build is run the newly built containers will be restarted.
If you additionally want to stop all the XOS containers, clear the database,
and reload the profile, use
make xos-teardown make -j4 build
This will teardown the XOS container set, tell the build system to rebuild images, then perform a build and reload the profile.
Creating a Scenario
Creating a new scenarios requires creating 3 items:
Creating a scenario config file, in
Creating any makefile targets necessary for new features
The Virtual machine configuration (stored in a
Vagrantfile) for testing the scenario.
By default, the inventory in a Scenario is specific to the machines created in
Vagrantfile, and if needed elsewhere the
Creating the scenario config.yaml
A scenario configuration yaml file must define the following items:
build_targets, which is a list of milestones to complete. In most cases, there is only one item in this list, and all other milestone targets are invoked via dependencies within the makefile.
docker_image_whitelist, which is the list of images used in the scenario.
inventory_groups, which specifies the inventory used for testing the scenario in a virtual installation.
Most scenarios also define the following:
vagrant_vms, a list of the Vagrant VM's to bring up for testing the scenario in a virtual environment.
Various Vagrant configuration variables, used to configure VM's in the Vagrantfile.
headnode, and possibly
buildnode, which specify the hosts that are logged into with SSH when running various build steps that have to be executed locally on those nodes. These names should match the names or IP addresses given in
inventory_groups, but in a SSH compatible format. Some example of this:
physical_node_list, which is used for DNS, DHCP, and network configuration of compute nodes. It specifies the last octet of the IP addresses used for each node on the management and fabric networks, and the management network DNS names assigned to the node. This should match or be a superset of every system listed in
Adding targets to the Makefile
If you would like to add functionality to the makefile for inclusion in a scenario, the process is:
Create an ansible playbook or script for your task. In most cases this is in the
platform-installif the task applies to the entire platform, or in
maasif it's specific to the MaaS hardware deployment component.
Add a target to the makefile for the task. Many paths to source code locations, names of binaries, and similar are variables in the Makefile, so check the top of the Makefile for these.
The general format of a make target is:
$(M)/my-target: | $(m)prereq-target $(ANSIBLE_PB) $(PI)/my-task-playbook.yml $(LOGCMD) touch $@
touch $@is to create a create a file in the
milestonesdirectory (make variable for the path to
$(M)) after the target is run.
Create dependencies within the makefile to depend upon your task. Be aware of adding dependencies that could break other scenarios, so do this with care.
To handle the case where a target may be used only in a subset of scenarios,
prereqs_* lists of milestones are added to the scenario, and when
config is run, these are added to the
genconfig/config.mk file, in a
capitalized version. For example the
start_xos_prereqs list adds milestones
START_XOS_PREREQS variable (the
$(M) milestones directory path is
added to every item in the list)
Creating a scenario Vagrantfile
A Vagrantfile should be created for the scenario, for testing and development work.
Vagrantfiles can be thought of as a ruby Domain Specific Language (DSL), and as
such can take advantage of other ruby language features. This is used in CORD
to read the
genconfig/config.yml file generated during the
make config step
settings variable , which allows for the VMs to have additional
configuration at runtime - for example, the amount of memory used in a VM is
frequently set this way.
Some example configuration variables found in scenarios that are used in Vagrantfiles:
vagrant_box- The name of the Vagrant Box image used for the VM's. This is currently either
bento/ubuntu-16.04depending on the base OS used.
*_vm_mem- The amount of memory allocated for the VM
*_vm_cpu- The number of CPU's allocated for the VM