diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/overview/testing.rst | 33 | ||||
| -rw-r--r-- | docs/release/configguide/feature.configuration.rst | 62 | ||||
| -rw-r--r-- | docs/release/userguide/feature.userguide.rst | 64 |
3 files changed, 93 insertions, 66 deletions
diff --git a/docs/development/overview/testing.rst b/docs/development/overview/testing.rst index 8d0e90e6..98be43e9 100644 --- a/docs/development/overview/testing.rst +++ b/docs/development/overview/testing.rst @@ -10,7 +10,7 @@ for doctor CI. You need to install OpenStack and other OPNFV components except Doctor Sample Inspector, Sample Monitor and Sample Consumer, as these will be launched in -this script. You are encouraged to use OPNFV offcial installers, but you can +this script. You are encouraged to use OPNFV official installers, but you can also deploy all components with other installers such as devstack or manual operation. In those cases, the versions of all components shall be matched with the versions of them in OPNFV specific release. @@ -18,38 +18,16 @@ the versions of them in OPNFV specific release. Run Test Script =============== -Doctor project has own testing script under `doctor/tests`_. This test script +Doctor project has own testing script under `doctor/doctor_tests`_. This test script can be used for functional testing agained an OPNFV deployment. -.. _doctor/tests: https://gerrit.opnfv.org/gerrit/gitweb?p=doctor.git;a=tree;f=tests; +.. _doctor/doctor_tests: https://git.opnfv.org/doctor/tree/doctor_tests Before running this script, make sure OpenStack env parameters are set properly -following `OpenStack CLI manual`_, so that Doctor Inspector can operate +(See e.g. `OpenStackClient Configuration`_), so that Doctor Inspector can operate OpenStack services. -.. _OpenStack CLI manual: https://docs.openstack.org/user-guide/common/cli-set-environment-variables-using-openstack-rc.html - -Run Bash Test Script -~~~~~~~~~~~~~~~~~~~~ - -You can run the bash script as follows: - -.. code-block:: bash - - git clone https://gerrit.opnfv.org/gerrit/doctor - cd doctor/tests - export INSTALLER_TYPE=local - export INSPECTOR_TYPE=sample - ./run.sh - -INSTALLER_TYPE can be 'apex', 'fuel', 'joid' and 'local'(default). If you are -not using OPNFV installers in this option, chose 'local'. -INSPECTOR_TYPE can be specified either 'sample'(default) or 'congress'. - -For testing with stable version, checkout stable branch of doctor repo before -'./run.sh'. - -The bash test script will be deprecated(only bug fixes) after E Release. +.. _OpenStackClient Configuration: https://docs.openstack.org/python-openstackclient/latest/configuration/index.html Run Python Test Script ~~~~~~~~~~~~~~~~~~~~~~ @@ -82,7 +60,6 @@ Functest container. You can run the Doctor test with the following steps: -e INSTALLER_IP=${INSTALLER_IP} \ -e INSPECTOR_TYPE=sample \ docker.io/opnfv/functest-features:${DOCKER_TAG} /bin/bash - docker exec <container_id> functest env prepare docker exec <container_id> functest testcase run doctor-notification See `Functest Userguide`_ for more information. diff --git a/docs/release/configguide/feature.configuration.rst b/docs/release/configguide/feature.configuration.rst index ddd9c7c1..64928eea 100644 --- a/docs/release/configguide/feature.configuration.rst +++ b/docs/release/configguide/feature.configuration.rst @@ -10,34 +10,38 @@ 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`_. +steps for all supported installers under `doctor/doctor_tests/installer`_. -.. _doctor/tests: https://gerrit.opnfv.org/gerrit/gitweb?p=doctor.git;a=tree;f=tests; +.. _doctor/doctor_tests/installer: https://git.opnfv.org/doctor/tree/doctor_tests/installer Doctor Inspector ---------------- -You need to configure one of Doctor Inspector below. +You need to configure one of Doctor Inspectors below. You can also learn detailed steps for +all supported Inspectors under `doctor/doctor_tests/inspector`_. -**Doctor Sample Inspector** +.. _doctor/doctor_tests/inspector: https://git.opnfv.org/doctor/tree/doctor_tests/inspector + + +**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). +Sample Inspector is suggested to be placed in one of the controller nodes, +but it can be put on any host where Sample Inspector can reach and access +the OpenStack Controllers (e.g. Nova, Neutron). -Make sure OpenStack env parameters are set properly, so that Doctor Inspector +Make sure OpenStack env parameters are set properly, so that Sample Inspector can issue admin actions such as compute host force-down and state update of VM. -Then, you can configure Doctor Inspector as follows: +Then, you can configure Sample Inspector as follows: .. code-block:: bash - git clone https://gerrit.opnfv.org/gerrit/doctor -b stable/danube - cd doctor/tests + git clone https://gerrit.opnfv.org/gerrit/doctor + cd doctor/doctor_tests/inspector INSPECTOR_PORT=12345 - python inspector.py $INSPECTOR_PORT > inspector.log 2>&1 & + python sample.py $INSPECTOR_PORT > inspector.log 2>&1 & **Congress** @@ -45,9 +49,9 @@ 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: https://governance.openstack.org/tc/reference/projects/congress.html -Congress is deployed by OPNFV installers. You need to enable doctor +Congress is deployed by OPNFV Apex installer. 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 @@ -55,7 +59,12 @@ that host from ACTIVE to ERROR state. .. code-block:: bash - openstack congress datasource create doctor doctor + openstack congress datasource create doctor "doctor" + + openstack congress datasource create --config api_version=$NOVA_MICRO_VERSION \ + --config username=$OS_USERNAME --config tenant_name=$OS_TENANT_NAME \ + --config password=$OS_PASSWORD --config auth_url=$OS_AUTH_URL \ + nova "nova21" openstack congress policy rule create \ --name host_down classification \ @@ -125,27 +134,28 @@ support the Doctor use case. This can be done in a few steps: 4. Restart the vitrage-graph and vitrage-notifier services -Doctor Monitor --------------- - -**Doctor Sample Monitor** +Doctor Monitors +--------------- 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. +You need to configure Monitors for all compute hosts one by one. You can also learn detailed +steps for all supported monitors under `doctor/doctor_tests/monitor`_. -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. +.. _doctor/doctor_tests/monitor: https://git.opnfv.org/doctor/tree/doctor_tests/monitor -Then, you can configure the Doctor Monitor as follows (Example for Apex deployment): +**Sample Monitor** +You can configure the Sample Monitor as follows (Example for Apex deployment): .. code-block:: bash - git clone https://gerrit.opnfv.org/gerrit/doctor -b stable/danube - cd doctor/tests + git clone https://gerrit.opnfv.org/gerrit/doctor + cd doctor/doctor_tests/monitor INSPECTOR_PORT=12345 COMPUTE_HOST='overcloud-novacompute-1.localdomain.com' COMPUTE_IP=192.30.9.5 - sudo python monitor.py "$COMPUTE_HOST" "$COMPUTE_IP" \ + sudo python sample.py "$COMPUTE_HOST" "$COMPUTE_IP" \ "http://127.0.0.1:$INSPECTOR_PORT/events" > monitor.log 2>&1 & + +**Collectd Monitor** diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index 0dde4f26..0783e0fd 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -9,7 +9,7 @@ Doctor. The implementation is based on OpenStack and related components. The Monitor can be realized by a sample Python-based implementation provided in the Doctor code repository. The Controller is realized by OpenStack Nova, Neutron and Cinder for compute, network and storage, respectively. The Inspector can be -realized by OpenStack Congress or a sample Python-based implementation also +realized by OpenStack Congress, Vitrage or a sample Python-based implementation also available in the code repository of Doctor. The Notifier is realized by OpenStack Aodh. @@ -26,18 +26,21 @@ 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 +See: +- Upstream spec document: +https://specs.openstack.org/openstack/ceilometer-specs/specs/liberty/event-alarm-evaluator.html +- Aodh official documentation: +https://docs.openstack.org/aodh/latest 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 + git clone https://gerrit.opnfv.org/gerrit/doctor + cd doctor/doctor_tests/consumer CONSUMER_PORT=12346 - python consumer.py "$CONSUMER_PORT" > consumer.log 2>&1 & + python sample.py "$CONSUMER_PORT" > consumer.log 2>&1 & Consistent resource state awareness ----------------------------------- @@ -46,9 +49,10 @@ 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. +See: +* Upstream spec document: https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/mark-host-down.html +* Upstream Compute API reference document: https://developer.openstack.org/api-ref/compute +* Doctor Mark Host Down Manual: https://git.opnfv.org/doctor/tree/docs/development/manuals/mark-host-down_manual.rst Valid compute host status given to VM owner ------------------------------------------- @@ -56,6 +60,42 @@ 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. +See: +* Upstream spec document: https://specs.openstack.org/openstack/nova-specs/specs/mitaka/implemented/get-valid-server-state.html +* Upstream Compute API reference document: https://developer.openstack.org/api-ref/compute +* Doctor Get Valid Server State Manual: https://git.opnfv.org/doctor/tree/docs/development/manuals/get-valid-server-state.rst + +Port data plane status update +----------------------------- + +Port data plane status can be changed/updated in the case of issues in the underlying data plane +affecting connectivity from/to Neutron ports. + +See: +* Upstream spec document: https://specs.openstack.org/openstack/neutron-specs/specs/pike/port-data-plane-status.html +* Upstream Networking API reference document: https://developer.openstack.org/api-ref/network + +Doctor driver (Congress) +------------------------ + +The Doctor driver can be notified about NFVI failures that have been detected by monitoring systems. + +See: +* Upstream spec document: https://specs.openstack.org/openstack/congress-specs/specs/mitaka/push-type-datasource-driver.html +* Congress official documentation: https://docs.openstack.org/congress/latest + +Event API (Vitrage) +------------------- +With this API, monitoring systems can push events to the Doctor datasource. + +See: +* Upstream spec document: https://specs.openstack.org/openstack/vitrage-specs/specs/ocata/event-api.html +* Vitrage official documentation: https://docs.openstack.org/vitrage/latest + +Doctor datasource (Vitrage) +--------------------------- +After receiving events from monitoring systems, the Doctor datasource identifies the affected resources based on the resource topology. + +See: +* Upstream spec document: https://specs.openstack.org/openstack/vitrage-specs/specs/ocata/doctor-datasource.html + |