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/values.yaml + ``Chart.yaml``
  41
  42 6) ``a1/openapi.yml``
  43
  44 7) in the it/dep repo that contains a1 helm chart, ``values.yaml``, ``Chart.yml``
  45
  46 Unit Testing
  47 ============
  48 Note, this requires rmr to be installed on the system executing the tests. Also, this requires the python packages ``tox`` and ``pytest``.
  49
  50 ::
  51
  52    tox
  53    open htmlcov/index.html
  54
  55 Integration testing
  56 ===================
  57 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.
  58
  59 Unlike the unit tests, however, this does not require rmr to be installed on the base system, as everything
  60 runs in Docker, and the Dockerfiles provide/install rmr.
  61
  62 First, build the latest A1 you are testing (from the root):
  63 ::
  64
  65     docker build  --no-cache -t a1:latest .
  66
  67 Note that this step also runs the unit tests, since running the unit tests are part of the Dockerfile for A1.
  68
  69 If you've never run the integration tests before, build the test receiver, which is referenced in the helm chart:
  70 ::
  71
  72     cd integration_tests
  73     docker build  --no-cache -t testreceiver:latest .
  74
  75 You do not need the "bombarder" image as they are not currently used in the integration tests (that is more for load testing).
  76
  77 Finally, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
  78 ::
  79
  80    tox -c tox-integration.ini
  81
  82 This script:
  83 1. Deploys 3 helm charts into a local kubernetes installation
  84 2. Port forwards a pod ClusterIP to localhost
  85 3. Uses “tavern” to run some tests against the server
  86 4. Barrages the server with apache bench
  87 5. Tears everything down
  88
  89 Running locally
  90 ===============
  91
  92 1. This requires that RMR is installed on the base system. (the
  93    Dockerfile does this when running in Docker)
  94
  95 2. It also requires rmr-python >= 0.10.1 installed. (The dockerfile also
  96    does this)
  97
  98 3. Create a ``local.rt`` file and copy it into ``/opt/route/local.rt``.
  99    Note, the example one in ``local_tests`` will need to be modified for
 100    your scenario and machine.
 101
 102 4. Copy a ric manifest into ``/opt/ricmanifest.json`` and an rmr mapping
 103    table into ``/opt/rmr_string_int_mapping.txt``. You can use the test
 104    ones packaged if you want:
 105
 106    ::
 107
 108      cp tests/fixtures/ricmanifest.json /opt/ricmanifest.json cp
 109      tests/fixtures/rmr_string_int_mapping.txt
 110      /opt/rmr_string_int_mapping.txt
 111
 112 5. Then:
 113
 114    sudo pip install –ignore-installed .; set -x LD_LIBRARY_PATH
 115    /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x
 116    RMR_RCV_RETRY_INTERVAL 500; set -x RMR_RETRY_TIMES 10;
 117    /usr/bin/run.py
 118
 119 Testing locally
 120 ===============
 121
 122 There are also two test receivers in ``integration_tests`` you can run locally.
 123 The first is meant to be used with the ``control_admission`` policy
 124 (that comes in test fixture ric manifest):
 125
 126 ::
 127
 128    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; python receiver.py
 129
 130 The second can be used against the ``test_policy`` policy to test the
 131 async nature of A1, and to test race conditions. You can start it with
 132 several env variables as follows:
 133
 134 ::
 135
 136    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
 137
 138 To test the async nature of A1, trigger a call to ``test_policy``, which
 139 will target the delayed receicer, then immediately call
 140 ``control_admission``. The ``control_admission`` policy return should be
 141 returned immediately, whereas the ``test_policy`` should return after
 142 about ``TEST_RCV_SEC_DELAY 5``. The ``test_policy`` should not block A1
 143 while it is sleeping, and both responses should be correct.
 144
 145 ::
 146
 147    curl -v -X PUT -H "Content-Type: application/json" -d '{}' localhost:10000/ric/policies/test_policy
 148    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
 149
 150 Finally, there is a test “bombarder” that will flood A1 with messages
 151 with good message types but bad transaction IDs, to test A1’s resilience
 152 against queue-overflow attacks
 153
 154 ::
 155
 156    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ;  python bombard.py