docs/Chapter5/Tosca/ONAP VNF or PNF CSAR Package.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 VNF or PNF CSAR Package
  17 ------------------------
  18
  19 CSAR Overview
  20 ^^^^^^^^^^^^^
  21
  22 TOSCA YAML CSAR file is an archive file using the ZIP file format whose
  23 structure complies with the TOSCA Simple Profile YAML v1.2 Specification.
  24 The CSAR file may have one of the two following structures:
  25
  26   - CSAR containing a TOSCA-Metadata directory, which includes the TOSCA.meta
  27     metadata file providing an entry information for processing a CSAR file.
  28
  29   - CSAR containing a single yaml (.yml or .yaml) file at the root of the
  30     archive. The yaml file is a TOSCA definition template that contains a
  31     metadata section with template_name and template_version metadata. This
  32     file is the CSAR Entry-Definitions file.
  33
  34 VNF or PNF Package Structure and Format
  35 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  36
  37 .. req::
  38     :id: R-51347
  39     :target: VNF or PNF CSAR PACKAGE
  40     :keyword: MUST
  41     :introduced: casablanca
  42     :updated: frankfurt
  43
  44     The VNF or PNF CSAR package **MUST** be arranged as a CSAR archive as
  45     specified in TOSCA Simple Profile in YAML 1.2.
  46
  47
  48 .. req::
  49     :id: R-87234
  50     :target: VNF or PNF CSAR PACKAGE
  51     :keyword: MUST
  52     :introduced: casablanca
  53     :updated: frankfurt
  54
  55     The VNF or PNF CSAR package provided by a VNF or PNF vendor **MUST** be with
  56     TOSCA-Metadata directory (CSAR Option 1) as specified in
  57     ETSI GS NFV-SOL004.
  58
  59     **Note:** SDC supports only the CSAR Option 1 in Dublin. The Option 2
  60     will be considered in future ONAP releases.
  61
  62 .. req::
  63     :id: R-506221
  64     :target: VNF or PNF CSAR PACKAGE
  65     :keyword: MUST
  66     :introduced: dublin
  67     :updated: frankfurt
  68
  69     The VNF or PNF CSAR file **MUST** be a zip file with .csar extension.
  70
  71
  72 VNF or PNF Package Contents
  73 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  74
  75 .. req::
  76     :id: R-10087
  77     :target: VNF or PNF CSAR PACKAGE
  78     :keyword: MUST
  79     :introduced: casablanca
  80     :updated: dublin
  81
  82     The VNF or PNF CSAR package **MUST** include all artifacts required by
  83     ETSI GS NFV-SOL004 including Manifest file, VNFD or PNFD (or Main
  84     TOSCA/YAML based Service Template) and other optional artifacts.
  85
  86 .. req::
  87     :id: R-01123
  88     :target: VNF or PNF CSAR PACKAGE
  89     :keyword: MUST
  90     :introduced: casablanca
  91     :updated: frankfurt
  92
  93     The VNF or PNF CSAR package Manifest file **MUST** contain: VNF or PNF
  94     package meta-data, a list of all artifacts (both internal and
  95     external) entry's including their respected URI's, as specified
  96     in ETSI GS NFV-SOL 004
  97
  98 .. req::
  99     :id: R-21322
 100     :target: VNF CSAR PACKAGE
 101     :keyword: MUST
 102     :introduced: casablanca
 103     :updated: frankfurt
 104
 105     The VNF provider **MUST** provide their testing scripts to support
 106     testing as specified in ETSI NFV-SOL004 - Testing directory in CSAR
 107
 108 .. req::
 109     :id: R-40820
 110     :target: VNF or PNF CSAR PACKAGE
 111     :keyword: MUST
 112     :introduced: casablanca
 113     :updated: frankfurt
 114
 115     The VNF or PNF CSAR PACKAGE **MUST** enumerate all of the open source
 116     licenses their VNF(s) incorporate. CSAR License directory as per ETSI
 117     SOL004.
 118
 119     for example ROOT\\Licenses\\ **License_term.txt**
 120
 121 .. req::
 122     :id: R-293901
 123     :target: VNF or PNF CSAR PACKAGE
 124     :keyword: MUST
 125     :introduced: dublin
 126
 127     The VNF or PNF CSAR PACKAGE with TOSCA-Metadata **MUST** include following
 128     additional keywords pointing to TOSCA files:
 129
 130       - ETSI-Entry-Manifest
 131
 132       - ETSI-Entry-Change-Log
 133
 134     Note: For a CSAR containing a TOSCA-Metadata directory, which includes
 135     the TOSCA.meta metadata file. The TOSCA.meta metadata file includes block_0
 136     with the Entry-Definitions keyword pointing to a TOSCA definitions YAML
 137     file used as entry for parsing the contents of the overall CSAR archive.
 138
 139 .. req::
 140     :id: R-146092
 141     :target: VNF or PNF CSAR PACKAGE
 142     :keyword: MUST
 143     :introduced: dublin
 144     :updated: frankfurt
 145
 146     If one or more non-MANO artifact(s) is included in the VNF or PNF CSAR
 147     package, the Manifest file in this CSAR package **MUST** contain one or more
 148     of the following ONAP non-MANO artifact set identifier(s):
 149
 150       - onap_ves_events: contains VES registration files
 151
 152       - onap_pm_dictionary: contains the PM dictionary files
 153
 154       - onap_yang_modules: contains Yang module files for configurations
 155
 156       - onap_ansible_playbooks: contains any ansible_playbooks
 157
 158       - onap_pnf_sw_information: contains the PNF software information file
 159
 160       - onap_others: contains any other non_MANO artifacts, e.g. informational
 161         documents
 162
 163      *NOTE: According to ETSI SOL004 v.2.6.1, every non-MANO artifact set shall be
 164      identified by a non-MANO artifact set identifier which shall be registered in
 165      the ETSI registry. Approved ONAP non-MANO artifact set identifiers are documented
 166      in the following page* https://wiki.onap.org/display/DW/ONAP+Non-MANO+Artifacts+Set+Identifiers
 167
 168 .. req::
 169     :id: R-221914
 170     :target: VNF or PNF CSAR PACKAGE
 171     :keyword: MUST
 172     :introduced: frankfurt
 173
 174     The VNF or PNF CSAR package **MUST** contain a human-readable change log text
 175     file. The Change Log file keeps a history describing any changes in the VNF
 176     or PNF package. The Change Log file is kept up to date continuously from
 177     the creation of the CSAR package.
 178
 179 .. req::
 180     :id: R-57019
 181     :target: PNF CSAR PACKAGE
 182     :keyword: MUST
 183     :introduced: dublin
 184     :updated: frankfurt
 185
 186     The PNF CSAR PACKAGE Manifest file **MUST** start with the PNF
 187     package metadata in the form of a name-value pairs. Each pair shall appear
 188     on a different line. The name is specified as following:
 189
 190       - pnfd_provider
 191
 192       - pnfd_name
 193
 194       - pnfd_release_date_time
 195
 196       - pnfd_archive_version
 197
 198 .. req::
 199     :id: R-795126
 200     :target: VNF CSAR PACKAGE
 201     :keyword: MUST
 202     :introduced: dublin
 203     :updated: frankfurt
 204
 205     The VNF CSAR package Manifest file **MUST** start with the VNF
 206     package metadata in the form of a name-value pairs. Each pair shall appear
 207     on a different line. The name is specified as following:
 208
 209       - vnf_provider_id
 210
 211       - vnf_product_name
 212
 213       - vnf_release_date_time
 214
 215       - vnf_package_version
 216
 217 .. req::
 218     :id: R-972082
 219     :target: PNF CSAR PACKAGE
 220     :keyword: MUST
 221     :introduced: frankfurt
 222
 223     If the Manifest file in the PNF CSAR package includes "onap_pnf_sw_information"
 224     as a non-MANO artifact set identifiers, then the PNF software information file is
 225     included in the package and it **MUST** be compliant to:
 226
 227     - The file extension which contains the PNF software version must be .yaml
 228
 229     - The PNF software version information must be specified as following:
 230
 231     .. code-block:: yaml
 232
 233        pnf_software_information:
 234
 235         - pnf_software_version:  "<version>"
 236
 237
 238
 239 VNF or PNF Package Authenticity and Integrity
 240 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 241
 242 VNF or PNF CSAR package shall support a method for authenticity and integrity
 243 assurance. According to ETSI SOL004 the onboarding package shall be secured.
 244 ETSI SOL004 provides two options:
 245
 246 Option 1 - One Digest for each components of the VNF or PNF package. The table
 247 of hashes is included in the manifest file, which is signed with the VNF or PNF
 248 provider private key. A signing certificate including the provider’s public key
 249 shall be included in the package.
 250
 251 Option 2 - The complete CSAR file shall be digitally signed with the provider
 252 private key. The provider delivers one zip file consisting of the CSAR file, a
 253 signature file and a certificate file that includes the VNF provider public
 254 key.
 255
 256 *Dublin release note*
 257
 258     - VNFSDK pre-onboarding validation procedure:
 259       - Option 1: specified in ETSI SOL004 is supported.
 260       - Option 2: Will be supported in the future releases.
 261
 262     - SDC onboarding procedure:
 263       - Option 1: Will be supported in the future releases.
 264       - Option 2: specified in ETSI SOL004 is supported.
 265
 266 .. req::
 267     :id: R-787965
 268     :target: VNF or PNF CSAR PACKAGE
 269     :keyword: MUST
 270     :introduced: dublin
 271
 272     If the VNF or PNF CSAR Package utilizes Option 2 for package security, then
 273     the complete CSAR file **MUST** be digitally signed with the VNF or PNF
 274     provider private key. The VNF or PNF provider delivers one zip file
 275     consisting of the CSAR file, a signature file and a certificate file that
 276     includes the VNF or PNF provider public key. The certificate may also be
 277     included in the signature container, if the signature format allows that.
 278     The VNF or PNF provider creates a zip file consisting of the CSAR file with
 279     .csar extension, signature and certificate files. The signature and
 280     certificate files must be siblings of the CSAR file with extensions .cms
 281     and .cert respectively.
 282
 283
 284 .. req::
 285     :id: R-130206
 286     :target: VNF or PNF CSAR PACKAGE
 287     :keyword: MUST
 288     :introduced: dublin
 289     :updated: el alto
 290
 291     If the VNF or PNF CSAR Package utilizes Option 1 for package security, then
 292     the complete CSAR file **MUST** contain a Digest (a.k.a. hash) for each of
 293     the components of the VNF or PNF package. The table of hashes is included
 294     in the package manifest file, which is signed with the VNF or PNF provider
 295     private key. In addition, the VNF or PNF provider MUST include a signing
 296     certificate that includes the VNF or PNF provider public key, following a
 297     TOSCA pre-defined naming convention and located either at the root of the
 298     archive or in a predefined location specified by the TOSCA.meta file with
 299     the corresponding entry named "ETSI-Entry-Certificate".
 300
 301
 302 VNF Package ONAP Extensions
 303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 304
 305 1. TOSCA data type extension tosca.datatypes.nfv.injectFile is used for vCPE
 306    use case.
 307 2. ONAP extensions for VNF package that is currently proposed for Dublin
 308    release is VES extension described below.