Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Apex Developer Build & Integration Guide ======

Apex an installation tool deploys according to OPNFV requirements standards using [[https://www.rdoproject.org/rdo-manager/ | RDO Manager]] from the [[https://www.rdoproject.org/ | RDO Project]]. This document will describe the process to build Apex and to integrate new features into Apex.

To get a good overview of the terms that describe an Apex deployment and the target architecture of what is deployed please review the Installation Instructions. [[http://artifacts.opnfv.org/apex/docs/installation-instructions/installation-instructions.html | Apex Installation Instructions]]

===== Building and Deploying Apex for Development =====

Building and Deploying Apex for development is a set of instructions to build and deploy out of the code repository in order to iterate quickly over building and deploying. If you are interested in deploying OPNFV Apex on a system to evaluate or use please use the Installation Documentation released with our official builds or skip to the section "Building Apex to produce Packages" for installable packages.

<code>
$ cd ~
$ git clone https://gerrit.opnfv.org/gerrit/p/apex.git
$ cd apex/build
$ make instack-clean
$ make instack
$ cd ../ci
$ ./clean.sh
$ ./deploy.sh -v --no-ha -c ~/apex/build/ -r ~/apex/build/stack/ \
-n ~/apex/config/deploy/network/network_settings.yaml -d ~/apex/config/deploy/deploy_settings.yaml 
</code>

  * -v means virtual
  * --no-ha means use a single controller and single compute node
  * -c and -r point to configuration and resource directories. This indicates the deploy to use the locally built images from `make instack`
  * -d and -n are settings files that are discussed more in the installation instructions documentation.

Network_settings.yaml can be left as it is for a virtual deployment\\
Look though the catalog of files in apex/config/deploy to choose the flavor of deployment you would like. There are a collection of SDN controllers and features that can be enabled or swapped out. You can also just edit the stock deploy_settings.yaml if you would like.

===== Building Apex to produce Packages =====

Building Apex to produce packages will produce a set of RPMs that should be installed following the Installation Instructions distributed with OPNFV Apex.

<code>
$ git clone https://gerrit.opnfv.org/gerrit/p/apex.git
$ cd apex/ci
$ ./build -v {build-version} -c file:///{cache-storage-location}
</code>

RPMS will be put in the build/noarch directory.

{build-version} is an RPM release number compatible identifier. This is used in both the RPM release value and to name the ISO.\\ 
{cache-storage-location} is where the 7-10G cache file will be stored between builds

===== Build process details =====
There are a collection of files executed during build that are helpful to understand. Not all files used in build are listed here, these are the primary files.

| ci/build.sh | A boiler plate entry point for build. This file may become common across all builders and is most likely not necessary to be edited during integration |
| ci/clean.sh | an environment clean up script that deletes libvirt resources and  ovs bridges |
| build/Makefile | The entry point into Apex specific processing. It's responsible for orchestrating the build process, RPM build and ISO build |
| build/instack.sh | The main build script. This is where configuration files and disk images are prepared for inclusion in the RPM |
| build/cache.mk | Handles building the cache,main take away: what is cached is defined in the top of this file |


Apex is built in a few stages and tasks summarized here:
  * construct virtual machine and dump their definitions
  * attach to RDO Project repository
  * download disk images
  * modify downloaded disk images
  * build RPM with configuration, scripts and disk images
  * build CentOS ISO for offline deployment

Building Apex is as simple as cloning the git repository and executing the build. The build scripts are designed to ensure that all the software dependencies are made available to the build. There are a few requirements to consider before building.

  * password-less tty-less sudo or root access is required
  * properly working libvirt installation is required
  * a new user will be autocreated named stack (this is for awareness only, no action required)
  * disk images, a centos iso, the Apex RPMs and iso and a build cache will all be written to disk which average around 80G of space at the time of this doc being written.

=== What happens during build in the instack.sh file ===
To build Apex, artifacts and packages are collected from the RDO Project build system. This includes:

  * RPM Packages from the RDO Release Repository
  * A pre-built Undercloud qcow2 image
  * Pre-built introspection images
  * Pre-built Overcloud qcow2 image

The disk images are cached after build so that they don't have to be downloaded again if they haven't been refreshed upstream. Though, RDO Project can rebuild them as frequently as every 8 hours. Once these disk images are downloaded the build process will modify them in preparation to use for Apex deployment.

Apex will also collect and prepare the artifacts for the SDN controller options that are supported for deployment.

Next, a collection of virtual machines are constructed:
  * the Instack Undercloud VM
  * 5 "Baremetal VMs" that the overcloud is deployed to in a virtual deployment.

Finally, the VM definitions are dumped to disk in preparation for packaging

=== RPM packaging and ISO build in the Makefile ===
Once instack.sh has run and has dumped all the files to disk that are needed to build, git archive is run which generates the initial tarball the RPM will build from. During build, files are generated that need to be included in the tarball so that the RPM has access to them for packaging. The tarball is appended with the necessary files for final packaging and deployment. Rpmbuild is executed to roll the RPM that includes the configuration files, deployment scripts and disk images necessary for deployment.

Once the RPM is built the CentOS installation DVD is downloaded, exploded, modified adding the Apex RPM and updating the installation configuration files for the OS and the ISO is rebuilt with the updated contents.
===== Apex Feature Integration =====

[[https://www.rdoproject.org/rdo-manager/ | RDO Manager]] from the [[https://www.rdoproject.org/ | RDO Project]] is the OpenStack installation platform that Apex is built on. Patches submitted must fit 1 of 2 criteria in order to be submitted for merge:
  - update the Apex and or OPNFV specific contents of the project
  - intent to update an upstream project used by Apex
    - patches for upstream projects can be carried temporarily in the Apex code base as long as there is active effort for the patch to be merged into the upstream project.

In addition, the RDO Manager project itself is considered "midstream" and it's upstream counterpart is called TripleO (also called "ooo").

=== TripleO Code Integration and Patches ===
In order to integrate your feature into Apex, you must create a patch for TripleO code.  TripleO uses heat templates with puppet configuration providers as its method to configure OpenStack Controllers and Images.  The TripleO sub-project for this is called "tripleo-heat-templates".  

As previously mentioned we can accodomate applying that patch via the Apex project, until the code is merged upstream.  At the time of this writing we currently do this for the OpenDaylight Controller feature.  An example commit for tripleo-heat-templates providing OpenDaylight installation can be found here [[https://review.openstack.org/#/c/200253/ | tripleO-OpenDaylight]].  They key files to modify include the yaml based heat templates, as well as the puppet modules.

Key Heat Templates:
  * puppet/controller.yaml (Controller Heat resource definition)
  * puppet/compute.yaml (Compute Heat resource definition)
  * overcloud.yaml (Overall Role definitions, previously called overcloud-without-merge in stable/liberty)

Key Puppet Modules:
  * puppet/manifests/overcloud_compute.pp (Compute puppet module)
  * puppet/manifests/overcloud_controller.pp (Controller puppet module for no-HA)
  * puppet/manifests/overcloud_controller_pacemaker.pp (Controller puppe tmodule for HA)

=== Feature Artifact Integration ===
Most features, such as OpenDaylight will need some artifact included in the Apex, such as the OpenDaylight controller software.  In Apex you can create a patch similar to what we do with OpenDaylight where you can use virt-customize in order to copy over any bits you need to the overcloud image.  For instance, we copy over the OpenDaylight RPM and necessary opendaylight puppet module to install/configure it, then our TripleO-OpenDaylight change takes care of initiating the the module and configuring it correctly.

Document is work in progress. More content is on its way
Wiki

User Tools

Site Tools

Page Tools
