Merge branch 'development'

[ric-plt/a1.git] / docs / developer-guide.rst

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index 60c1d9a..38722da 100644 (file)
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -1,25 +1,15 @@
-.. ==================================================================================
-..       Copyright (c) 2019 Nokia
-..       Copyright (c) 2018-2019 AT&T Intellectual Property.
-..
-..   Licensed under the Apache License, Version 2.0 (the "License");
-..   you may not use this file except in compliance with the License.
-..   You may obtain a copy of the License at
-..
-..          http://www.apache.org/licenses/LICENSE-2.0
-..
-..   Unless required by applicable law or agreed to in writing, software
-..   distributed under the License is distributed on an "AS IS" BASIS,
-..   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-..   See the License for the specific language governing permissions and
-..   limitations under the License.
-.. ==================================================================================
-
-A1 Dev Guide
-============
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Developer-Guide
+===============
+
+.. contents::
+   :depth: 3
+   :local:

 
 Tech Stack
 
 Tech Stack

-==========
+----------

 
 -  OpenAPI3
 -  Connexion
 
 -  OpenAPI3
 -  Connexion


@@ -27,7 +17,7 @@ Tech Stack
 -  Python3.7
 
 Version bumping
 -  Python3.7
 
 Version bumping

-===============
+---------------

 
 This project follows semver. When changes are made, the versions are in:
 
 
 This project follows semver. When changes are made, the versions are in:
 


@@ -39,21 +29,49 @@ This project follows semver. When changes are made, the versions are in:
 
 4) ``integration_tests/a1mediator/Chart.yaml``
 
 
 4) ``integration_tests/a1mediator/Chart.yaml``
 

-6) ``a1/openapi.yml`` (this is an API version, not a software version)
+6) ``a1/openapi.yaml`` (this is an API version, not a software version; no need to bump on patch changes)

 
 7) in the it/dep repo that contains a1 helm chart, ``values.yaml``, ``Chart.yml``
 
 
 7) in the it/dep repo that contains a1 helm chart, ``values.yaml``, ``Chart.yml``
 

+
+Version bumping rmr
+--------------------
+rmr is a critical dependency of A1. Bumping the rmr version dependency requires changes in:
+
+1) ``Dockerfile``
+
+2) ``Dockerfile-Unit-Test``
+
+3) ``integration_tests/Dockerfile``
+
+rmr-python is the python binding to rmr . Installing rmr per the above does not install it.
+Bumping the rmr python version dependency requires changes in:
+
+1) ``setup.py``
+
+2) ``integration_tests/Dockerfile``
+
+Run the integration tests after attempting this.
+
+

 Unit Testing
 Unit Testing

-============
-Note, this requires rmr to be installed on the system executing the tests. Also, this requires the python packages ``tox`` and ``pytest``.
+------------
+Note,  before this will work, for the first time on the machine running the tests, run ``./install_deps.sh``. This is only needed once on the machine.
+Also, this requires the python packages ``tox`` and ``pytest``.

 
 ::
 
    tox
    open htmlcov/index.html
 
 
 ::
 
    tox
    open htmlcov/index.html
 

