docs/scenario-lifecycle/scenario-descriptor-files.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) 2017 OPNFV Ulrich Kleber (Huawei)
   4
   5
   6 Scenario Descriptor Files
   7 ----------------------------
   8
   9 What are Scenario Descriptor Files?
  10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  11
  12 Every scenario is described in its own descriptor file.
  13 The scenario descriptor file will be used by several parties:
  14
  15 * Installer tools will read from it the list of components to be installed
  16   and the configuration (e.g. deployment options and necessary details) to use.
  17 * The dynamic CI process will read from it the prerequisites of the scenario
  18   to select the resource that has the needed capabilities for the deployment.
  19   It will also select the installer
  20   from the list of supported installers and the other deployment options as
  21   supported in their combination.
  22
  23   The dynamic CI process will provide the installers with the deployment option
  24   to use for a particular deployment.
  25
  26 * The scenario owner needs to provide the descriptor file.
  27
  28   When compiling it the scenario owner typically needs to work together with
  29   the installers, so the installers will support the required components and
  30   options.
  31 * The testing framework can read from the scenario descriptor file necessary
  32   information to know which features can be tested on the scenario.
  33 * The scenario descriptor file will also contain some maintenance information
  34
  35
  36 Structure of the file
  37 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  38
  39 The scenario descriptor file is a yaml file. The syntax will allow to specify
  40 additional descriptor files, to make it better readable or structure common
  41 configurations across multiple scenarios.
  42
  43 The file has following main sections:
  44
  45 * metadata (owner, history, description)
  46 * list of components (names, versions, submodules)
  47 * deployment options (HA/NOHA, hardware&virtualization, installers, including
  48   possible combinations and necessary details)
  49 * other prerequisites (e.g. memory requirement more than pharos spec)
  50 * list of features to be tested
  51
  52 More information to be provided in next version of this document. The file will
  53 be defined based on the installer-specific files for scenario specification
  54 used by the 4 installers in Danube release. Thus it will be made sure that the
  55 information needed by the installers will be covered.
  56
  57 All scenario files will be stored in a central repo, e.g. Octopus. There will
  58 also be a commented template to help create scenario descriptor files.
  59
  60
  61 Metadata
  62 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  63
  64 In Danube timeframe only Fuel installer has some metadata in the descriptor file.
  65 The new template contains:
  66
  67 * Unique name
  68
  69   This is a free name, there is a recommendation to take fish for names, matching
  70   OPNFV release naming with rivers.
  71
  72 * A free text title
  73
  74   This should be a short descriptive text telling the main purpose
  75
  76 * A version number for the descriptor file
  77
  78   Three digits, separated with dots, as used by Fuel in Danube
  79
  80 * Creation date
  81 * Comment
  82
  83   The file should contain a clear description of the purpose of the scenario,
  84   including the main benefits and major features.
  85   If applicable, the parent scenario should be mentioned.
  86
  87 * First OPNFV version to use the scenario
  88 * Author/Owner
  89
  90 * A list of additional contact persons, e.g. from installers or major components
  91
  92 Components
  93 ^^^^^^^^^^^^^^^^
  94
  95 In this section all components are listed together with their version.
  96 For some components in addtion submodules can be listed.
  97
  98 More details will be added.
  99
 100
 101 Deployment options
 102 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 103
 104 This section will list the supported deployment options. In each category at least
 105 one option must be supported.
 106
 107 * hardware (cpu) types (intel or ARM)
 108 * Virtualization (bare-metal or vPOD)
 109 * availability (HA or NOHA)
 110
 111   This subsection needs to specify also what does an HA deployment need, e.g.:
 112
 113 ::
 114
 115   availability:
 116
 117     - type: HA
 118         nodes:
 119           - name: host1
 120             roles:
 121               - openstack-controller
 122               - odl
 123               - ceph-adm
 124               - ceph-mon
 125           - name: host2
 126             roles:
 127               - openstack-controller
 128               - odl
 129               - ceph-adm
 130               - ceph-mon
 131           - name: host3
 132             roles:
 133               - openstack-controller
 134               - odl
 135               - ceph-adm
 136               - ceph-mon
 137           - name: host4
 138               - openstack-compute
 139               - ceph-osd
 140           - name: host5
 141               - openstack-compute
 142               - ceph-osd
 143     - type: NOHA
 144         hosts:
 145           - name: host1
 146             roles:
 147               - openstack-controller
 148               - odl
 149               - ceph-adm
 150               - ceph-mon
 151           - name: host2
 152               - openstack-compute
 153               - ceph-osd
 154           - name: host3
 155               - openstack-compute
 156               - ceph-osd
 157
 158
 159
 160 * deployment tool (apex, compass, fuel, daisy, joid)
 161
 162   In the section for each deployment tool, the combinations of the first three
 163   options have to be listed, e.g.:
 164
 165 ::
 166
 167   deployment-tools:
 168
 169     - type: fuel
 170          cpu: intel
 171          pod: baremetal
 172          availability: HA
 173     - type: fuel
 174          cpu: intel
 175          pod: virtual
 176          availability: HA
 177     - type: fuel
 178          cpu: intel
 179          pod: virtual
 180          availability: NOHA
 181
 182 Please note that this allows easy definition of other availability options
 183 including scaling and redundant configuration of SDN controllers.
 184
 185
 186 Prerequisites
 187 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 188
 189 This section will list additional prerequisites. Currently there is only
 190 one case where a scenario has additional prerequisites to the Pharos spec.
 191 E.g. a component could requires more RAM on the nodes than defined in
 192 Pharos spec.
 193 In general it should be preferred to issue such requirements to pharos
 194 using the pharos change request process, but in some cases in might be
 195 better to specify additional prerequisites.
 196
 197 Another use case for these prerequisites will be usage of specilized
 198 hardware, e.g. for acceleration. This needs further study.
 199
 200 The section can be empty or omitted.
 201
 202
 203 Testcases
 204 ^^^^^^^^^^^^^^^^
 205
 206 This section will provide information for functest and yardstick to decide
 207 on the proper test cases for the scenario.
 208
 209 More details will be added.
 210
 211
 212 Shared settings
 213 ^^^^^^^^^^^^^^^^
 214
 215 This descriptor file might get quite long and complex. Also some of the settings
 216 will be shared between several scenarios, e.g. a long OpenStack module list.
 217
 218 Therefore it shall be possible to reference another file like a macro.
 219 In that case all the file content is included in that place, e.g.:
 220
 221 ::
 222
 223   availability:
 224
 225     - type: HA
 226         file: odl-ha-configuration.yaml
 227
 228