summaryrefslogtreecommitdiffstats
path: root/docs/release
diff options
context:
space:
mode:
Diffstat (limited to 'docs/release')
-rw-r--r--docs/release/configguide/feature.configuration.rst104
-rw-r--r--docs/release/configguide/index.rst12
-rw-r--r--docs/release/index.rst19
-rw-r--r--docs/release/installation/index.rst12
-rw-r--r--docs/release/installation/releasenotes.rst113
-rw-r--r--docs/release/installation/releasenotes_colorado.rst170
-rw-r--r--docs/release/userguide/feature.userguide.rst44
-rw-r--r--docs/release/userguide/index.rst12
8 files changed, 486 insertions, 0 deletions
diff --git a/docs/release/configguide/feature.configuration.rst b/docs/release/configguide/feature.configuration.rst
new file mode 100644
index 00000000..3ddc409c
--- /dev/null
+++ b/docs/release/configguide/feature.configuration.rst
@@ -0,0 +1,104 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Doctor Configuration
+====================
+
+OPNFV installers install most components of Doctor framework including
+OpenStack Nova, Neutron and Cinder (Doctor Controller) and OpenStack
+Ceilometer and Aodh (Doctor Notifier) except Doctor Monitor.
+
+After major components of OPNFV are deployed, you can setup Doctor functions
+by following instructions in this section. You can also learn detailed
+steps in setup_installer() under `doctor/tests`_.
+
+.. _doctor/tests: https://gerrit.opnfv.org/gerrit/gitweb?p=doctor.git;a=tree;f=tests;
+
+Doctor Inspector
+----------------
+
+You need to configure one of Doctor Inspector below.
+
+**Doctor Sample Inspector**
+
+Sample Inspector is intended to show minimum functions of Doctor Inspector.
+
+Doctor Sample Inspector suggested to be placed in one of the controller nodes,
+but it can be put on any host where Doctor Monitor can reach and access
+the OpenStack Controller (Nova).
+
+Make sure OpenStack env parameters are set properly, so that Doctor Inspector
+can issue admin actions such as compute host force-down and state update of VM.
+
+Then, you can configure Doctor Inspector as follows:
+
+.. code-block:: bash
+
+ git clone https://gerrit.opnfv.org/gerrit/doctor -b stable/danube
+ cd doctor/tests
+ INSPECTOR_PORT=12345
+ python inspector.py $INSPECTOR_PORT > inspector.log 2>&1 &
+
+**Congress**
+
+OpenStack `Congress`_ is a Governance as a Service (previously Policy as a
+Service). Congress implements Doctor Inspector as it can inspect a fault
+situation and propagate errors onto other entities.
+
+.. _Congress: https://wiki.openstack.org/wiki/Congress
+
+Congress is deployed by OPNFV installers. You need to enable doctor
+datasource driver and set policy rules. By the example configuration below,
+Congress will force down nova compute service when it received a fault event
+of that compute host. Also, Congress will set the state of all VMs running on
+that host from ACTIVE to ERROR state.
+
+.. code-block:: bash
+
+ openstack congress datasource create doctor doctor
+
+ openstack congress policy rule create \
+ --name host_down classification \
+ 'host_down(host) :-
+ doctor:events(hostname=host, type="compute.host.down", status="down")'
+
+ openstack congress policy rule create \
+ --name active_instance_in_host classification \
+ 'active_instance_in_host(vmid, host) :-
+ nova:servers(id=vmid, host_name=host, status="ACTIVE")'
+
+ openstack congress policy rule create \
+ --name host_force_down classification \
+ 'execute[nova:services.force_down(host, "nova-compute", "True")] :-
+ host_down(host)'
+
+ openstack congress policy rule create \
+ --name error_vm_states classification \
+ 'execute[nova:servers.reset_state(vmid, "error")] :-
+ host_down(host),
+ active_instance_in_host(vmid, host)'
+
+Doctor Monitor
+--------------
+
+**Doctor Sample Monitor**
+
+Doctor Monitors are suggested to be placed in one of the controller nodes,
+but those can be put on any host which is reachable to target compute host and
+accessible by the Doctor Inspector.
+You need to configure Monitors for all compute hosts one by one.
+
+Make sure OpenStack env parameters are set properly, so that Doctor Inspector
+can issue admin actions such as compute host force-down and state update of VM.
+
+Then, you can configure the Doctor Monitor as follows (Example for Apex deployment):
+
+.. code-block:: bash
+
+ git clone https://gerrit.opnfv.org/gerrit/doctor -b stable/danube
+ cd doctor/tests
+ INSPECTOR_PORT=12345
+ COMPUTE_HOST='overcloud-novacompute-1.localdomain.com'
+ COMPUTE_IP=192.30.9.5
+ sudo python monitor.py "$COMPUTE_HOST" "$COMPUTE_IP" \
+ "http://127.0.0.1:$INSPECTOR_PORT/events" > monitor.log 2>&1 &
diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst
new file mode 100644
index 00000000..ad89030b
--- /dev/null
+++ b/docs/release/configguide/index.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+*************************
+Doctor Installation Guide
+*************************
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ feature.configuration.rst
diff --git a/docs/release/index.rst b/docs/release/index.rst
new file mode 100644
index 00000000..6b0b43c5
--- /dev/null
+++ b/docs/release/index.rst
@@ -0,0 +1,19 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) 2017 OPNFV.
+
+
+======
+Doctor
+======
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ ./installation/index.rst
+ ./userguide/index.rst
+
+Indices
+=======
+* :ref:`search`
diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst
new file mode 100644
index 00000000..eff14e58
--- /dev/null
+++ b/docs/release/installation/index.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+********************
+Doctor Release Notes
+********************
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ releasenotes.rst
diff --git a/docs/release/installation/releasenotes.rst b/docs/release/installation/releasenotes.rst
new file mode 100644
index 00000000..efb7b08c
--- /dev/null
+++ b/docs/release/installation/releasenotes.rst
@@ -0,0 +1,113 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+=====================================
+OPNFV Doctor release notes (Danube)
+=====================================
+
+Version history
+===============
+
++------------+--------------+------------+-------------+
+| **Date** | **Ver.** | **Author** | **Comment** |
++============+==============+============+=============+
+| 2016-XX-XX | Danube 1.0 | ... | |
++------------+--------------+------------+-------------+
+
+Important notes
+===============
+
+OPNFV Doctor project started as a requirement project and identified gaps
+between "as-is" open source software (OSS) and an "ideal" platform for NFV.
+Based on this analysis, the Doctor project proposed missing features to
+upstream OSS projects. After those features were implemented, OPNFV installer
+projects integrated the features to the OPNFV platform and the OPNFV
+infra/testing projects verified the functionalities in the OPNFV Labs.
+
+This document provides an overview of the Doctor project in the OPNFV Danube
+release, including new features, known issues and documentation updates.
+
+New features
+============
+
+* **FEATURE 1**
+
+ TODO: add description including pointer to `feature1`_ and explain what it is about.
+
+.. _feature1: https://review.openstack.org/#/c/....../
+
+Installer support and verification status
+=========================================
+
+Integrated features
+-------------------
+
+Minimal Doctor functionality of VIM is available in the OPNFV platform from
+the Brahmaputra release. The basic Doctor framework in VIM consists of a
+Controller (Nova) and a Notifier (Ceilometer+Aodh) along with a sample
+Inspector and Monitor developed by the Doctor team.
+
+From the Danube release, key integrated features are:
+
+* ...
+
+* ...
+
+OPNFV installer support matrix
+------------------------------
+
+In the Brahmaputra release, only one installer (Apex) supported the deployment
+of the basic doctor framework by configuring Doctor features. In the Danube
+release, integration of Doctor features progressed in other OPNFV installers.
+
+TODO: TABLE TO BE UPDATED!
+
++-----------+-------------------+--------------+-----------------+------------------+
+| Installer | Aodh | Nova: Force | Nova: Get valid | Congress |
+| | integration | compute down | service status | integration |
++===========+===================+==============+=================+==================+
+| Apex | Available | Available | Available | Available |
+| | | | (`DOCTOR-67`_), | (`APEX-135`_, |
+| | | | Verified only | `APEX-158`_), |
+| | | | for admin users | Not Verified |
++-----------+-------------------+--------------+-----------------+------------------+
+| Fuel | Available | Available | Available, | N/A |
+| | (`DOCTOR-58`_), | | Verified only | (`FUEL-119`_) |
+| | Not verified | | for admin users | |
++-----------+-------------------+--------------+-----------------+------------------+
+| Joid | Available | TBC | TBC | TBC |
+| | (`JOID-76`_), | | | (`JOID-73`_) |
+| | Not verified | | | |
++-----------+-------------------+--------------+-----------------+------------------+
+| Compass | Available | TBC | TBC | N/A |
+| | (`COMPASS-357`_), | | | (`COMPASS-367`_) |
+| | Not verified | | | |
++-----------+-------------------+--------------+-----------------+------------------+
+
+.. _DOCTOR-67: https://jira.opnfv.org/browse/DOCTOR-67
+.. _APEX-135: https://jira.opnfv.org/browse/APEX-135
+.. _APEX-158: https://jira.opnfv.org/browse/APEX-158
+.. _DOCTOR-58: https://jira.opnfv.org/browse/DOCTOR-58
+.. _FUEL-119: https://jira.opnfv.org/browse/FUEL-119
+.. _JOID-76: https://jira.opnfv.org/browse/JOID-76
+.. _JOID-73: https://jira.opnfv.org/browse/JOID-73
+.. _COMPASS-357: https://jira.opnfv.org/browse/COMPASS-357
+.. _COMPASS-367: https://jira.opnfv.org/browse/COMPASS-367
+
+Note: 'Not verified' means that we didn't verify the functionality by having
+our own test scenario running in OPNFV CI pipeline yet.
+
+Documentation updates
+=====================
+
+* **Update 1**
+
+ Description including pointer to JIRA ticket (`DOCTOR-46`_).
+
+.. _DOCTOR-46: https://jira.opnfv.org/browse/DOCTOR-46
+
+
+Known issues
+============
+
+* ...
diff --git a/docs/release/installation/releasenotes_colorado.rst b/docs/release/installation/releasenotes_colorado.rst
new file mode 100644
index 00000000..505fbdb5
--- /dev/null
+++ b/docs/release/installation/releasenotes_colorado.rst
@@ -0,0 +1,170 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+=====================================
+OPNFV Doctor release notes (Colorado)
+=====================================
+
+Version history
+===============
+
++------------+--------------+------------+-------------+
+| **Date** | **Ver.** | **Author** | **Comment** |
++============+==============+============+=============+
+| 2016-09-19 | Colorado 1.0 | Ryota Mibu | |
++------------+--------------+------------+-------------+
+
+Important notes
+===============
+
+OPNFV Doctor project started as a requirement project and identified gaps
+between "as-is" open source software (OSS) and an "ideal" platform for NFV.
+Based on this analysis, the Doctor project proposed missing features to
+upstream OSS projects. After those features were implemented, OPNFV installer
+projects integrated the features to the OPNFV platform and the OPNFV
+infra/testing projects verified the functionalities in the OPNFV Labs.
+
+This document provides an overview of the Doctor project in the OPNFV Colorado
+release, including new features, known issues and documentation updates.
+
+New features
+============
+
+* **Congress as a Doctor Inspector**
+
+ Since `Doctor driver`_ in OpenStack Congress has been implemented in Mitaka,
+ OpenStack Congress can now take the role of the Doctor Inspector to correlate
+ an error in a physical resource to the affected virtual resource(s)
+ immediately.
+
+.. _Doctor driver: https://review.openstack.org/#/c/314915/
+
+Installer support and verification status
+=========================================
+
+Integrated features
+-------------------
+
+Minimal Doctor functionality of VIM is available in the OPNFV platform from
+the Brahmaputra release. The basic Doctor framework in VIM consists of a
+Controller (Nova) and a Notifier (Ceilometer+Aodh) along with a sample
+Inspector and Monitor developed by the Doctor team.
+From the Colorado release, key integrated features are:
+
+* Immediate notification upon state update of virtual resource enabled by
+ Ceilometer and Aodh (Aodh integration)
+
+* Consistent state awareness improved by having nova API to mark nova-compute
+ service down (Nova: Force compute down)
+
+* Consistent state awareness improved by exposing host status in server (VM)
+ information via Nova API (Nova: Get valid service status)
+
+* OpenStack Congress enabling policy-based flexible failure correlation
+ (Congress integration)
+
+OPNFV installer support matrix
+------------------------------
+
+In the Brahmaputra release, only one installer (Apex) supported the deployment
+of the basic doctor framework by configuring Doctor features. In the Colorado
+release, integration of Doctor features progressed in other OPNFV installers.
+
++-----------+-------------------+--------------+-----------------+------------------+
+| Installer | Aodh | Nova: Force | Nova: Get valid | Congress |
+| | integration | compute down | service status | integration |
++===========+===================+==============+=================+==================+
+| Apex | Available | Available | Available | Available |
+| | | | (`DOCTOR-67`_), | (`APEX-135`_, |
+| | | | Verified only | `APEX-158`_), |
+| | | | for admin users | Not Verified |
++-----------+-------------------+--------------+-----------------+------------------+
+| Fuel | Available | Available | Available, | N/A |
+| | (`DOCTOR-58`_), | | Verified only | (`FUEL-119`_) |
+| | Not verified | | for admin users | |
++-----------+-------------------+--------------+-----------------+------------------+
+| Joid | Available | TBC | TBC | TBC |
+| | (`JOID-76`_), | | | (`JOID-73`_) |
+| | Not verified | | | |
++-----------+-------------------+--------------+-----------------+------------------+
+| Compass | Available | TBC | TBC | N/A |
+| | (`COMPASS-357`_), | | | (`COMPASS-367`_) |
+| | Not verified | | | |
++-----------+-------------------+--------------+-----------------+------------------+
+
+.. _DOCTOR-67: https://jira.opnfv.org/browse/DOCTOR-67
+.. _APEX-135: https://jira.opnfv.org/browse/APEX-135
+.. _APEX-158: https://jira.opnfv.org/browse/APEX-158
+.. _DOCTOR-58: https://jira.opnfv.org/browse/DOCTOR-58
+.. _FUEL-119: https://jira.opnfv.org/browse/FUEL-119
+.. _JOID-76: https://jira.opnfv.org/browse/JOID-76
+.. _JOID-73: https://jira.opnfv.org/browse/JOID-73
+.. _COMPASS-357: https://jira.opnfv.org/browse/COMPASS-357
+.. _COMPASS-367: https://jira.opnfv.org/browse/COMPASS-367
+
+Note: 'Not verified' means that we didn't verify the functionality by having
+our own test scenario running in OPNFV CI pipeline yet.
+
+Documentation updates
+=====================
+
+* **Alarm comparison**
+
+ A report on the gap analysis across alarm specifications in ETSI NFV IFA,
+ OPNFV Doctor and OpenStack Aodh has been added, along with some proposals
+ on how to improve the alignment between SDO specification and OSS
+ implementation as a future work (`DOCTOR-46`_).
+
+.. _DOCTOR-46: https://jira.opnfv.org/browse/DOCTOR-46
+
+* **Description of test scenario**
+
+ The description of the Doctor scenario, which is running as one of the
+ feature verification scenarios in Functest, has been updated (`DOCTOR-53`_).
+
+.. _DOCTOR-53: https://jira.opnfv.org/browse/DOCTOR-53
+
+* **Neutron port status update**
+
+ Design documentation for port status update has been added, intending to
+ propose new features to OpenStack Neutron.
+
+* **SB I/F specification**
+
+ The initial specification of the Doctor southbound interface, which is for
+ the Inspector to receive event messages from Monitors, has been added
+ (`DOCTOR-17`_).
+
+.. _DOCTOR-17: https://jira.opnfv.org/browse/DOCTOR-17
+
+Known issues
+============
+
+* **Aodh 'event-alarm' is not available as default (Fuel)**
+
+ In Fuel 9.0, Aodh integration for 'event-alarm' is not completed.
+ Ceilometer and Nova would be mis-configured and cannot pass event
+ notification to Aodh.
+ You can use `fuel-plugin-doctor`_ to correct Ceilometer and Nova
+ configuration as a workaround. See `DOCTOR-62`_.
+
+.. _fuel-plugin-doctor: https://github.com/openzero-zte/fuel-plugin-doctor
+.. _DOCTOR-62: https://jira.opnfv.org/browse/DOCTOR-62
+
+* **Security notice**
+
+ Security notice has been raised in [*]_. Please insure that the debug option
+ of Flask is set to False, before running in production.
+
+.. [*] http://lists.opnfv.org/pipermail/opnfv-tech-discuss/2016-September/012610.html
+
+* **Performance issue in correct resource status (Fuel)**
+
+ Although the Doctor project is aiming to ensure that the time interval
+ between detection and notification to the user is less than 1 second, we
+ observed that it takes more than 2 seconds in the default OPNFV deployment
+ using the Fuel installer [*]_.
+ This issue will be solved by checking the OpenStack configuration and
+ improving Doctor testing scenario.
+
+.. [*] http://lists.opnfv.org/pipermail/opnfv-tech-discuss/2016-September/012542.html
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
new file mode 100644
index 00000000..4ae521bd
--- /dev/null
+++ b/docs/release/userguide/feature.userguide.rst
@@ -0,0 +1,44 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Doctor capabilities and usage
+=============================
+Immediate Notification
+----------------------
+
+Immediate notification can be used by creating 'event' type alarm via
+OpenStack Alarming (Aodh) API with relevant internal components support.
+
+See, upstream spec document:
+http://specs.openstack.org/openstack/ceilometer-specs/specs/liberty/event-alarm-evaluator.html
+
+An example of a consumer of this notification can be found in the Doctor
+repository. It can be executed as follows:
+
+.. code-block:: bash
+
+ git clone https://gerrit.opnfv.org/gerrit/doctor -b stable/danube
+ cd doctor/tests
+ CONSUMER_PORT=12346
+ python consumer.py "$CONSUMER_PORT" > consumer.log 2>&1 &
+
+Consistent resource state awareness
+-----------------------------------
+
+Resource state of compute host can be changed/updated according to a trigger
+from a monitor running outside of OpenStack Compute (Nova) by using
+force-down API.
+
+See
+http://artifacts.opnfv.org/doctor/danube/manuals/mark-host-down_manual.html
+for more detail.
+
+Valid compute host status given to VM owner
+-------------------------------------------
+
+The resource state of a compute host can be retrieved by a user with the
+OpenStack Compute (Nova) servers API.
+
+See
+http://artifacts.opnfv.org/doctor/danube/manuals/get-valid-server-state.html
+for more detail.
diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst
new file mode 100644
index 00000000..c6830fd1
--- /dev/null
+++ b/docs/release/userguide/index.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+*****************
+Doctor User Guide
+*****************
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ feature.userguide.rst