+Alternatively, you can run the unit tests in Docker (this is somewhat less nice because you don't get the pretty HTML)
+
+::
+
+   docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
+

 Integration testing
 Integration testing

-===================
+-------------------

 This tests A1’s external API with two test receivers. This depends on helm+k8s, meaning you cannot run this if this is not installed.
 
 Unlike the unit tests, however, this does not require rmr to be installed on the base system, as everything
 This tests A1’s external API with two test receivers. This depends on helm+k8s, meaning you cannot run this if this is not installed.
 
 Unlike the unit tests, however, this does not require rmr to be installed on the base system, as everything


@@ -72,8 +90,6 @@ If you've never run the integration tests before, build the test receiver, which
     cd integration_tests
     docker build  --no-cache -t testreceiver:latest .
 
     cd integration_tests
     docker build  --no-cache -t testreceiver:latest .
 

-You do not need the "bombarder" image as they are not currently used in the integration tests (that is more for load testing).
-

 Finally, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
 ::
 
 Finally, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
 ::
 


@@ -86,17 +102,18 @@ This script:
 4. Barrages the server with apache bench
 5. Tears everything down
 
 4. Barrages the server with apache bench
 5. Tears everything down
 

+Unless you're a core A1 developer, you should probably stop here. The below instructions
+are for running A1 locally, without docker, and is much more involved (however useful when developing a1).
+

 Running locally
 Running locally

-===============
+---------------

 
 

-1. This requires that RMR is installed on the base system. (the
-   Dockerfile does this when running in Docker)
+1. Before this will work, for the first time on that machine, run ``./install_deps.sh``

 
 

-2. It also requires rmr-python >= 0.10.1 installed. (The dockerfile also
-   does this)
+2. It also requires rmr-python installed. (The dockerfile does this)

 
 3. Create a ``local.rt`` file and copy it into ``/opt/route/local.rt``.
 
 3. Create a ``local.rt`` file and copy it into ``/opt/route/local.rt``.

-   Note, the example one in ``local_tests`` will need to be modified for
+   Note, the example one in ``integration_tests`` will need to be modified for

    your scenario and machine.
 
 4. Copy a ric manifest into ``/opt/ricmanifest.json`` and an rmr mapping
    your scenario and machine.
 
 4. Copy a ric manifest into ``/opt/ricmanifest.json`` and an rmr mapping


@@ -105,19 +122,17 @@ Running locally
 
    ::
 
 
    ::
 

-     cp tests/fixtures/ricmanifest.json /opt/ricmanifest.json cp
-     tests/fixtures/rmr_string_int_mapping.txt
-     /opt/rmr_string_int_mapping.txt
+     cp tests/fixtures/ricmanifest.json /opt/ricmanifest.json
+     cp tests/fixtures/rmr_string_int_mapping.txt /opt/rmr_string_int_mapping.txt

 
 5. Then:
 
 
 5. Then:
 

-   sudo pip install –ignore-installed .; set -x LD_LIBRARY_PATH
-   /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x
-   RMR_RCV_RETRY_INTERVAL 500; set -x RMR_RETRY_TIMES 10;
-   /usr/bin/run.py
+   ::
+
+     sudo pip install -e .
+     set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x RMR_RCV_RETRY_INTERVAL 500; set -x RMR_RETRY_TIMES 10;
+     /usr/bin/run.py

 
 

-Testing locally
-===============

 
 There are also two test receivers in ``integration_tests`` you can run locally.
 The first is meant to be used with the ``control_admission`` policy
 
 There are also two test receivers in ``integration_tests`` you can run locally.
 The first is meant to be used with the ``control_admission`` policy


@@ -136,7 +151,7 @@ several env variables as follows:
    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x TEST_RCV_PORT 4563; set -x TEST_RCV_RETURN_MINT 10001; set -x TEST_RCV_SEC_DELAY 5; set -x TEST_RCV_RETURN_PAYLOAD '{"ACK_FROM": "DELAYED_TEST", "status": "SUCCESS"}' ; python receiver.py
 
 To test the async nature of A1, trigger a call to ``test_policy``, which
    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x TEST_RCV_PORT 4563; set -x TEST_RCV_RETURN_MINT 10001; set -x TEST_RCV_SEC_DELAY 5; set -x TEST_RCV_RETURN_PAYLOAD '{"ACK_FROM": "DELAYED_TEST", "status": "SUCCESS"}' ; python receiver.py
 
 To test the async nature of A1, trigger a call to ``test_policy``, which

-will target the delayed receicer, then immediately call
+will target the delayed receiver, then immediately call

 ``control_admission``. The ``control_admission`` policy return should be
 returned immediately, whereas the ``test_policy`` should return after
 about ``TEST_RCV_SEC_DELAY 5``. The ``test_policy`` should not block A1
 ``control_admission``. The ``control_admission`` policy return should be
 returned immediately, whereas the ``test_policy`` should return after
 about ``TEST_RCV_SEC_DELAY 5``. The ``test_policy`` should not block A1


@@ -145,12 +160,6 @@ while it is sleeping, and both responses should be correct.
 ::
 
    curl -v -X PUT -H "Content-Type: application/json" -d '{}' localhost:10000/ric/policies/test_policy
 ::
 
    curl -v -X PUT -H "Content-Type: application/json" -d '{}' localhost:10000/ric/policies/test_policy

-   curl -v -X PUT -H "Content-Type: application/json" -d '{"dc_admission_start_time": "10:00:00", "dc_admission_end_time": "11:00:00"}' localhost:10000/ric/policies/control_admission_time
-
-Finally, there is a test “bombarder” that will flood A1 with messages
-with good message types but bad transaction IDs, to test A1’s resilience
-against queue-overflow attacks
-
-::
-
-   set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ;  python bombard.py
+   curl -v -X PUT -H "Content-Type: application/json" -d '{ "enforce":true, "window_length":10, "blocking_rate":20, "trigger_threshold":10 }' localhost:10000/ric/policies/admission_control_policy
+   curl -v localhost:10000/ric/policies/admission_control_policy
+   curl -v localhost:10000/a1-p/healthcheck