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 - Basic Helm package support for CNF
  18
  19 For an extensive guide on how to perform onboarding, please refer to the ONAP User guide:
  20 * :ref:`User Guides <onap-doc:doc_guide_user_des>`
  21
  22
  23 Heat Package
  24 ^^^^^^^^^^^^
  25 The heat package is a zip archive with a .zip extension. The package contains heat template yaml file(s), corresponding
  26 environment file(s) and a MANIFEST.json file. The MANIFEST.json file describes the contents of the package.
  27
  28 There must be at least one heat template yaml file in the package whose name starts with *base_*. The other heat
  29 templates in the package can have any name. All  environment files that are included in the package must have the same
  30 name as its corresponding yaml file with a .env file extension.
  31
  32 An example of a simple heat package stucture is a zip archive containing the following 3 files
  33
  34 - base_vFW.yaml   (heat template)
  35 - base_vFW.env    (corresponding environment file)
  36 - MANIFEST.json   (describes files included in the package)
  37
  38 Examples of heat packages are the packages with .zip extension available in `SDC git repo <https://git.onap.org/sdc/tree/integration-tests/src/test/resources/Files/VNFs>`_
  39
  40 ONAP Tosca CSAR Package
  41 ^^^^^^^^^^^^^^^^^^^^^^^
  42 The ONAP Tosca CSAR package is a zip archive with a .csar extension. The structure of the CSAR package is as described
  43 in `ONAP wiki page <https://wiki.onap.org/display/DW/Csar+Structure>`_
  44
  45 ASD CSAR Package
  46 ^^^^^^^^^^^^^^^^
  47 The Application Service Descriptor CSAR package is a zip archive with a .csar extension. The structure of the CSAR and the descriptor it shall contain is described in `Application Service Descriptor (ASD) and packaging Proposals for CNF <https://wiki.onap.org/display/DW/Application+Service+Descriptor+%28ASD%29+and+packaging+Proposals+for+CNF>`_.
  48
  49 ETSI SOL004 Tosca CSAR Package
  50 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  51 The ETSI SOL004 Tosca CSAR Package is a zip archive with a .csar extension. The structure necessary for the supported CSAR package
  52 depends on the model selected in onboarding as detailed below.
  53
  54 **SDC AID**
  55
  56 If the package is onboarded using the SDC AID model, the structure of the supported CSAR package
  57 is as described in `ETSI NFV-SOL 004v2.6.1`_ csar structure option 1 i.e. CSAR containing a TOSCA-Metadata directory.
  58
  59 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>`_. The descriptor is partially mapped into the SDC AID model. There is also limited support for v2.7.1 and 3.3.1
  60
  61 **ETSI SOL001 v2.5.1**
  62
  63 If the package is onboarded using the ETSI SOL001 v2.5.1 model, the structure of the supported CSAR package
  64 is as described in `ETSI NFV-SOL 004v2.5.1`_ csar structure option 1 i.e. CSAR containing a TOSCA-Metadata directory.
  65
  66 The supported descriptor included in the package is aligned to `ETSI NFV-SOL 001v2.5.1`_. The tosca types defined in this version of the ETSI NFV-SOL 001 are used in the created VF (rather than the types defined in the SDC AID model).
  67
  68 Note in relation to model selection:
  69
  70 - More than one model can be selected during onboarding. In the subsequent VSP import one model from the list of models selected at onboarding time must be selected.
  71 - For a package to be used in service design it must be imported with the same model as is selected during service creation.
  72
  73 Other Points to note when onboarding this package are:
  74
  75 - During onboarding the ETSI NFV-SOL004 CSAR structure is transformed to the internal ONAP CSAR structure.
  76 - The original input CSAR is maintained and stored as the SDC artifact *ETSI_PACKAGE* in the xNF internal model. For existing legacy xNF, it can be stored as *ONBOARDED_PACKAGE* instead.
  77 - The non-mano artifacts are mapped to the corresponding SDC Artifact Type in the xNF internal model.
  78
  79
  80 Basic Helm package support for CNF
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82
  83 The helm package support is new since Guilin release, helm chart packaged as tgz file can be onboarded and distributed.
  84 The support is limited for this first release.
  85
  86 Since Istanbul release there is also an additional helm chart validation step during package onboarding process. More information: :ref:`SDC Helm Validator <sdc_helm_validator>`.
  87
  88 Package Types applicable to Resource Types
  89 ------------------------------------------
  90 VF
  91 ^^
  92 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
  93 these package types.
  94
  95 PNF
  96 ^^^
  97 Only the `ETSI SOL004 Tosca CSAR Package`_ is applicable for a PNF.
  98
  99 .. note::
 100    The PNF is not explicitly mentioned in ETSI NFV-SOL 004v2.6.1. There is a CR pending on the SOL004 specification
 101    describing the PNFD archive. SDC supports and expects the metadata section in the PNFD archive manifest to be
 102    aligned with this CR i.e. the entries contain the following names (keys)
 103
 104    - pnfd_provider
 105    - pnfd_name
 106    - pnfd_release_date_time
 107    - pnfd_archive_version
 108
 109    An example of valid manifest file metadata section
 110    ::
 111
 112       metadata:
 113           pnfd_name: MRF
 114           pnfd_provider: SunShineCompany
 115           pnfd_archive_version: 1.0
 116           pnfd_release_date_time: 2017-01-01T10:00:00+03:00
 117
 118 When the PNF package in onboarded, the PNFD (descriptor) is transformed from ETSI NFV-SOL 001 model to the internal
 119 ONAP model.
 120
 121 How does SDC determine which package type is being onboarded
 122 ------------------------------------------------------------
 123 SDC onboarding processes each of the package types differently. SDC determines which package type is being onboarded, and
 124 hence which logic to use.
 125
 126 If the ETSI SOL001 v2.5.1 model is selected during onboarding, SDC will always treat the package as an `ETSI SOL004 Tosca CSAR Package`_.
 127
 128 If the SDC AID model is selected during onboarding, SDC will determine the package type based on the following.
 129
 130 First SDC checks the extension of the package. If the package extension is *.zip* then the package is treated as a `Heat package`_ or `Basic Helm package support for CNF`_.
 131
 132 To determine whether the package is of type Helm, SDC looks into the package content and tries to find Helm base files if not found it will treat it as Heat.
 133
 134 If it determines that this is a Helm package, SDC will add dummy Heat descriptor files.
 135
 136 If the package extension is *.csar* and the following is true
 137
 138 - CSAR package contains TOSCA-Metadata directory
 139 - The TOSCA.meta file exists within the TOSCA-Metadata directory
 140 - The TOSCA.meta file contains the following keynames in block_0
 141
 142    - Entry-Definitions
 143    - ETSI-Entry-Manifest
 144    - ETSI-Entry-Change-Log
 145
 146 then the package is treated as an `ETSI SOL004 Tosca CSAR Package`_. Otherwise the package is treated as an `ONAP Tosca CSAR Package`_.
 147
 148 Package Security
 149 ----------------
 150 SDC validates the authenticity and integrity of onboarding packages that are secured according to
 151 Security option 2 described in `ETSI NFV-SOL 004v2.6.1`_.
 152
 153 In this option the whole package is signed and delivered as part of a zip file. SDC supports both zip file structures
 154 specified in the standard i.e
 155
 156 1. Zip file containing 3 artifacts
 157
 158    a. Package
 159    b. Signing Certificate File
 160    c. Signature File
 161
 162 2. Zip file containing 2 artifacts
 163
 164    a. Package
 165    b. Signature File containing signing certificate
 166
 167 SDC supports the signature in Cryptographic Message Syntax (CMS) format.
 168
 169 .. note::
 170    For SDC to validate the authenticity and integrity of the onboarding package, the root certificate of the trusted CA
 171    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>`.
 172
 173 .. _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
 174 .. _ETSI NFV-SOL 004v2.5.1: https://docbox.etsi.org/ISG/NFV/Open/Publications_pdf/Specs-Reports/NFV-SOL%20004v2.5.1%20-%20GS%20-%20VNF%20Package%20Stage%203%20spec.pdf
 175 .. _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