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) ``a1mediator/values.yaml``
  41
  42 5) ``a1mediator/Chart.yaml``
  43
  44 6) ``a1/openapi.yml``
  45
  46 Running locally
  47 ===============
  48
  49 1. This requires that RMR is installed on the base system. (the
  50    Dockerfile does this when running in Docker)
  51
  52 2. It also requires rmr-python >= 0.10.1 installed. (The dockerfile also
  53    does this)
  54
  55 3. Create a ``local.rt`` file and copy it into ``/opt/route/local.rt``.
  56    Note, the example one in ``local_tests`` will need to be modified for
  57    your scenario and machine.
  58
  59 4. Copy a ric manifest into ``/opt/ricmanifest.json`` and an rmr mapping
  60    table into ``/opt/rmr_string_int_mapping.txt``. You can use the test
  61    ones packaged if you want:
  62
  63    ::
  64
  65      cp tests/fixtures/ricmanifest.json /opt/ricmanifest.json cp
  66      tests/fixtures/rmr_string_int_mapping.txt
  67      /opt/rmr_string_int_mapping.txt
  68
  69 5. Then:
  70
  71    sudo pip install –ignore-installed .; set -x LD_LIBRARY_PATH
  72    /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x
  73    RMR_RCV_RETRY_INTERVAL 500; set -x RMR_RETRY_TIMES 10;
  74    /usr/bin/run.py
  75
  76 Testing locally
  77 ===============
  78
  79 There are also two test receivers in ``integration_tests`` you can run locally.
  80 The first is meant to be used with the ``control_admission`` policy
  81 (that comes in test fixture ric manifest):
  82
  83 ::
  84
  85    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; python receiver.py
  86
  87 The second can be used against the ``test_policy`` policy to test the
  88 async nature of A1, and to test race conditions. You can start it with
  89 several env variables as follows:
  90
  91 ::
  92
  93    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
  94
  95 To test the async nature of A1, trigger a call to ``test_policy``, which
  96 will target the delayed receicer, then immediately call
  97 ``control_admission``. The ``control_admission`` policy return should be
  98 returned immediately, whereas the ``test_policy`` should return after
  99 about ``TEST_RCV_SEC_DELAY 5``. The ``test_policy`` should not block A1
 100 while it is sleeping, and both responses should be correct.
 101
 102 ::
 103
 104    curl -v -X PUT -H "Content-Type: application/json" -d '{}' localhost:10000/ric/policies/test_policy
 105    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
 106
 107 Finally, there is a test “bombarder” that will flood A1 with messages
 108 with good message types but bad transaction IDs, to test A1’s resilience
 109 against queue-overflow attacks
 110
 111 ::
 112
 113    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ;  python bombard.py