diff options
Diffstat (limited to 'docs/release')
| -rw-r--r-- | docs/release/configguide/feature.configuration.rst | 104 | ||||
| -rw-r--r-- | docs/release/configguide/index.rst | 12 | ||||
| -rw-r--r-- | docs/release/index.rst | 19 | ||||
| -rw-r--r-- | docs/release/installation/index.rst | 12 | ||||
| -rw-r--r-- | docs/release/installation/releasenotes.rst | 113 | ||||
| -rw-r--r-- | docs/release/installation/releasenotes_colorado.rst | 170 | ||||
| -rw-r--r-- | docs/release/userguide/feature.userguide.rst | 44 | ||||
| -rw-r--r-- | docs/release/userguide/index.rst | 12 |
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 |