diff options
| -rw-r--r-- | docs/index.rst | 9 | ||||
| -rw-r--r-- | docs/sections/administration.rst | 6 | ||||
| -rw-r--r-- | docs/sections/configuration.rst | 36 | ||||
| -rw-r--r-- | docs/sections/consumedapis.rst | 32 | ||||
| -rw-r--r-- | docs/sections/distribution.rst | 749 | ||||
| -rw-r--r-- | docs/sections/example.rst | 1 | ||||
| -rw-r--r-- | docs/sections/glossary.rst | 74 | ||||
| -rw-r--r-- | docs/sections/homingspecification.rst | 11 | ||||
| -rw-r--r-- | docs/sections/humaninterfaces.rst | 6 | ||||
| -rw-r--r-- | docs/sections/installation.rst | 758 | ||||
| -rw-r--r-- | docs/sections/release-notes.rst | 122 |
11 files changed, 898 insertions, 906 deletions
diff --git a/docs/index.rst b/docs/index.rst index 69b61c3..e626a31 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,15 +39,10 @@ is an orchestration service, or Nova is a compute service. ./sections/architecture.rst ./sections/offeredapis.rst - ./sections/homingspecification.rst ./sections/consumedapis.rst - Distribution <./sections/distribution.rst> - ./sections/logging.rst ./sections/installation.rst - ./sections/configuration.rst - ./sections/administration.rst - ./sections/humaninterfaces.rst - ./sections/glossary.rst + ./sections/logging.rst + ./sections/homingspecification.rst Example Homing Templates <./sections/example.rst> ./sections/release-notes.rst diff --git a/docs/sections/administration.rst b/docs/sections/administration.rst deleted file mode 100644 index 0650561..0000000 --- a/docs/sections/administration.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Administration -============================================= - - Administration - TBD
\ No newline at end of file diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst deleted file mode 100644 index 5e55a89..0000000 --- a/docs/sections/configuration.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Configuration -============================================= - -For the configuration inside the config-file, please refer to the README inside Gerrit - -It is worth noting that A&AI and MUSIC may be needed to run HAS project. Please refer to their setup page for installation. - -For MUSIC version 2.4.x and newer refer Setup for Developing MUSIC - -Running the example ------------------------ -To start the process, execute the following commands: - - $ conductor-api --port=8091 -- --config-file={conductor_conf_file_location} - - $ conductor-controller --config-file={conductor_conf_file_location} - - $ conductor-solver --config-file={conductor_conf_file_location} - - $ conductor-reservation --config-file={conductor_conf_file_location} - - $ conductor-data --config-file={conductor_conf_file_location} - -Committing the Code ------------------------ - $ git commit -am "Initial proj struct" - - $ git review -s - - $ git commit -as --amend - -# scroll down 2 lines (above your Change-ID) insert "Issue-ID: {issue_id}" - - $ git review diff --git a/docs/sections/consumedapis.rst b/docs/sections/consumedapis.rst index 954a138..00ffde9 100644 --- a/docs/sections/consumedapis.rst +++ b/docs/sections/consumedapis.rst @@ -2,17 +2,35 @@ Consumed APIs ============================================= -The following are the dependencies for the project based on the scope for the Beijing Release. -The required dependencies have been identified based on the current homing requirements for the vCPE use case, -and the potential dependencies are tentative dependencies that may exist based on how the information required -for homing (e.g., Hardware Platform Enablement, VIM attributes) is available. - +The following are the dependencies for the project based on the scope for the Casablanca Release. AAI -------------------------------------------- -See documentation for Active and Available Inventory component +See ReadTheDocs documentation for Active and Available Inventory component + - `AAI project page <https://onap.readthedocs.io/en/beijing/submodules/aai/aai-common.git/docs/index.html>`_ Multi-Cloud -------------------------------------------- -See documentation for Multi-Cloud component
\ No newline at end of file +See ReadTheDocs documentation for Multi-Cloud component + + - `Multi-Cloud project page <https://onap.readthedocs.io/en/beijing/submodules/multicloud/framework.git/docs/index.html>`_ + +MUSIC +-------------------------------------------- +See ReadTheDocs documentation for Multi-site State Coordination Service component + + - `MUSIC project page <https://onap.readthedocs.io/en/beijing/submodules/music.git/docs/index.html>`_ + +SDNC +-------------------------------------------- +See ReadTheDocs documentation for Software Defined Network Controller component + + - `SDNC project page <https://onap.readthedocs.io/en/beijing/submodules/sdnc/oam.git/docs/index.html>`_ + +SMS +-------------------------------------------- +The Secrets Management Service is a component of the Application Authorization Framework. Disclaimer - +as of this writing AAF RTD does not include discussion of SMS + + - `SMS project page <https://onap.readthedocs.io/en/beijing/submodules/aaf/authz.git/docs/index.html>`_ diff --git a/docs/sections/distribution.rst b/docs/sections/distribution.rst deleted file mode 100644 index df7a4c2..0000000 --- a/docs/sections/distribution.rst +++ /dev/null @@ -1,749 +0,0 @@ -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 index b1a5313..a3dd55b 100644 --- a/docs/sections/example.rst +++ b/docs/sections/example.rst @@ -62,6 +62,7 @@ Example 1 - distance_between: - customer_loc - vG + Example 1 --------- diff --git a/docs/sections/glossary.rst b/docs/sections/glossary.rst deleted file mode 100644 index 99e56e5..0000000 --- a/docs/sections/glossary.rst +++ /dev/null @@ -1,74 +0,0 @@ -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/homingspecification.rst b/docs/sections/homingspecification.rst index 7ab1859..0edb441 100644 --- a/docs/sections/homingspecification.rst +++ b/docs/sections/homingspecification.rst @@ -1135,7 +1135,7 @@ supported by the services, etc. | ``attributes_value`` | Attributes value | +--------------------------+-------------------------------------------+ -*Note: Each VFC must have one directive with type 'flavor_directives' to put the +*Note*: Each VFC must have one directive with type 'flavor_directives' to put the flavors inside. The ``attribute_name`` is the place to put flavor label and the ``attribute_value`` will first left blank. After getting the proper flavor, OOF will merge the flavor name into the ``attribute_value`` inside flavor directives. Also, @@ -1184,6 +1184,9 @@ together in ``directives``, as they are using the same structure as 'directives' Example for HEAT request(SO) +*Note*: Where "attributes":[{"attribute_name":" oof_returned_flavor_label_for_vgw_1 ", + Admin needs to ensure that this value is same as flavor parameter in HOT + .. code-block:: json { @@ -1202,7 +1205,7 @@ Example for HEAT request(SO) "type":"flavor_directives", "attributes":[ { - "attribute_name":" oof_returned_flavor_label_for_vgw_0 ", //Admin needs to ensure that this value is same as flavor parameter in HOT + "attribute_name":" oof_returned_flavor_label_for_vgw_0 ", "attribute_value": "<Blank>" } ] @@ -1283,7 +1286,7 @@ Example for HEAT request(SO) "type":"flavor_directives", "attributes":[ { - "attribute_name":" oof_returned_flavor_label_for_vgw_1 ", //Admin needs to ensure that this value is same as flavor parameter in HOT + "attribute_name":" oof_returned_flavor_label_for_vgw_1 ", "attribute_value": "<Blank>" } ] @@ -1372,7 +1375,7 @@ Example for HEAT request(SO) } } } - + Example for Pure TOSCA request(VF-C) .. code-block:: json diff --git a/docs/sections/humaninterfaces.rst b/docs/sections/humaninterfaces.rst deleted file mode 100644 index 5b8c3e7..0000000 --- a/docs/sections/humaninterfaces.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Human Interfaces -============================================= - - OOF HAS does not expose a human interface
\ No newline at end of file diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst index f25aea3..df7a4c2 100644 --- a/docs/sections/installation.rst +++ b/docs/sections/installation.rst @@ -1,25 +1,749 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. +Python/Linux Distribution Notes +=============================== -Installation -============================================= +*Updated: 10 Nov 2017 23:30 GMT* -Installing from the Source Code ------------------------------------- -Get HAS seed code from the Linux Foundation Projects page +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. -.. code-block:: bash +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 -Use python virtual environment (https://virtualenv.pypa.io/en/stable/) to create and manage libraries and dependencies for HAS project. - $ virtualenv {virtual_environment_location} - - $ source {virtual_environemtn_location}/bin/activate +Remove any previously made configuration file changes, user accounts, +Ubuntu/SWM packages, and other settings as needed. -Inside of /has/conductor folder, run the following commands: - $ python setup.py install - - $ pip install -e . +Bug Reporting and Feedback +-------------------------- -In {virtual_environment_location}/bin folder, you should see the five components of HAS/Conductor project -conductor-api,conductor-controller, conductor-solver, conductor-reservation, conductor-data +... is encouraged. Please raise an issue at: +https://jira.onap.org/projects/OPTFRA/summary diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst index fe5b98a..6ac990f 100644 --- a/docs/sections/release-notes.rst +++ b/docs/sections/release-notes.rst @@ -7,6 +7,128 @@ Release Notes ============= +Version: 1.2.4 +-------------- + +:Release Date: 2018-11-30 (R3 Casablanca Release) + +**New Features** + +A summary of features includes: + +* Security enhancements, including integration with AAF to implement access controls on + OSDF and HAS northbound interfaces +* Integration with SMS +* Platform Maturity Level 1 + * ~50%+ unit test coverage +* Hardware Platform Awareness Enhancements + 1) Added support for SRIOV-NIC and directives to assist the orchestrator + 2) Select the best candidate across all cloud region based on HPA score. + 3) HPA metrics using prometheus + +The Casablanca release for OOF delivered the following Epics. + + * OPTFRA-106 - OOF Functional Testing Related User Stories and Tasks + * OPTFRA-266 - Integrate OOF with Certificate and Secret Management Service (CSM) + * OPTFRA-267 - OOF - HPA Enhancements + * OPTFRA-269 - This epic covers the work to get the OOF development platform ready for Casablanca development + * OPTFRA-270 - This epic captures stories related to maintaining current S3P levels of the project as new functional requirements are supported + * OPTFRA-271 - This epic spans the work to progress further from the current security level + * OPTFRA-272 - This epic spans the work to progress further from the current Performance level + * OPTFRA-273 - This epic spans the work to progress further from the current Manageability level + * OPTFRA-274 - This epic spans the work to progress further from the current Usability level + * OPTFRA-275 - This epic spans the stories to improve deployability of services + * OPTFRA-276 - Implementing a POC for 5G SON Optimization + * OPTFRA-298 - Should be able to orchestrate Cross Domain and Cross Layer VPN + +**Bug Fixes** + + * OPTFRA-205 - Generated conductor.conf missing configurations + * OPTFRA-210 - Onboarding to Music error + * OPTFRA-211 - Error solution for HPA + * OPTFRA-249 - OOF does not return serviceResourceId in homing solution + * OPTFRA-259 - Fix intermittent failure of HAS CSIT job + * OPTFRA-264 - oof-has-zookeeper image pull error + * OPTFRA-305 - Analyze OOM health check failure + * OPTFRA-306 - OOF-Homing fails health check in HEAT deployment + * OPTFRA-321 - Fix osdf functional tests script to fix builder failures + * OPTFRA-323 - Cannot resolve multiple policies with the same 'hpa-feature' name + * OPTFRA-325 - spelling mistake + * OPTFRA-326 - hyperlink links are missing + * OPTFRA-335 - Making flavors an optional field in HAS candidate object + * OPTFRA-336 - OOM oof deployment failure on missing image - optf-osdf:1.2.0 + * OPTFRA-338 - Create authentication key for OOF-VFC integration + * OPTFRA-341 - Cannot support multiple candidates for one feature in one flavor + * OPTFRA-344 - Fix broken HPA CSIT test + * OPTFRA-354 - Generalize the logic to process Optimization policy + * OPTFRA-358 - Tox fails with the AttributeError: 'module' object has no attribute 'MUSIC_API' + * OPTFRA-359 - Create index on plans table for HAS + * OPTFRA-362 - AAF Authentication CSIT issues + * OPTFRA-365 - Fix Jenkins jobs for CMSO + * OPTFRA-366 - HAS CSIT issues + * OPTFRA-370 - Update the version of the OSDF and HAS images + * OPTFRA-374 - 'ModelCustomizationName' should be optional for the request + * OPTFRA-375 - SO-OSDF request is failing without modelCustomizationName value + * OPTFRA-384 - Generate and Validate Policy for vFW testing + * OPTFRA-385 - resourceModelName is sent in place of resourceModuleName + * OPTFRA-388 - Fix OOF to handle sdnr/configdb api changes + * OPTFRA-395 - CMSO - Fix security violations and increment version + + +**Known Issues** + +These are all issues with fix version: Casablanca Release and status: open, in-progress, reopened + + * OPTFRA-401 - Need flavor id while launching vm + * OPTFRA-398 - Add documentation for OOF-VFC interaction + * OPTFRA-393 - CMSO Implement code coverage + * OPTFRA-383 - OOF 7 of 8 pods are not starting in a clean master 20181029 + * OPTFRA-368 - Remove Beijing repositories from CLM jenkins + * OPTFRA-337 - Document new transitions in HAS states + * OPTFRA-331 - Role-based access controls to OOF + * OPTFRA-329 - role based access control for OSDF-Policy interface + * OPTFRA-316 - Clean up hard-coded references to south bound dependencies + * OPTFRA-314 - Create user stories for documenting new APIs defined for OOF + * OPTFRA-304 - Code cleaning + * OPTFRA-300 - Fix Heat deployment scripts for OOF + * OPTFRA-298 - Should be able to orchestrate Cross Domain and Cross Layer VPN + * OPTFRA-297 - OOF Should support Cross Domain and Cross Layer VPN + * OPTFRA-296 - Support SON (PCI) optimization using OSDF + * OPTFRA-293 - Implement encryption for all OSDF internal and external communication + * OPTFRA-292 - Implement encryption for all HAS internal and external communication + * OPTFRA-279 - Policy-based capacity check enhancements + * OPTFRA-276 - Implementing a POC for 5G SON Optimization + * OPTFRA-274 - This epic spans the work to progress further from the current Usability level + * OPTFRA-273 - This epic spans the work to progress further from the current Manageability level + * OPTFRA-272 - This epic spans the work to progress further from the current Performance level + * OPTFRA-271 - This epic spans the work to progress further from the current security level + * OPTFRA-270 - This epic captures stories related to maintaining current S3P levels of the project as new functional requirements are supported + * OPTFRA-269 - This epic covers the work to get the OOF development platform ready for Casablanca development + * OPTFRA-268 - OOF - project specific enhancements + * OPTFRA-266 - Integrate OOF with Certificate and Secret Management Service (CSM) + * OPTFRA-262 - ReadTheDoc - update for R3 + * OPTFRA-260 - Testing vCPE flows with multiple clouds + * OPTFRA-240 - Driving Superior Isolation for Tiered Services using Resource Reservation -- Optimization Policies for Residential vCPE + * OPTFRA-223 - On boarding and testing AAF certificates for OSDF + +**Security Issues** + +OPTFRA code has been formally scanned during build time using NexusIQ and no Critical vulnerability was found. + +**Quick Links**: + - `OPTFRA project page <https://wiki.onap.org/display/DW/Optimization+Framework+Project>`_ + + - `Passing Badge information for OPTFRA <https://bestpractices.coreinfrastructure.org/en/projects/1720>`_ + +**Upgrade Notes** +To upgrade, run docker container or install from source, See Distribution page + +**Deprecation Notes** +No features deprecated in this release + +**Other** +None + Version: 1.1.1 -------------- |