docs/developer-guide.rst

   1 .. ==================================================================================
   2 ..       Copyright (c) 2019 Nokia
   3 ..       Copyright (c) 2018-2019 AT&T Intellectual Property.
   4 ..
   5 ..   Licensed under the Apache License, Version 2.0 (the "License");
   6 ..   you may not use this file except in compliance with the License.
   7 ..   You may obtain a copy of the License at
   8 ..
   9 ..          http://www.apache.org/licenses/LICENSE-2.0
  10 ..
  11 ..   Unless required by applicable law or agreed to in writing, software
  12 ..   distributed under the License is distributed on an "AS IS" BASIS,
  13 ..   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 ..   See the License for the specific language governing permissions and
  15 ..   limitations under the License.
  16 .. ==================================================================================
  17
  18 A1 Dev Guide
  19 ============
  20
  21 Tech Stack
  22 ==========
  23
  24 -  OpenAPI3
  25 -  Connexion
  26 -  Flask with Gevent serving
  27 -  Python3.7
  28
  29 Version bumping
  30 ===============
  31
  32 This project follows semver. When changes are made, the versions are in:
  33
  34 1) ``docs/release-notes.rst``
  35
  36 2) ``setup.py``
  37
  38 3) ``container-tag.yaml``
  39
  40 4) ``integration_tests/a1mediator/Chart.yaml``
  41
  42 6) ``a1/openapi.yml`` (this is an API version, not a software version)
  43
  44 7) in the it/dep repo that contains a1 helm chart, ``values.yaml``, ``Chart.yml``
  45
  46 Unit Testing
  47 ============
  48 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.
  49 Also, this requires the python packages ``tox`` and ``pytest``.
  50
  51 ::
  52
  53    tox
  54    open htmlcov/index.html
  55
  56 Alternatively, you can run the unit tests in Docker (this is somewhat less nice because you don't get the pretty HTML)
  57
  58 ::
  59
  60    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
  61
  62 Integration testing
  63 ===================
  64 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.
  65
  66 Unlike the unit tests, however, this does not require rmr to be installed on the base system, as everything
  67 runs in Docker, and the Dockerfiles provide/install rmr.
  68
  69 First, build the latest A1 you are testing (from the root):
  70 ::
  71
  72     docker build  --no-cache -t a1:latest .
  73
  74 Note that this step also runs the unit tests, since running the unit tests are part of the Dockerfile for A1.
  75
  76 If you've never run the integration tests before, build the test receiver, which is referenced in the helm chart:
  77 ::
  78
  79     cd integration_tests
  80     docker build  --no-cache -t testreceiver:latest .
  81
  82 You do not need the "bombarder" image as they are not currently used in the integration tests (that is more for load testing).
  83
  84 Finally, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
  85 ::
  86
  87    tox -c tox-integration.ini
  88
  89 This script:
  90 1. Deploys 3 helm charts into a local kubernetes installation
  91 2. Port forwards a pod ClusterIP to localhost
  92 3. Uses “tavern” to run some tests against the server
  93 4. Barrages the server with apache bench
  94 5. Tears everything down
  95
  96 Unless you're a core A1 developer, you should probably stop here. The below instructions
  97 are for running A1 locally, without docker, and is much more involved (however useful when developing a1).
  98
  99 Running locally
 100 ===============
 101
 102 1. Before this will work, for the first time on that machine, run ``./install_deps.sh``
 103
 104 2. It also requires rmr-python >= 0.10.1 installed. (The dockerfile also
 105    does this)
 106
 107 3. Create a ``local.rt`` file and copy it into ``/opt/route/local.rt``.
 108    Note, the example one in ``integration_tests`` will need to be modified for
 109    your scenario and machine.
 110
 111 4. Copy a ric manifest into ``/opt/ricmanifest.json`` and an rmr mapping
 112    table into ``/opt/rmr_string_int_mapping.txt``. You can use the test
 113    ones packaged if you want:
 114
 115    ::
 116
 117      cp tests/fixtures/ricmanifest.json /opt/ricmanifest.json
 118      cp tests/fixtures/rmr_string_int_mapping.txt /opt/rmr_string_int_mapping.txt
 119
 120 5. Then:
 121
 122    ::
 123
 124    sudo pip install -e .
 125    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;
 126    /usr/bin/run.py
 127
 128
 129 There are also two test receivers in ``integration_tests`` you can run locally.
 130 The first is meant to be used with the ``control_admission`` policy
 131 (that comes in test fixture ric manifest):
 132
 133 ::
 134
 135    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; python receiver.py
 136
 137 The second can be used against the ``test_policy`` policy to test the
 138 async nature of A1, and to test race conditions. You can start it with
 139 several env variables as follows:
 140
 141 ::
 142
 143    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
 144
 145 To test the async nature of A1, trigger a call to ``test_policy``, which
 146 will target the delayed receicer, then immediately call
 147 ``control_admission``. The ``control_admission`` policy return should be
 148 returned immediately, whereas the ``test_policy`` should return after
 149 about ``TEST_RCV_SEC_DELAY 5``. The ``test_policy`` should not block A1
 150 while it is sleeping, and both responses should be correct.
 151
 152 ::
 153
 154    curl -v -X PUT -H "Content-Type: application/json" -d '{}' localhost:10000/ric/policies/test_policy
 155    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
 156    curl -v localhost:10000/ric/policies/admission_control_policy
 157    curl -v localhost:10000/a1-p/healthcheck
 158
 159 Finally, there is a test “bombarder” that will flood A1 with messages
 160 with good message types but bad transaction IDs, to test A1’s resilience
 161 against queue-overflow attacks
 162
 163 ::
 164
 165    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ;  python bombard.py