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: dublin
 173     :updated: frankfurt
 174
 175     The VNF or PNF CSAR package **MUST** contain a human-readable change log text
 176     file. The Change Log file keeps a history describing any changes in the VNF
 177     or PNF package. The Change Log file is kept up to date continuously from
 178     the creation of the CSAR package.
 179
 180 .. req::
 181     :id: R-57019
 182     :target: PNF CSAR PACKAGE
 183     :keyword: MUST
 184     :introduced: dublin
 185     :updated: frankfurt
 186
 187     The PNF CSAR PACKAGE Manifest file **MUST** start with the PNF
 188     package metadata in the form of a name-value pairs. Each pair shall appear
 189     on a different line. The name is specified as following:
 190
 191       - pnfd_provider
 192
 193       - pnfd_name
 194
 195       - pnfd_release_date_time
 196
 197       - pnfd_archive_version
 198
 199 .. req::
 200     :id: R-795126
 201     :target: VNF CSAR PACKAGE
 202     :keyword: MUST
 203     :introduced: dublin
 204     :updated: frankfurt
 205
 206     The VNF CSAR package Manifest file **MUST** start with the VNF
 207     package metadata in the form of a name-value pairs. Each pair shall appear
 208     on a different line. The name is specified as following:
 209
 210       - vnf_provider_id
 211
 212       - vnf_product_name
 213
 214       - vnf_release_date_time
 215
 216       - vnf_package_version
 217
 218 .. req::
 219     :id: R-972082
 220     :target: PNF CSAR PACKAGE
 221     :keyword: MUST
 222     :introduced: frankfurt
 223
 224     If the Manifest file in the PNF CSAR package includes "onap_pnf_sw_information"
 225     as a non-MANO artifact set identifiers, then the PNF software information file is
 226     included in the package and it **MUST** be compliant to:
 227
 228     - The file extension which contains the PNF software version must be .yaml
 229
 230     - The PNF software version information must be specified as following:
 231
 232     .. code-block:: yaml
 233
 234        pnf_software_information:
 235
 236         - pnf_software_version:  "<version>"
 237
 238
 239
 240 VNF or PNF Package Authenticity and Integrity
 241 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 242
 243 VNF or PNF CSAR package shall support a method for authenticity and integrity
 244 assurance. According to ETSI SOL004 the onboarding package shall be secured.
 245 ETSI SOL004 provides two options:
 246
 247 Option 1 - One Digest for each components of the VNF or PNF package. The table
 248 of hashes is included in the manifest file, which is signed with the VNF or PNF
 249 provider private key. A signing certificate including the provider’s public key
 250 shall be included in the package.
 251
 252 Option 2 - The complete CSAR file shall be digitally signed with the provider
 253 private key. The provider delivers one zip file consisting of the CSAR file, a
 254 signature file and a certificate file that includes the VNF provider public
 255 key.
 256
 257 *Dublin release note*
 258
 259     - VNFSDK pre-onboarding validation procedure:
 260       - Option 1: specified in ETSI SOL004 is supported.
 261       - Option 2: Will be supported in the future releases.
 262
 263     - SDC onboarding procedure:
 264       - Option 1: Will be supported in the future releases.
 265       - Option 2: specified in ETSI SOL004 is supported.
 266
 267 .. req::
 268     :id: R-787965
 269     :target: VNF or PNF CSAR PACKAGE
 270     :keyword: MUST
 271     :introduced: dublin
 272
 273     If the VNF or PNF CSAR Package utilizes Option 2 for package security, then
 274     the complete CSAR file **MUST** be digitally signed with the VNF or PNF
 275     provider private key. The VNF or PNF provider delivers one zip file
 276     consisting of the CSAR file, a signature file and a certificate file that
 277     includes the VNF or PNF provider public key. The certificate may also be
 278     included in the signature container, if the signature format allows that.
 279     The VNF or PNF provider creates a zip file consisting of the CSAR file with
 280     .csar extension, signature and certificate files. The signature and
 281     certificate files must be siblings of the CSAR file with extensions .cms
 282     and .cert respectively.
 283
 284
 285 .. req::
 286     :id: R-130206
 287     :target: VNF or PNF CSAR PACKAGE
 288     :keyword: MUST
 289     :introduced: dublin
 290     :updated: el alto
 291
 292     If the VNF or PNF CSAR Package utilizes Option 1 for package security, then
 293     the complete CSAR file **MUST** contain a Digest (a.k.a. hash) for each of
 294     the components of the VNF or PNF package. The table of hashes is included
 295     in the package manifest file, which is signed with the VNF or PNF provider
 296     private key. In addition, the VNF or PNF provider MUST include a signing
 297     certificate that includes the VNF or PNF provider public key, following a
 298     TOSCA pre-defined naming convention and located either at the root of the
 299     archive or in a predefined location specified by the TOSCA.meta file with
 300     the corresponding entry named "ETSI-Entry-Certificate".
 301
 302
 303 VNF Package ONAP Extensions
 304 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 305
 306 1. TOSCA data type extension tosca.datatypes.nfv.injectFile is used for vCPE
 307    use case.
 308 2. ONAP extensions for VNF package that is currently proposed for Dublin
 309    release is VES extension described below.