docs/Chapter8/Ansible-JSON-Key-Value-Description.rst

   1 .. Modifications Copyright © 2017-2018 AT&T Intellectual Property.
   2
   3 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.
   4    (the "License"); you may not use this documentation except in compliance
   5    with the License. You may obtain a copy of the License at
   6
   7 .. https://creativecommons.org/licenses/by/4.0/
   8
   9 .. Unless required by applicable law or agreed to in writing, software
  10    distributed under the License is distributed on an "AS IS" BASIS,
  11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    See the License for the specific language governing permissions and
  13    limitations under the License.
  14
  15
  16 Ansible JSON Key Value Description
  17 -------------------------------------------------------------
  18
  19 The following provides the key value pairs that must be contained in the
  20 JSON file supporting Ansible action.
  21
  22 Table B1. Ansible JSON File key value description
  23 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  24
  25 +---------------+----------------------+---------+----------------------------+
  26 | **Field Name**| **Description**      | **Type**| **Comment**                |
  27 +===============+======================+=========+============================+
  28 | PlaybookName  | VNF providor must    |Mandatory|Currently following         |
  29 |               | list name of the     |         |Ansible standard            |
  30 |               | playbook relative    |         |naming, where main          |
  31 |               | path used to         |         |playbook is always          |
  32 |               | execute the VNF      |         |named site.yml, and         |
  33 |               | action.              |         |directory name where        |
  34 |               |                      |         |this main playbook resides, |
  35 |               |                      |         |is named after the          |
  36 |               |                      |         |command/action playbook     |
  37 |               |                      |         |performs, in lower case,    |
  38 |               |                      |         |example, configure.         |
  39 +---------------+----------------------+---------+----------------------------+
  40 | Action        | Name of VNF action.  | Optional|                            |
  41 +---------------+----------------------+---------+----------------------------+
  42 | EnvParameters | A JSON dictionary    | Optional|Depends on the VNF action.  |
  43 |               | which should list key|         |                            |
  44 |               | value pairs to be    |         |Attribute names (variable   |
  45 |               | passed to the Ansible|         |names) passed to Ansible    |
  46 |               | playbook. These      |         |shall follow Ansible valid  |
  47 |               | values would         |         |variable names: "Variable   |
  48 |               | correspond to        |         |names should be letters,    |
  49 |               | instance specific    |         |numbers, and underscores.   |
  50 |               | parameters that a    |         |Variables should always     |
  51 |               | playbook may need to |         |start with a letter."       |
  52 |               | execute an action.   |         |                            |
  53 +---------------+----------------------+---------+----------------------------+
  54 | NodeList      |Ansible inventory     | Optional|If not provided, pre-loaded |
  55 |               |hosts file with       |         |(VNF) inventory hosts       |
  56 |               |VNF groups and        |         |file must exist in the      |
  57 |               |respective IP         |         |Ansible Server otherwise    |
  58 |               |addresses or DNS      |         |request fails.              |
  59 |               |supported FQDNs       |         |                            |
  60 |               |that the playbook must|         |                            |
  61 |               |be executed against.  |         |                            |
  62 +---------------+----------------------+---------+----------------------------+
  63 | FileParameters| A JSON dictionary    | Optional| Depends on the VNF action  |
  64 |               | where keys are       |         | and playbook design.       |
  65 |               | filenames and values |         |                            |
  66 |               | are contents of      |         |                            |
  67 |               | files. The Ansible   |         |                            |
  68 |               | Server will utilize  |         |                            |
  69 |               | this feature to      |         |                            |
  70 |               | generate files with  |         |                            |
  71 |               | keys as filenames and|         |                            |
  72 |               | values as content.   |         |                            |
  73 |               | This attribute can be|         |                            |
  74 |               | used to generate     |         |                            |
  75 |               | files that a playbook|         |                            |
  76 |               | may require as part  |         |                            |
  77 |               | of execution.        |         |                            |
  78 +---------------+----------------------+---------+----------------------------+
  79 | Timeout       | Time (in seconds)    | Optional|                            |
  80 |               | that a playbook is   |         |                            |
  81 |               | expected to take to  |         |                            |
  82 |               | finish execution for |         |                            |
  83 |               | the VNF. If playbook |         |                            |
  84 |               | execution time       |         |                            |
  85 |               | exceeds this value,  |         |                            |
  86 |               | Ansible Server will  |         |                            |
  87 |               | terminate the        |         |                            |
  88 |               | playbook process.    |         |                            |
  89 +---------------+----------------------+---------+----------------------------+
  90
  91 Ansible JSON file example:
  92
  93 .. code-block:: json
  94
  95   {
  96
  97     "Action":"Configure",
  98
  99     "PlaybookName": "<VNFCode>/<Version>/ansible/configure/site.yml",
 100
 101     "NodeList": ["test1.vnf_b.onap.com", "test2.vnf_b.onap.com"],
 102
 103     "Timeout": 60,
 104
 105     "EnvParameters": {"Retry": 3, "Wait": 5, "ConfigFile":"config.txt"},
 106
 107     "FileParameters": {"config.txt":"db_ip=10.1.1.1, sip_timer=10000"}
 108
 109   }
 110
 111 In the above example, the Ansible Server will:
 112
 113 a. Process the "FileParameters" dictionary and generate a file named
 114    ‘config.txt’ with contents set to the value of the ‘config.txt’ key.
 115
 116 b. Execute the playbook named ‘<VNFCode>/<Version>/ansible/configure/site.yml’
 117    on nodes with    FQDNs test1.vnf\_b.onap.com and test2.vnf\_b.onap.com
 118    respectively while providing the following key value pairs to the playbook:
 119    Retry=3, Wait=5, ConfigFile=config.txt
 120
 121
 122 c. If execution time of the playbook exceeds 60 secs (across all hosts),
 123    it will be terminated.
 124