Merge "Development documentations update"

5 files changed, 186 insertions, 0 deletions

diff --git a/docs/development/design/feature-integration.rst b/docs/development/design/feature-integration.rst
new file mode 100644
index 00000000..71fceb3e
--- /dev/null
+++ b/docs/development/design/feature-integration.rst
@@ -0,0 +1,174 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) by Justin Chi (HUAWEI) and Yifei Xue (HUAWEI)
+
+How to integrate a feature into compass4nfv
+===========================================
+
+This document describes how to integrate a feature (e.g. sdn, moon, kvm, sfc)
+into compass installer. Follow the steps below, you can achieve the goal.
+
+Create a role for the feature
+-----------------------------
+
+Currently Ansible is the main packages installation plugin in the adapters of
+Compass4nfv, which is used to deploy all the roles listed in the playbooks.
+(More details about ansible and playbook can be achieved according to the
+Reference.) The mostly used playbook in compass4nfv is named
+"HA-ansible-multinodes.yml" located in "*your_path_to_compass4nfv*/compass4nfv/deploy/
+adapters/ansible/openstack/".
+
+Before you add your role into the playbook, create your role under the directory of
+"*your_path_to_compass4nfv*/compass4nfv/deploy/adapters/ansible/roles/". For example
+Fig 1 shows some roles currently existed in compass4nfv.
+
+
+.. figure:: images/Existed_roles.png
+    :alt: Existed roles in compass4nfv
+    :figclass: align-center
+
+    Fig 1. Existed roles in compass4nfv
+
+
+Let's take a look at "moon" and understand the construction of a role. Fig 2
+below presents the tree of "moon".
+
+
+.. figure:: images/Moon.png
+    :alt: Tree of moon role
+    :figclass: align-center
+
+    Fig 2. Tree of moon role
+
+
+There are five directories in moon, which are files, handlers, tasks, templates and vars.
+Almost every role has such five directories.
+
+For "files", it is used to store the files you want to copy to the hosts without any
+modification. These files can be configuration files, code files and etc. Here in moon's
+files directory, there are two python files and one configuration file. All of the three
+files will be copied to controller nodes for some purposes.
+
+For "handlers", it is used to store some operations frequently used in your tasks. For
+example, restart the service daemon.
+
+For "tasks", it is used to store the task yaml files. You need to add the yaml files including
+the tasks you write to deploy your role on the hosts. Please attention that a *main.yml*
+should be existed as the entrance of running tasks. In Fig 2, you can find that there are four
+yaml files in the tasks directory of moon. The *main.yml* is the entrance which will call the
+other three yaml files.
+
+For "templates", it is used to store the files that you want to replace some variables in them
+before copying to hosts. These variables are usually defined in "vars" directory. This can
+avoid hard coding.
+
+For "vars", it is used to store the yaml files in which the packages and variables are defined.
+The packages defined here are some generic debian or rpm packages. The script of making repo
+will scan the packages names here and download them into related PPA. For some special
+packages, section "Build packages for the feature" will introduce how to handle with special
+packages. The variables defined here are used in the files in "templates" and "tasks".
+
+Note: you can get the special packages in the tasks like this:
+
+.. code-block:: bash
+
+    - name: get the special packages' http server
+      shell: awk -F'=' '/compass_server/ {print $2}' /etc/compass.conf
+      register: http_server
+
+    - name: download odl package
+      get_url:
+        url: "http://{{ http_server.stdout_lines[0] }}/packages/odl/{{ odl_pkg_url }}"
+        dest: /opt/
+
+
+Build packages for the feature
+------------------------------
+
+In the previous section, we have explained how to build the generic packages for your feature.
+In this section, we will talk about how to build the special packages used by your feature.
+
+
+.. figure:: images/repo_features.png
+    :alt: Features building directory in compass4nfv
+    :figclass: align-center
+
+    Fig 3. Features building directory in compass4nfv
+
+
+Fig 3 shows the tree of "*your_path_to_compass4nfv*/compass4nfv/repo/features/". Dockerfile
+is used to start a docker container to run the scripts in scripts directory. These scripts
+will download the special feature related packages into the container. What you need to do is
+to write a shell script to download or build the package you want. And then put the script
+into "*your_path_to_compass4nfv*/compass4nfv/repo/features/scripts/". Attention that, you need
+to make a directory under */pkg*. Take opendaylight as an example:
+
+.. code-block:: bash
+
+    mkdir -p /pkg/odl
+
+After downloading or building your feature packages, please copy all of your packages into the
+directory you made, e.g. */pkg/odl*.
+
+Note: If you have specail requirements for the container OS or kernel vesion, etc. Please
+contact us.
+
+After all of these, come back to *your_path_to_compass4nfv*/compass4nfv/ directory, and run
+the command below:
+
+.. code-block:: bash
+
+    ./repo/make_repo.sh feature # To get special packages
+
+    ./repo/make_repo.sh openstack # To get generic packages
+
+When execution finished, you will get a tar package named *packages.tar.gz* under
+"*your_path_to_compass4nfv*/compass4nfv/work/repo/". Your feature related packages have been
+archived in this tar package. And you will also get the PPA packages which includes the generic
+packages you defined in the role directory. The PPA packages are *xenial-newton-ppa.tar.gz*
+and *centos7-newton-ppa.tar.gz*, also in "*your_path_to_compass4nfv*/compass4nfv/work/repo/".
+
+
+Build compass ISO including the feature
+---------------------------------------
+
+Before you deploy a cluster with your feature installed, you need an ISO with feature packages,
+generic packages and role included. This section introduces how to build the ISO you want.
+What you need to do are two simple things:
+
+**Configure the build configuration file**
+
+The build configuration file is located in "*your_path_to_compass4nfv*/compass4nfv/build/".
+There are lines in the file like this:
+
+.. code-block:: bash
+
+    export APP_PACKAGE=${APP_PACKAGE:-$FEATURE_URL/packages.tar.gz}
+
+    export XENIAL_NEWTON_PPA=${XENIAL_NEWTON_PPA:-$PPA_URL/xenial-newton-ppa.tar.gz}
+
+    export CENTOS7_NEWTON_PPA=${CENTOS7_NEWTON_PPA:-$PPA_URL/centos7-newton-ppa.tar.gz}
+
+Just replace the $FEATURE_URL and $PPA_URL to the directory where your *packages.tar.gz*
+located in. For example:
+
+.. code-block:: bash
+
+    export APP_PACKAGE=${APP_PACKAGE:-file:///home/opnfv/compass4nfv/work/repo/packages.tar.gz}
+
+    export XENIAL_NEWTON_PPA=${XENIAL_NEWTON_PPA:-file:///home/opnfv/compass4nfv/work/repo/xenial-newton-ppa.tar.gz}
+
+    export CENTOS7_NEWTON_PPA=${CENTOS7_NEWTON_PPA:-file:///home/opnfv/compass4nfv/work/repo/centos7-newton-ppa.tar.gz}
+
+**Build the ISO**
+
+After the configuration, just run the command below to build the ISO you want for deployment.
+
+.. code-block:: bash
+
+    ./build.sh
+
+References
+----------
+
+`Ansible documentation: http://docs.ansible.com/ansible/index.html>`
diff --git a/docs/development/design/images/Existed_roles.png b/docs/development/design/images/Existed_roles.png
new file mode 100644
index 00000000..b2427dba
--- /dev/null
+++ b/docs/development/design/images/Existed_roles.png
diff --git a/docs/development/design/images/Moon.png b/docs/development/design/images/Moon.png
new file mode 100644
index 00000000..869ffbc8
--- /dev/null
+++ b/docs/development/design/images/Moon.png
diff --git a/docs/development/design/images/repo_features.png b/docs/development/design/images/repo_features.png
new file mode 100644
index 00000000..c634bfa8
--- /dev/null
+++ b/docs/development/design/images/repo_features.png
diff --git a/docs/development/design/index.rst b/docs/development/design/index.rst
new file mode 100644
index 00000000..8dd7277d
--- /dev/null
+++ b/docs/development/design/index.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+========================
+Compass4nfv Design Guide
+========================
+
+.. toctree::
+   :numbered:
+   :maxdepth: 3
+
+   feature-integration.rst