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.yaml`` (this is an API version, not a software version; no need to bump on patch changes)
  43
  44 7) in the it/dep repo that contains a1 helm chart, ``values.yaml``, ``Chart.yml``
  45
  46
  47 Version bumping rmr
  48 ====================
  49 rmr is a critical dependency of A1. Bumping the rmr version dependency requires changes in:
  50
  51 1) ``Dockerfile``
  52
  53 2) ``Dockerfile-Unit-Test``
  54
  55 3) ``integration_tests/Dockerfile``
  56
  57 rmr-python is the python binding to rmr . Installing rmr per the above does not install it.
  58 Bumping the rmr python version dependency requires changes in:
  59
  60 1) ``setup.py``
  61
  62 2) ``integration_tests/Dockerfile``
  63
  64 Run the integration tests after attempting this.
  65
  66
  67 Unit Testing
  68 ============
  69 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.
  70 Also, this requires the python packages ``tox`` and ``pytest``.
  71
  72 ::
  73
  74    tox
  75    open htmlcov/index.html
  76
  77 Alternatively, you can run the unit tests in Docker (this is somewhat less nice because you don't get the pretty HTML)
  78
  79 ::
  80
  81    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
  82
  83 Integration testing
  84 ===================
  85 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.
  86
  87 Unlike the unit tests, however, this does not require rmr to be installed on the base system, as everything
  88 runs in Docker, and the Dockerfiles provide/install rmr.
  89
  90 First, build the latest A1 you are testing (from the root):
  91 ::
  92
  93     docker build  --no-cache -t a1:latest .
  94
  95 Note that this step also runs the unit tests, since running the unit tests are part of the Dockerfile for A1.
  96
  97 If you've never run the integration tests before, build the test receiver, which is referenced in the helm chart:
  98 ::
  99
 100     cd integration_tests
 101     docker build  --no-cache -t testreceiver:latest .
 102
 103 Finally, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
 104 ::
 105
 106    tox -c tox-integration.ini
 107
 108 This script:
 109 1. Deploys 3 helm charts into a local kubernetes installation
 110 2. Port forwards a pod ClusterIP to localhost
 111 3. Uses “tavern” to run some tests against the server
 112 4. Barrages the server with apache bench
 113 5. Tears everything down
 114
 115 Unless you're a core A1 developer, you should probably stop here. The below instructions
 116 are for running A1 locally, without docker, and is much more involved (however useful when developing a1).
 117
 118 Running locally
 119 ===============
 120
 121 1. Before this will work, for the first time on that machine, run ``./install_deps.sh``
 122
 123 2. It also requires rmr-python installed. (The dockerfile does this)
 124
 125 3. Create a ``local.rt`` file and copy it into ``/opt/route/local.rt``.
 126    Note, the example one in ``integration_tests`` will need to be modified for
 127    your scenario and machine.
 128
 129 4. Copy a ric manifest into ``/opt/ricmanifest.json`` and an rmr mapping
 130    table into ``/opt/rmr_string_int_mapping.txt``. You can use the test
 131    ones packaged if you want:
 132
 133    ::
 134
 135      cp tests/fixtures/ricmanifest.json /opt/ricmanifest.json
 136      cp tests/fixtures/rmr_string_int_mapping.txt /opt/rmr_string_int_mapping.txt
 137
 138 5. Then:
 139
 140    ::
 141
 142    sudo pip install -e .
 143    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;
 144    /usr/bin/run.py
 145
 146
 147 There are also two test receivers in ``integration_tests`` you can run locally.
 148 The first is meant to be used with the ``control_admission`` policy
 149 (that comes in test fixture ric manifest):
 150
 151 ::
 152
 153    set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; python receiver.py
 154
 155 The second can be used against the ``test_policy`` policy to test the
 156 async nature of A1, and to test race conditions. You can start it with
 157 several env variables as follows:
 158
 159 ::
 160
 161    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
 162
 163 To test the async nature of A1, trigger a call to ``test_policy``, which
 164 will target the delayed receiver, then immediately call
 165 ``control_admission``. The ``control_admission`` policy return should be
 166 returned immediately, whereas the ``test_policy`` should return after
 167 about ``TEST_RCV_SEC_DELAY 5``. The ``test_policy`` should not block A1
 168 while it is sleeping, and both responses should be correct.
 169
 170 ::
 171
 172    curl -v -X PUT -H "Content-Type: application/json" -d '{}' localhost:10000/ric/policies/test_policy
 173    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
 174    curl -v localhost:10000/ric/policies/admission_control_policy
 175    curl -v localhost:10000/a1-p/healthcheck