docs/Chapter8/Chef-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 Chef JSON Key Value Description
  17 -------------------------------------
  18
  19 The following provides the key value pairs that must be contained in the
  20 JSON file supporting Chef action.
  21
  22 Table A1. Chef JSON File key value description
  23 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  24
  25 +----------------+--------------------------+---------+----------------------+
  26 | **Field Name** | **Description**          | **Type**| **Comment**          |
  27 +================+==========================+=========+======================+
  28 | Environment    | A JSON dictionary        | Optional|Depends on VNF action.|
  29 |                | representing a Chef      |         |                      |
  30 |                | Environment object. If   |         |                      |
  31 |                | the VNF action requires  |         |                      |
  32 |                | loading or modifying Chef|         |                      |
  33 |                | environment attributes   |         |                      |
  34 |                | associated with the VNF, |         |                      |
  35 |                | all the relevant         |         |                      |
  36 |                | information must be      |         |                      |
  37 |                | provided in this JSON    |         |                      |
  38 |                | dictionary in a structure|         |                      |
  39 |                | that conforms to a Chef  |         |                      |
  40 |                | Environment Object.      |         |                      |
  41 +----------------+--------------------------+---------+----------------------+
  42 | Node           | A JSON dictionary        |Mandatory|                      |
  43 |                | representing a Chef Node |         |                      |
  44 |                | Object.                  |         |                      |
  45 |                |                          |         |                      |
  46 |                | The Node JSON dictionary |         |                      |
  47 |                | must include the run list|         |                      |
  48 |                | to be triggered for the  |         |                      |
  49 |                | desired VNF action by the|         |                      |
  50 |                | push job. It should also |         |                      |
  51 |                | include any attributes   |         |                      |
  52 |                | that need to be          |         |                      |
  53 |                | configured on the Node   |         |                      |
  54 |                | Object as part of the VNF|         |                      |
  55 |                | action.                  |         |                      |
  56 +----------------+--------------------------+---------+----------------------+
  57 | NodeList       | Array of FQDNs that      |Mandatory|                      |
  58 |                | correspond to the        |         |                      |
  59 |                | endpoints (VMs) of a VNF |         |                      |
  60 |                | registered with the Chef |         |                      |
  61 |                | Server that need to      |         |                      |
  62 |                | trigger a chef-client run|         |                      |
  63 |                | as part of the desired   |         |                      |
  64 |                | VNF action.              |         |                      |
  65 +----------------+--------------------------+---------+----------------------+
  66 | PushJobFlag    | This field indicates     |Mandatory| If set to "True",    |
  67 |                | whether the VNF action   |         | ONAP will request a  |
  68 |                | requires a push Job. Push|         | push job. Ignored    |
  69 |                | job object will be       |         | otherwise.           |
  70 |                | created by ONAP if       |         |                      |
  71 |                | required.                |         |                      |
  72 +----------------+--------------------------+---------+----------------------+
  73 | CallbackCapable| This field indicates if  | Optional| If Chef cookbook is  |
  74 |                | the chef-client run      |         | callback capable, VNF|
  75 |                | invoked by push job      |         | owner is required to |
  76 |                | corresponding to the VNF |         | set it to "True".    |
  77 |                | action is capable of     |         | Ignored otherwise.   |
  78 |                | posting results on a     |         |                      |
  79 |                | callback URL.            |         |                      |
  80 +----------------+--------------------------+---------+----------------------+
  81 | GetOutputFlag  | Flag which indicates     |Mandatory| ONAP will retrieve   |
  82 |                | whether ONAP should      |         | output from          |
  83 |                | retrieve output generated|         | NodeObject attributes|
  84 |                | in a chef-client run from|         | [‘PushJobOutput’] for|
  85 |                | Node object attribute    |         | all nodes in NodeList|
  86 |                | node[‘PushJobOutput’] for|         | if set to "True".    |
  87 |                | this VNF action (e.g., in|         | Ignored otherwise.   |
  88 |                | Audit).                  |         |                      |
  89 +----------------+--------------------------+---------+----------------------+
  90
  91 Chef Template example:
  92
  93 .. code-block:: erb
  94
  95  "Environment":{
  96       "name": "HAR",
  97       "description": "VNF Chef environment for HAR",
  98       "json_class": "Chef::Environment",
  99       "chef_type": "environment",
 100       "default_attributes": { },
 101       "override_attributes": {
 102             "Retry_Time":"50",
 103             "MemCache": "1024",
 104             "Database_IP":"10.10.1.5"
 105       },
 106  }
 107  }
 108  "Node": {
 109       "name" : "signal.network.com "
 110       "chef_type": "node",
 111       "json_class": "Chef::Node",
 112       "attributes": {
 113             "IPAddress1": "192.168.1.2",
 114             "IPAddress2":"135.16.162.5",
 115             "MyRole":"BE"
 116       },
 117       "override": {},
 118       "default": {},
 119       "normal":{},
 120       "automatic":{},
 121       "chef_environment" : "_default"
 122       "run_list": [ "configure_signal" ]
 123       },
 124       "NodeList":["node1.vnf_a.onap.com", "node2.vnf_a.onap.com"],
 125       "PushJobFlag": "True"
 126       "CallbackCapable":True
 127       "GetOutputFlag" : "False"
 128  }
 129
 130 The example JSON file provided by the VNF provider for each VNF action will be
 131 turned into a template by ONAP, that can be updated with instance
 132 specific values at run-time.
 133
 134 Some points worth noting regarding the JSON fields:
 135
 136 a. The JSON file must be created for each action for each VNF.
 137
 138 b. If a VNF action involves multiple endpoints (VMs) of a VNF, ONAP will
 139    replicate the "Node" JSON dictionary in the template and post it to
 140    each FQDN (i.e., endpoint) in the NodeList after setting the "name"
 141    field in the Node object to be the respective FQDN [#8.1.1]_. Hence, it
 142    is required that all end points (VMs) of a VNF involved in a VNF
 143    action support the same set of Node Object attributes.
 144
 145 The following table describes the JSON dictionary to post in Callback.
 146
 147 Table A2. JSON Dictionary to Post in Callback
 148 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 149
 150 +--------------+----------------------------+---------+-----------------------+
 151 | **Key**      | **Description**            | **Type**| **Comment**           |
 152 +==============+============================+=========+=======================+
 153 | RequestId    | A unique string associated |Mandatory|                       |
 154 |              | with the original request  |         |                       |
 155 |              | by ONAP. This key-value    |         |                       |
 156 |              | pair will be provided by   |         |                       |
 157 |              | ONAP in the environment of |         |                       |
 158 |              | the push job request and   |         |                       |
 159 |              | must be returned as part of|         |                       |
 160 |              | the POST message.          |         |                       |
 161 +--------------+----------------------------+---------+-----------------------+
 162 | StatusCode   | An integer that must be set|Mandatory|                       |
 163 |              | to 200 if chef-client run  |         |                       |
 164 |              | on the node finished       |         |                       |
 165 |              | successfully 500 otherwise.|         |                       |
 166 +--------------+----------------------------+---------+-----------------------+
 167 | StatusMessage| A string which must be set |Mandatory|                       |
 168 |              | to ‘SUCCESS’ if StatusCode |         |                       |
 169 |              | was 200                    |         |                       |
 170 |              |                            |         |                       |
 171 |              | Appropriate error message  |         |                       |
 172 |              | otherwise.                 |         |                       |
 173 +--------------+----------------------------+---------+-----------------------+
 174 | Name         | A string which corresponds |Mandatory|                       |
 175 |              | to the name of the node    |         |                       |
 176 |              | where push job is run. It  |         |                       |
 177 |              | is required that the value |         |                       |
 178 |              | be retrieved from the node |         |                       |
 179 |              | object attributes (where it|         |                       |
 180 |              | is always defined).        |         |                       |
 181 +--------------+----------------------------+---------+-----------------------+
 182 | PushJobOutput| Any output from the        |Optional | Depends on VNF action.|
 183 |              | chef-client run that needs |         | If empty, it must not |
 184 |              | to be returned to ONAP.    |         | be included.          |
 185 +--------------+----------------------------+---------+-----------------------+
 186
 187 .. [#8.1.1]
 188    The "name" field is a mandatory field in a valid Chef Node Object
 189    JSON dictionary.