summaryrefslogtreecommitdiffstats
path: root/docs/sections
diff options
context:
space:
mode:
authorfsandoval <frank.sandoval@oamtechnologies.com>2018-05-30 14:22:03 -0600
committerfsandoval <frank.sandoval@oamtechnologies.com>2018-05-30 18:04:27 -0600
commit84ad836b25024835dc3abbb42832dfd36bcb23ce (patch)
tree83cba4ad0888031557151518b7d889cd82fefd1f /docs/sections
parent6808592a9533c02d58981c3a4317ceb5dd056899 (diff)
update has docs
Issue-ID: OPTFRA-242 Change-Id: I9d89ef313018c3a0c25c48a4e0cecabba75db2fd Signed-off-by: fsandoval <frank.sandoval@oamtechnologies.com>
Diffstat (limited to 'docs/sections')
-rw-r--r--docs/sections/distribution.rst749
-rw-r--r--docs/sections/example.rst144
-rw-r--r--docs/sections/glossary.rst74
-rw-r--r--docs/sections/release-notes.rst10
4 files changed, 976 insertions, 1 deletions
diff --git a/docs/sections/distribution.rst b/docs/sections/distribution.rst
new file mode 100644
index 0000000..df7a4c2
--- /dev/null
+++ b/docs/sections/distribution.rst
@@ -0,0 +1,749 @@
+Python/Linux Distribution Notes
+===============================
+
+*Updated: 10 Nov 2017 23:30 GMT*
+
+This document exists to help bridge the gap between the Conductor python
+package and any downstream distribution. The steps outlined herein may
+be taken into consideration when creating an AT&T SWM package,
+Ubuntu/Debian package, Chef cookbook, or Ansible playbook.
+
+Components
+----------
+
+Conductor consists of five services that work together:
+
+- **``conductor-api``**: An HTTP REST API
+- **``conductor-controller``**: Validation, translation, and
+ status/results
+- **``conductor-data``**: Inventory provider and service controller
+ gateway
+- **``conductor-solver``**: Processing and solution calculation
+- **``conductor-reservation``**: Reserves the suggested solution solved
+ by Solver component.
+
+Workflow
+--------
+
+- Deployment **plans** are created, viewed, and deleted via
+ ``conductor-api`` and its `REST API <doc/api/README.md>`__.
+- Included within each ``conductor-api`` plan request is a `Homing
+ Template <doc/template/README.md>`__.
+- Homing Templates describe a set of inventory demands and constraints
+ to be solved against.
+- ``conductor-api`` hands off all API requests to
+ ``conductor-controller`` for handling.
+- All deployment plans are assigned a unique identifier (UUID-4), which
+ can be used to check for solution status asynchronously. (Conductor
+ does not support callbacks at this time.)
+- ``conductor-controller`` ensures templates are well-formed and valid.
+ Errors and remediation are made visible through ``conductor-api``.
+ When running in debug mode, the API will also include a python
+ traceback in the response body, if available.
+- ``conductor-controller`` uses ``conductor-data`` to resolve demands
+ against a particular **inventory provider** (e.g., A&AI).
+- ``conductor-controller`` translates the template into a format
+ suitable for solving.
+- As each template is translated, ``conductor-solver`` begins working
+ on it.
+- ``conductor-solver`` uses ``conductor-data`` to resolve constraints
+ against a particular **service controller** (e.g., SDN-C).
+- ``conductor-solver`` determines the most suitable inventory to
+ recommend.
+- ``conductor-reservation`` attempts to reserve the solved solution in
+ SDN-GC
+
+**NOTE**: There is no Command Line Interface or Python API Library at
+this time.
+
+Pre-Flight and Pre-Installation Considerations
+----------------------------------------------
+
+AT&T Application Identifiers and Roles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- App/Tool Name: ECOMP Conductor
+- MOTS Application ID: 26213
+- MechID: m04308
+- ECOMP Feature ID: F13704
+- PMT: 461306
+- UAM Role Name: Conductor Production Support
+- UAM Role id: 0000025248
+
+Root
+~~~~
+
+Be aware that some commands may require ``sudo``, depending on the
+account being used to perform the installation.
+
+Proxy
+~~~~~
+
+If line-of-sight to internet-facing repositories is permitted and
+available, set the following shell environment variables if AT&T proxy
+services are required:
+
+.. code:: bash
+
+ $ export http_proxy="http://one.proxy.att.com:8080/"
+ $ export https_proxy="http://one.proxy.att.com:8080/"
+
+Requirements
+~~~~~~~~~~~~
+
+Conductor is officially supported on `Ubuntu 14.04 LTS (Trusty
+Tahr) <http://releases.ubuntu.com/14.04/>`__, though it should also work
+on newer releases.
+
+Ensure the following Ubuntu packages are present, as they may not be
+included by default:
+
+- `libffi-dev <http://packages.ubuntu.com/trusty/libffi-dev>`__
+- `postgresql-server-dev-9.3 <http://packages.ubuntu.com/trusty/postgresql-server-dev-9.3>`__
+- `python2.7 <http://packages.ubuntu.com/trusty/python2.7>`__
+
+``conductor-api`` may be run as-is for development and test purposes.
+When used in a production environment, it is recommended that
+``conductor-api`` run under a multithreaded httpd service supporting
+`WSGI <https://www.wikipedia.org/wiki/Web_Server_Gateway_Interface>`__,
+tuned as appropriate.
+
+Configuration instructions for **apache2 httpd** and **nginx** are
+included herein. Respective package requirements are:
+
+- `apache2 <http://packages.ubuntu.com/trusty/apache2>`__ and
+ `libapache2-mod-wsgi <http://packages.ubuntu.com/trusty/libapache2-mod-wsgi>`__
+- `nginx <http://packages.ubuntu.com/trusty/nginx>`__ and
+ `uwsgi <http://packages.ubuntu.com/trusty/uwsgi>`__
+
+All Conductor services use AT&T `Music <https://github.com/att/music>`__
+for data storage/persistence and/or as a RPC transport mechanism.
+Consult the `Music Local Installation
+Guide <https://github.com/att/music/blob/master/README.md>`__ for
+installation/configuration steps.
+
+Networking
+~~~~~~~~~~
+
+All conductor services require line-of-sight access to all Music
+servers/ports.
+
+The ``conductor-api`` service uses TCP port 8091.
+
+Security
+~~~~~~~~
+
+``conductor-api`` is accessed via HTTP. SSL/TLS certificates and
+AuthN/AuthZ (e.g., AAF) are not supported at this time.
+
+Conductor makes use of plugins that act as gateways to *inventory
+providers* and *service controllers*. At present, two plugins are
+supported out-of-the-box: **A&AI** and **SDN-C**, respectively.
+
+A&AI requires two-way SSL/TLS. Certificates must be registered and
+whitelisted with A&AI. SDN-C uses HTTP Basic Authentication. Consult
+with each respective service for official information on how to obtain
+access.
+
+Storage
+~~~~~~~
+
+For a cloud environment in particular, it may be desirable to use a
+separate block storage device (e.g., an OpenStack Cinder volume) for
+logs, configuration, and other data persistence. In this way, it becomes
+a trivial matter to replace the entire VM if necessary, followed by
+reinstallation of the app and any supplemental configuration. Take this
+into consideration when setting various Conductor config options.
+
+Python Virtual Environments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At present, Conductor installation is only supported at the (upstream)
+python package level and not the (downstream) Ubuntu distribution or SWM
+package levels.
+
+To mitigate/eliminate the risk of introducing conflicts with other
+python applications or Ubuntu/SWM package dependencies, consider
+installing Conductor in a `python virtual
+environment <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`__
+(or *venv* for short).
+
+Example venv-aware WSGI app configurations, sysvinit scripts, and
+upstart scripts can be found in the Conductor repository under
+`examples </examples/>`__.
+
+Python Package Dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Conductor is installed using the python ``pip`` command. ``pip`` uses a
+python project's `requirements manifest </requirements.txt>`__ to
+install all python module dependencies.
+
+**NOTE**: When line-of-sight access to a PyPI-compatible package index
+is not available, advance installation of Conductor's python package
+dependencies is required *before* installation.
+
+Other Production Environment Considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TBD. ``:)``
+
+Over time, considerations may include services such as:
+
+- AAF
+- AppMetrics
+- Introscope
+- Nagios
+- Splunk
+- UAM
+
+Installation and Configuration
+------------------------------
+
+**IMPORTANT**: Perform the steps in this section after *optionally*
+configuring and activating a python virtual environment.
+
+Installing From a PyPI Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In ONAP, the ``conductor`` package can be found on \`\`\`\`.
+
+Installation is via the ``pip`` command. Here is an example ``pip.conf``
+file that uses both the internet and intranet-facing PyPI repositories:
+
+.. code:: ini
+
+ [global]
+ index = https://pypi.python.org/pypi
+ index-url = https://pypi.python.org/simple
+ extra-index-url =
+ trusted-host =
+
+Once the configuration is in place, installation is simple:
+
+.. code:: bash
+
+ $ pip install of-has
+
+To upgrade or downgrade, simply re-run ``pip install`` using the
+appropriate ``pip`` command line options.
+
+**NOTE**: Be sure proxy settings are in place if they're required to
+access ``pypi.python.org``.
+
+Installing From Source
+~~~~~~~~~~~~~~~~~~~~~~
+
+Conductor source in ONAP is maintained in
+https://gerrit.onap.org/r/optf/has.
+
+Clone the git repository, and then install from within the ``conductor``
+directory:
+
+.. code:: bash
+
+ $ git clone https://gerrit.onap.org/r/optf/has
+ Cloning into 'conductor'...
+ remote: Counting objects: 2291, done.
+ remote: Compressing objects: 88% (1918/2179)
+ remote: Compressing objects: 100% (2179/2179), done.
+ remote: Total 2291 (delta 1422), reused 0 (delta 0)
+ Receiving objects: 100% (2291/2291), 477.59 KiB | 0 bytes/s, done.
+ Resolving deltas: 100% (1422/1422), done.
+ $ cd conductor
+ $ pip install .
+
+The latest source can be pulled from ONAP at any time and reinstalled:
+
+.. code:: bash
+
+ $ git pull
+ $ pip install .
+
+Verifying Installation
+~~~~~~~~~~~~~~~~~~~~~~
+
+Each of the five Conductor services may be invoked with the ``--help``
+option:
+
+.. code:: bash
+
+ $ conductor-api -- --help
+ $ conductor-controller --help
+ $ conductor-data --help
+ $ conductor-solver --help
+ $ conductor-reservation --help
+
+**NOTE**: The ``conductor-api`` command is deliberate. ``--`` is used as
+as separator between the arguments used to start the WSGI server and the
+arguments passed to the WSGI application.
+
+Post-Flight and Post-Installation Considerations
+------------------------------------------------
+
+User and Group
+~~~~~~~~~~~~~~
+
+It's good practice to create an unprivileged account (e.g., a user/group
+named ``conductor``) and run all Conductor services as that user:
+
+.. code:: bash
+
+ $ sudo addgroup --system conductor
+ $ sudo adduser --system --home /var/lib/conductor --ingroup conductor --no-create-home --shell /bin/false conductor
+
+SSL/TLS Certificates
+~~~~~~~~~~~~~~~~~~~~
+
+The A&AI Inventory Provider Plugin requiries two-way SSL/TLS. After
+provisioning a certificate per A&AI guidelines, it will be necessary to
+securely install the certificate, key, and certificate authority bundle.
+
+When running conductor services as ``conductor:conductor``
+(recommended), consider co-locating all of these files under the
+configuration directory. For example, when using ``/etc/conductor``:
+
+.. code:: bash
+
+ $ # Certificate files (crt extension, 644 permissions)
+ $ sudo mkdir /etc/conductor/ssl/certs
+ $ # Private Certificate Key files (key extension, 640 permissions)
+ $ sudo mkdir /etc/conductor/ssl/private
+ $ # Certificate Authority (CA) Bundles (crt extension, 644 permissions)
+ $ sudo mkdir /etc/conductor/ssl/ca-certificates
+ $ # Add files to newly created directories, then set ownership
+ $ sudo chmod -R conductor:conductor /etc/conductor/ssl
+
+For a hypothetical domain name ``imacculate.client.research.att.com``,
+example filenames could be as follows:
+
+.. code:: bash
+
+ $ find ssl -type f -printf '%M %u:%g %f\n'
+ -rw-r----- conductor:conductor imacculate.client.research.att.com.key
+ -rw-r--r-- conductor:conductor Symantec_Class_3_Secure_Server_CA.crt
+ -rw-r--r-- conductor:conductor imacculate.client.research.att.com.crt
+
+When running conductor services as ``root``, consider these existing
+Ubuntu filesystem locations for SSL/TLS files:
+
+**Certificate** files (``crt`` extension) are typically stored in
+``/etc/ssl/certs`` with ``root:root`` ownership and 644 permissions.
+
+**Private Certificate Key** files (``key`` extension) are typically
+stored in ``/etc/ssl/private`` with ``root:root`` ownership and 640
+permissions.
+
+**Certificate Authority (CA) Bundles** (``crt`` extension) are typically
+stored in ``/usr/share/ca-certificates/conductor`` with ``root:root``
+ownership, and 644 permissions. These Bundle files are then symlinked
+within ``/etc/ssl/certs`` using equivalent filenames, a ``pem``
+extension, and ``root:root`` ownership.
+
+**NOTE**: LUKS (Linux Unified Key Setup) is not supported by Conductor
+at this time.
+
+Configuration
+~~~~~~~~~~~~~
+
+Configuration files are located in ``etc/conductor`` relative to the
+python environment Conductor is installed in.
+
+To generate a sample configuration file, change to the directory just
+above where ``etc/conductor`` is located (e.g., ``/`` for the default
+environment, or the virtual environment root directory). Then:
+
+.. code:: bash
+
+ $ oslo-config-generator --config-file=etc/conductor/conductor-config-generator.conf
+
+This will generate ``etc/conductor/conductor.conf.sample``.
+
+Because the configuration directory and files will include credentials,
+consider removing world permissions:
+
+.. code:: bash
+
+ $ find etc/conductor -type f -exec chmod 640 {} +
+ $ find etc/conductor -type d -exec chmod 750 {} +
+
+The sample config may then be copied and edited. Be sure to backup any
+previous ``conductor.conf`` if necessary.
+
+.. code:: bash
+
+ $ cd etc/conductor
+ $ cp -p conductor.conf.sample conductor.conf
+
+``conductor.conf`` is fully annotated with descriptions of all options.
+Defaults are included, with all options commented out. Conductor will
+use defaults even if an option is not present in the file. To change an
+option, simply uncomment it and edit its value.
+
+With the exception of the ``DEFAULT`` section, it's best to restart the
+Conductor services after making any config changes. In some cases, only
+one particular service actually needs to be restarted. When in doubt,
+however, it's best to restart all of them.
+
+A few options in particular warrant special attention:
+
+::
+
+ [DEFAULT]
+
+ # If set to true, the logging level will be set to DEBUG instead of the default
+ # INFO level. (boolean value)
+ # Note: This option can be changed without restarting.
+ #debug = false
+
+For more verbose logging across all Conductor services, set ``debug`` to
+true.
+
+::
+
+ [aai]
+
+ # Base URL for A&AI, up to and not including the version, and without a
+ # trailing slash. (string value)
+ #server_url = https://controller:8443/aai
+
+ # SSL/TLS certificate file in pem format. This certificate must be registered
+ # with the A&AI endpoint. (string value)
+ #certificate_file = certificate.pem
+
+ # Private Certificate Key file in pem format. (string value)
+ #certificate_key_file = certificate_key.pem
+
+ # Certificate Authority Bundle file in pem format. Must contain the appropriate
+ # trust chain for the Certificate file. (string value)
+ #certificate_authority_bundle_file = certificate_authority_bundle.pem
+
+Set ``server_url`` to the A&AI server URL, to but not including the
+version, omitting any trailing slash. Conductor supports A&AI API v9 at
+a minimum.
+
+Set the ``certificate`` prefixed keys to the appropriate SSL/TLS-related
+files.
+
+**IMPORTANT**: The A&AI server may have a mismatched host/domain name
+and SSL/TLS certificate. In such cases, certificate verification will
+fail. To mitigate this, ``certificate_authority_bundle_file`` may be set
+to an empty value. While Conductor normally requires a CA Bundle
+(otherwise why bother using SSL/TLS), this requirement has been
+temporarily relaxed so that development and testing may continue.
+
+::
+
+ [messaging_server]
+
+ # Log debug messages. Default value is False. (boolean value)
+ #debug = false
+
+When the ``DEFAULT`` section's ``debug`` option is ``true``, set this
+section's ``debug`` option to ``true`` to enable detailed Conductor-side
+RPC-over-Music debug messages.
+
+Be aware, it is voluminous. "You have been warned." ``:)``
+
+::
+
+ [music_api]
+
+ # List of hostnames (round-robin access) (list value)
+ #hostnames = localhost
+
+ # Log debug messages. Default value is False. (boolean value)
+ #debug = false
+
+Set ``hostnames`` to match wherever the Music REST API is being hosted
+(wherever Apache Tomcat and ``MUSIC.war`` are located).
+
+When the ``DEFAULT`` section's ``debug`` option is ``true``, set this
+section's ``debug`` option to ``true`` to enable detailed Conductor-side
+MUSIC API debug messages.
+
+The previous comment around the volume of log lines applies even more so
+here. (Srsly. We're not kidding.)
+
+**IMPORTANT**: Conductor does not presently use Music's atomic
+consistency features due to concern around lock creation/acquisition.
+Instead, Conductor uses eventual consistency. For this reason,
+consistency issues may occur when using Music in a multi-server, High
+Availability configuration.
+
+::
+
+ [sdnc]
+
+ # Base URL for SDN-C. (string value)
+ #server_url = https://controller:8443/restconf
+
+ # Basic Authentication Username (string value)
+ #username = <None>
+
+ # Basic Authentication Password (string value)
+ #password = <None>
+
+Set ``server_url`` to the SDN-C server URL, omitting any trailing slash.
+
+Set ``username`` and ``password`` to the appropriate values as directed
+by SDN-C.
+
+Running for the First Time
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each Conductor component may be run interactively. In this case, the
+user does not necessarily matter.
+
+When running interactively, it is suggested to run each command in a
+separate terminal session and in the following order:
+
+.. code:: bash
+
+ conductor-data --config-file=/etc/conductor/conductor.conf
+ conductor-controller --config-file=/etc/conductor/conductor.conf
+ conductor-solver --config-file=/etc/conductor/conductor.conf
+ conductor-reservation --config-file=/etc/conductor/conductor.conf
+ conductor-api --port=8091 -- --config-file=/etc/conductor/conductor.conf
+
+Optionally, use an application like
+`screen <http://packages.ubuntu.com/trusty/screen>`__ to nest all five
+terminal sessions within one detachable session. (This is also the same
+package used by
+`DevStack <https://docs.openstack.org/developer/devstack/>`__.)
+
+To verify that ``conductor-api`` can be reached, browse to
+``http://HOST:8091/``, where HOST is the hostname ``conductor-api`` is
+running on. No AuthN/AuthZ is required at this time. Depending on
+network considerations, it may be necessary to use a command like
+``wget`` instead of a desktop browser.
+
+The response should look similar to:
+
+.. code:: json
+
+ {
+ "versions": {
+ "values": [
+ {
+ "status": "development",
+ "updated": "2016-11-01T00:00:00Z",
+ "media-types": [
+ {
+ "base": "application/json",
+ "type": "application/vnd.ecomp.homing-v1+json"
+ }
+ ],
+ "id": "v1",
+ "links": [
+ {
+ "href": "http://127.0.0.1:8091/v1",
+ "rel": "self"
+ },
+ {
+ "href": "http://conductor.research.att.com/",
+ "type": "text/html",
+ "rel": "describedby"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+Sample API Calls and Homing Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A `Postman <http://getpostman.com/>`__ collection illustrating sample
+requests is available upon request. The collection will also be added in
+a future revision.
+
+`Sample homing templates </doc/examples/README.md>`__ are also
+available.
+
+Ubuntu Service Scripts
+~~~~~~~~~~~~~~~~~~~~~~
+
+Ubuntu sysvinit (init.d) and upstart (init) scripts are typically
+installed at the Ubuntu package level. Since there is no such packaging
+at this time, example scripts have been provided in the repository.
+
+To install, place all Conductor `sysvinit
+scripts </examples/distribution/ubuntu/init.d>`__ in ``/etc/init.d``,
+and all `upstart scripts </examples/distribution/ubuntu/init>`__ in
+``/etc/init``.
+
+Set file permissions:
+
+.. code:: bash
+
+ $ sudo chmod 644 /etc/init/conductor*
+ $ sudo chmod 755 /etc/init.d/conductor*
+
+If a python virtual environment is being used, edit each
+``/etc/init/conductor*`` and ``/etc/init.d/conductor*`` prefixed file so
+that ``PYTHON_HOME`` is set to the python virtual environment root
+directory.
+
+Next, enable the scripts:
+
+.. code:: bash
+
+ $ sudo update-rc.d conductor-api defaults
+ $ sudo update-rc.d conductor-controller defaults
+ $ sudo update-rc.d conductor-data defaults
+ $ sudo update-rc.d conductor-solver defaults
+ $ sudo update-rc.d conductor-reservation defaults
+ $ sudo initctl reload-configuration
+
+Conductor components may now be started/stopped like any other Ubuntu
+service, for example:
+
+.. code:: bash
+
+ $ sudo service conductor-api start
+ $ sudo service conductor-api status
+ $ sudo service conductor-api restart
+ $ sudo service conductor-api stop
+
+Conductor service scripts automatically create directories for ``log``,
+``lock``, ``run``, ``lib``, and ``log`` files, e.g.,
+``/var/log/conductor`` and so on.
+
+Log File Rotation
+~~~~~~~~~~~~~~~~~
+
+Sample ``logrotate.d`` configuration files have been provided in the
+repository.
+
+To install, place all Conductor `logrotate
+files </examples/distribution/ubuntu/logrotate.d>`__ in
+``/etc/logrotate.d``.
+
+Set file ownership and permissions:
+
+.. code:: bash
+
+ $ sudo chown root:root /etc/logrotate.d/conductor*
+ $ sudo chmod 644 /etc/logrotate.d/conductor*
+
+``logrotate.d`` automatically recognizes new files at the next log
+rotation opportunity and does not require restarting.
+
+Running conductor-api Under apache2 httpd and mod\_wsgi
+-------------------------------------------------------
+
+Sample configuration files have been provided in the repository.
+
+These instructions presume a ``conductor`` user exists. See the
+**Service Scripts** section for details.
+
+First, set up a few directories:
+
+.. code:: bash
+
+ $ sudo mkdir -p /var/www/conductor
+ $ sudo mkdir /var/log/apache2/conductor
+
+To install, place the Conductor `WSGI application
+file </conductor/api/app.wsgi>`__ in ``/var/www/conductor``.
+
+Set the owner/group of both directories/files to ``conductor``:
+
+.. code:: bash
+
+ $ sudo chown -R conductor:conductor /var/log/apache2/conductor /var/www/conductor
+
+Next, place the Conductor `apache2 httpd site config
+file </examples/apache2/conductor.conf>`__ in
+``/etc/apache2/sites-available``.
+
+Set the owner/group to ``root``:
+
+.. code:: bash
+
+ $ sudo chown -R root:root /etc/apache2/sites-available/conductor.conf
+
+If Conductor was installed in a python virtual environment, append
+``python-home=VENV`` to ``WSGIDaemonProcess``, where ``VENV`` is the
+python virtual environment root directory.
+
+**IMPORTANT**: Before proceeding, disable the ``conductor-api`` sysvinit
+and upstart services, as the REST API will now be handled by apache2
+httpd. Otherwise there will be a port conflict, and you will be sad.
+
+Enable the Conductor site, ensure the configuration syntax is valid, and
+gracefully restart apache2 httpd.
+
+.. code:: bash
+
+ $ sudo a2ensite conductor
+ $ sudo apachectl -t
+ Syntax OK
+ $ sudo apachectl graceful
+
+To disable the Conductor site, run ``sudo a2dissite conductor``, then
+gracefully restart once again. Optionally, re-enable the
+``conductor-api`` sysvinit and upstart services.
+
+Running conductor-api Under nginx and uWSGI
+-------------------------------------------
+
+Sample configuration files have been provided in the repository.
+
+These instructions presume a ``conductor`` user exists. See the
+**Service Scripts** section for details.
+
+To install, place the Conductor `nginx config
+files </examples/nginx/>`__ and `WSGI application
+file </conductor/api/app.wsgi>`__ in ``/etc/nginx`` (taking care to
+backup any prior configuration files). It may be desirable to
+incorporate Conductor's ``nginx.conf`` into the existing config.
+
+Rename ``app.wsgi`` to ``conductor.wsgi``:
+
+.. code:: bash
+
+ $ cd /etc/nginx
+ $ sudo mv app.wsgi conductor.wsgi
+
+In ``nginx.conf``, set ``CONDUCTOR_API_FQDN`` to the server name.
+
+**IMPORTANT**: Before proceeding, disable the ``conductor-api`` sysvinit
+and upstart services, as the REST API will now be handled by nginx.
+Otherwise there will be a port conflict, and you will be sad.
+
+Restart nginx:
+
+.. code:: bash
+
+ $ sudo service nginx restart
+
+Then, run ``conductor-api`` under nginx using uWSGI:
+
+.. code:: bash
+
+ $ sudo uwsgi -s /tmp/uwsgi.sock --chmod-socket=777 --wsgi-file /etc/nginx/conductor.wsgi --callable application --set port=8091
+
+To use a python virtual environment, add ``--venv VENV`` to the
+``uwsgi`` command, where ``VENV`` is the python virtual environment root
+directory.
+
+Uninstallation
+--------------
+
+Activate a virtual environment (venv) first, if necessary, then
+uninstall with:
+
+.. code:: bash
+
+ $ pip uninstall ecomp-conductor
+
+Remove any previously made configuration file changes, user accounts,
+Ubuntu/SWM packages, and other settings as needed.
+
+Bug Reporting and Feedback
+--------------------------
+
+... is encouraged. Please raise an issue at:
+https://jira.onap.org/projects/OPTFRA/summary
diff --git a/docs/sections/example.rst b/docs/sections/example.rst
new file mode 100644
index 0000000..b1a5313
--- /dev/null
+++ b/docs/sections/example.rst
@@ -0,0 +1,144 @@
+Example Conductor Templates
+===========================
+
+Example 1
+---------
+
+.. code:: yaml
+
+ name: yyy-yyy-yyyy
+ files: {}
+ timeout: 600
+ limit: 1
+ template:
+ homing_template_version: '2018-02-01'
+ parameters:
+ service_name: ''
+ service_id: d61b2543-5914-4b8f-8e81-81e38575b8ec
+ customer_lat: 32.89748
+ customer_long: -97.040443
+ locations:
+ customer_loc:
+ latitude:
+ get_param: customer_lat
+ longitude:
+ get_param: customer_long
+ demands:
+ vGMuxInfra:
+ - inventory_provider: aai
+ inventory_type: service
+ service_type: vGMuxInfra-xx
+ attributes:
+ customer-id: ''
+ orchestration-status: ''
+ model-invariant-id: b3dc6465-942c-42af-8464-2bf85b6e504b
+ model-version-id: ba3b8981-9a9c-4945-92aa-486234ec321f
+ service-type: vGMuxInfra-xx
+ equipment-role: ''
+ global-customer-id: SDN-ETHERNET-INTERNET
+ vG:
+ - inventory_provider: aai
+ inventory_type: cloud
+ service_type: 71d563e8-e714-4393-8f99-cc480144a05e
+ constraints:
+ affinity_vCPE:
+ type: zone
+ demands:
+ - vGMuxInfra
+ - vG
+ properties:
+ category: complex
+ qualifier: same
+ optimization:
+ minimize:
+ sum:
+ - product:
+ - '1'
+ - distance_between:
+ - customer_loc
+ - vGMuxInfra
+ - product:
+ - '1'
+ - distance_between:
+ - customer_loc
+ - vG
+Example 1
+---------
+
+.. code:: yaml
+
+ files: {}
+ limit: 1
+ name: a2e3e0cc-3a97-44fc-8a08-1b86143fbdd3
+ template:
+ constraints:
+ affinity_vCPE:
+ demands:
+ - vgMuxAR
+ - vGW
+ properties:
+ category: complex
+ qualifier: same
+ type: zone
+ distance-vGMuxAR:
+ demands:
+ - vgMuxAR
+ properties:
+ distance: "< 500 km"
+ location: customer_loc
+ type: distance_to_location
+ distance-vGW:
+ demands:
+ - vGW
+ properties:
+ distance: "< 1500 km"
+ location: customer_loc
+ type: distance_to_location
+ demands:
+ vGW:
+ - attributes:
+ model-invariant-id: 782c87a6-b712-47d1-9c5b-1ea2cd9a2dd5
+ model-version-id: 9877dbbe-8ada-40a2-8adb-f6f26f1ad9ab
+ inventory_provider: aai
+ inventory_type: cloud
+ service_type: c3e0e82b-3367-48ce-ab00-27dc2e91a34a
+ vgMuxAR:
+ - attributes:
+ global-customer-id: SDN-ETHERNET-INTERNET
+ model-invariant-id: 565d5b75-11b8-41be-9991-ee03a0049159
+ model-version-id: 61414c6c-6082-4e03-9824-bf53c3582b78
+ inventory_provider: aai
+ inventory_type: service
+ service_type: 46b29078-8442-4ea3-bea6-9199a7d514d4
+ homing_template_version: '2017-10-10'
+ locations:
+ customer_loc:
+ latitude:
+ get_param: customer_lat
+ longitude:
+ get_param: customer_long
+ optimization:
+ minimize:
+ sum:
+ - product:
+ - '1'
+ - distance_between:
+ - customer_loc
+ - vgMuxAR
+ - product:
+ - '1'
+ - distance_between:
+ - customer_loc
+ - vGW
+ parameters:
+ customer_lat: 32.89748
+ customer_long: 97.040443
+ service_id: 0dbb9d5f-27d9-429b-bc36-293e9fab7731
+ service_name: ''
+ timeout: 600
+
+Contact
+-------
+
+Shankar Narayanan shankarpnsn@gmail.com
+a \ No newline at end of file
diff --git a/docs/sections/glossary.rst b/docs/sections/glossary.rst
new file mode 100644
index 0000000..99e56e5
--- /dev/null
+++ b/docs/sections/glossary.rst
@@ -0,0 +1,74 @@
+Glossary
+========
+
++-----------------------+---------------+
+| Term | Description |
++=======================+===============+
+| **A&AI** | Active and |
+| | Available |
+| | Inventory |
++-----------------------+---------------+
+| **Cloud** | tbd |
+| | |
++-----------------------+---------------+
+| **Conductor** | AIC/ECOMP |
+| | Homing |
+| | service. |
++-----------------------+---------------+
+| **Constraint** | tbd |
+| | |
++-----------------------+---------------+
+| **Cost Function** | tbd |
+| | |
++-----------------------+---------------+
+| **Data Center** | tbd |
+| | |
++-----------------------+---------------+
+| **DCAE** | Data |
+| | Collection, |
+| | Analytics, |
+| | Events |
++-----------------------+---------------+
+| **Demand** | tbd |
+| | |
++-----------------------+---------------+
+| **Homing** | Canonical |
+| | service name |
+| | for Conductor |
++-----------------------+---------------+
+| **Host** | tbd |
+| | |
++-----------------------+---------------+
+| **Inventory** | tbd |
+| | |
++-----------------------+---------------+
+| **Inventory Source** | tbd |
+| | |
++-----------------------+---------------+
+| **LCP (and vLCP)** | Local Control |
+| | Plane (or |
+| | virtual LCP). |
+| | Synonymous |
+| | with |
+| | **Region**. |
++-----------------------+---------------+
+| **Location** | tbd |
+| | |
++-----------------------+---------------+
+| **Network Link** | tbd |
+| | |
++-----------------------+---------------+
+| **Region** | Synonymous |
+| | with **LCP**. |
++-----------------------+---------------+
+| **Service Inventory** | tbd |
+| | |
++-----------------------+---------------+
+| **Site** | tbd |
+| | |
++-----------------------+---------------+
+
+Contact
+-------
+
+Joe D'Andrea jdandrea@research.att.com
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
index ec2358e..0aec94f 100644
--- a/docs/sections/release-notes.rst
+++ b/docs/sections/release-notes.rst
@@ -53,7 +53,15 @@ None. Initial release R2 Beijing. No previous versions
Known Issues
------------
-None.
+
+ * [OPTFRA-179] - Error solution for HPA
+
+ * [OPTFRA-205] - Onboarding to Music error
+
+ * [OPTFRA-210] - Generated conductor.conf missing configurations
+
+ * [OPTFRA-211] - Remove Extraneous Flavor Information from cloud-region cache
+
Security Issues
---------------