docs/onboardingpackages.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 .. _sdc_onboarding_package_types:
   5
   6 ========================
   7 Onboarding Package Types
   8 ========================
   9
  10 Supported Package Types
  11 -----------------------
  12 SDC supports the following packages types
  13
  14 - Heat Package
  15 - ONAP Tosca CSAR Package
  16 - ETSI SOL004 Tosca CSAR Package
  17
  18 Heat Package
  19 ^^^^^^^^^^^^
  20 The heat package is a zip archive with a .zip extension. The package contains heat template yaml file(s), corresponding
  21 environment file(s) and a MANIFEST.json file. The MANIFEST.json file describes the contents of the package.
  22
  23 There must be at least one heat template yaml file in the package whose name starts with *base_*. The other heat
  24 templates in the package can have any name. All  environment files that are included in the package must have the same
  25 name as its corresponding yaml file with a .env file extension.
  26
  27 An example of a simple heat package stucture is a zip archive containing the following 3 files
  28
  29 - base_vFW.yaml   (heat template)
  30 - base_vFW.env    (corresponding environment file)
  31 - MANIFEST.json   (describes files included in the package)
  32
  33 Examples of heat packages are the packages with .zip extension available in `SDC git repo <https://git.onap.org/sdc/tree/test-apis-ci/sdc-api-tests/chef-repo/cookbooks/sdc-api-tests/files/default/Files/VNFs>`_
  34
  35 ONAP Tosca CSAR Package
  36 ^^^^^^^^^^^^^^^^^^^^^^^
  37 The ONAP Tosca CSAR package is a zip archive with a .csar extension. The structure of the CSAR package is as described
  38 in `ONAP wiki page <https://wiki.onap.org/display/DW/Csar+Structure>`_
  39
  40 ETSI SOL004 Tosca CSAR Package
  41 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  42 The ETSI SOL004 Tosca CSAR Package is a zip archive with a .csar extension. The structure of the supported CSAR package
  43 is as described in `ETSI NFV-SOL 004v2.6.1`_ csar structure option 1 i.e. CSAR containing a TOSCA-Metadata directory.
  44
  45 The supported descriptor included in the package is aligned to `ETSI NFV-SOL 001v2.5.1 <https://docbox.etsi.org/ISG/NFV/Open/Publications_pdf/Specs-Reports/NFV-SOL%20001v2.5.1%20-%20GS%20-%20TOSCA-based%20NFV%20descriptors%20spec.pdf>`_
  46
  47 Other Points to note when onboarding this package are:
  48
  49 - During onboarding the ETSI NFV-SOL004 CSAR structure is transformed to the internal ONAP CSAR structure.
  50 - The original input CSAR is maintained and stored as the SDC artifact *ONBOARDED_PACKAGE* in the xNF internal model.
  51 - The non-mano artifacts are mapped to the corresponding SDC Artifact Type in the xNF internal model.
  52
  53 Package Types applicable to Resource Types
  54 ------------------------------------------
  55 VF
  56 ^^
  57 The 3 package types described in `Supported Package Types`_ are all applicable for a VF i.e. a VF can be onboarded using any of
  58 these package types.
  59
  60 PNF
  61 ^^^
  62 Only the `ETSI SOL004 Tosca CSAR Package`_ is applicable for a PNF.
  63
  64 .. note::
  65    The PNF is not explicitly mentioned in ETSI NFV-SOL 004v2.6.1. There is a CR pending on the SOL004 specification
  66    describing the PNFD archive. SDC supports and expects the metadata section in the PNFD archive manifest to be
  67    aligned with this CR i.e. the entries contain the following names (keys)
  68
  69    - pnfd_provider
  70    - pnfd_name
  71    - pnfd_release_date_time
  72    - pnfd_archive_version
  73
  74    An example of valid manifest file metadata section
  75    ::
  76
  77       metadata:
  78           pnfd_name: MRF
  79           pnfd_provider: SunShineCompany
  80           pnfd_archive_version: 1.0
  81           pnfd_release_date_time: 2017-01-01T10:00:00+03:00
  82
  83 When the PNF package in onboarded, the PNFD (descriptor) is transformed from ETSI NFV-SOL 001 model to the internal
  84 ONAP model.
  85
  86 How does SDC determine which package type is being onboarded
  87 ------------------------------------------------------------
  88 SDC onboarding processes each of the package types differently. SDC determines which package type is being onboarded, and
  89 hence which logic to use, based on the following
  90
  91 First SDC checks the extension of the package. If the package extension is *.zip* then the package is treated as a `Heat package`_.
  92
  93 If the package extension is *.csar* and the following is true
  94
  95 - CSAR package contains TOSCA-Metadata directory
  96 - The TOSCA.meta file exists within the TOSCA-Metadata directory
  97 - The TOSCA.meta file contains the following keynames in block_0
  98
  99    - Entry-Definitions
 100    - ETSI-Entry-Manifest
 101    - ETSI-Entry-Change-Log
 102
 103 then the package is treated as an `ETSI SOL004 Tosca CSAR Package`_. Otherwise the package is treated as an `ONAP Tosca CSAR Package`_.
 104
 105 Package Security
 106 ----------------
 107 SDC validates the authenticity and integrity of onboarding packages that are secured according to
 108 Security option 2 described in `ETSI NFV-SOL 004v2.6.1`_.
 109
 110 In this option the whole package is signed and delivered as part of a zip file. SDC supports both zip file structures
 111 specified in the standard i.e
 112
 113 1. Zip file containing 3 artifacts
 114
 115    a. Package
 116    b. Signing Certificate File
 117    c. Signature File
 118
 119 2. Zip file containing 2 artifacts
 120
 121    a. Package
 122    b. Signature File containing signing certificate
 123
 124 SDC supports the signature in Cryptographic Message Syntax (CMS) format.
 125
 126 .. note::
 127    For SDC to validate the authenticity and integrity of the onboarding package, the root certificate of the trusted CA
 128    needs to be pre-installed in SDC before onboarding is started. The details of this procedure are described :ref:`here <doc_guide_user_des_res-onb_pre-install_root_certificate>`.
 129
 130 .. _ETSI NFV-SOL 004v2.6.1: https://docbox.etsi.org/ISG/NFV/Open/Publications_pdf/Specs-Reports/NFV-SOL%20004v2.6.1%20-%20GS%20-%20VNF%20Package%20Stage%203%20-%20spec.pdf