From 1a252d968a6a11ae1ec1944018a5a7556515610b Mon Sep 17 00:00:00 2001 From: "bilal.iqbal" Date: Wed, 14 Aug 2019 15:15:45 +0000 Subject: Updating documentation on onboarding packages Change-Id: Id167f34e918e15856d7c86b9f7c767e1e3f4a0bb Issue-ID: DOC-521 Signed-off-by: bilal.iqbal --- docs/onboardingpackages.rst | 130 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/onboardingpackages.rst (limited to 'docs/onboardingpackages.rst') diff --git a/docs/onboardingpackages.rst b/docs/onboardingpackages.rst new file mode 100644 index 0000000000..dac1a88606 --- /dev/null +++ b/docs/onboardingpackages.rst @@ -0,0 +1,130 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _sdc_onboarding_package_types: + +======================== +Onboarding Package Types +======================== + +Supported Package Types +----------------------- +SDC supports the following packages types + +- Heat Package +- ONAP Tosca CSAR Package +- ETSI SOL004 Tosca CSAR Package + +Heat Package +^^^^^^^^^^^^ +The heat package is a zip archive with a .zip extension. The package contains heat template yaml file(s), corresponding +environment file(s) and a MANIFEST.json file. The MANIFEST.json file describes the contents of the package. + +There must be at least one heat template yaml file in the package whose name starts with *base_*. The other heat +templates in the package can have any name. All environment files that are included in the package must have the same +name as its corresponding yaml file with a .env file extension. + +An example of a simple heat package stucture is a zip archive containing the following 3 files + +- base_vFW.yaml (heat template) +- base_vFW.env (corresponding environment file) +- MANIFEST.json (describes files included in the package) + +Examples of heat packages are the packages with .zip extension available in `SDC git repo `_ + +ONAP Tosca CSAR Package +^^^^^^^^^^^^^^^^^^^^^^^ +The ONAP Tosca CSAR package is a zip archive with a .csar extension. The structure of the CSAR package is as described +in `ONAP wiki page `_ + +ETSI SOL004 Tosca CSAR Package +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The ETSI SOL004 Tosca CSAR Package is a zip archive with a .csar extension. The structure of the supported CSAR package +is as described in `ETSI NFV-SOL 004v2.6.1`_ csar structure option 1 i.e. CSAR containing a TOSCA-Metadata directory. + +The supported descriptor included in the package is aligned to `ETSI NFV-SOL 001v2.5.1 `_ + +Other Points to note when onboarding this package are: + +- During onboarding the ETSI NFV-SOL004 CSAR structure is transformed to the internal ONAP CSAR structure. +- The original input CSAR is maintained and stored as the SDC artifact *ONBOARDED_PACKAGE* in the xNF internal model. +- The non-mano artifacts are mapped to the corresponding SDC Artifact Type in the xNF internal model. + +Package Types applicable to Resource Types +------------------------------------------ +VF +^^ +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 +these package types. + +PNF +^^^ +Only the `ETSI SOL004 Tosca CSAR Package`_ is applicable for a PNF. + +.. note:: + The PNF is not explicitly mentioned in ETSI NFV-SOL 004v2.6.1. There is a CR pending on the SOL004 specification + describing the PNFD archive. SDC supports and expects the metadata section in the PNFD archive manifest to be + aligned with this CR i.e. the entries contain the following names (keys) + + - pnfd_provider + - pnfd_name + - pnfd_release_date_time + - pnfd_archive_version + + An example of valid manifest file metadata section + :: + + metadata: + pnfd_name: MRF + pnfd_provider: SunShineCompany + pnfd_archive_version: 1.0 + pnfd_release_date_time: 2017-01-01T10:00:00+03:00 + +When the PNF package in onboarded, the PNFD (descriptor) is transformed from ETSI NFV-SOL 001 model to the internal +ONAP model. + +How does SDC determine which package type is being onboarded +------------------------------------------------------------ +SDC onboarding processes each of the package types differently. SDC determines which package type is being onboarded, and +hence which logic to use, based on the following + +First SDC checks the extension of the package. If the package extension is *.zip* then the package is treated as a `Heat package`_. + +If the package extension is *.csar* and the following is true + +- CSAR package contains TOSCA-Metadata directory +- The TOSCA.meta file exists within the TOSCA-Metadata directory +- The TOSCA.meta file contains the following keynames in block_0 + + - Entry-Definitions + - ETSI-Entry-Manifest + - ETSI-Entry-Change-Log + +then the package is treated as an `ETSI SOL004 Tosca CSAR Package`_. Otherwise the package is treated as an `ONAP Tosca CSAR Package`_. + +Package Security +---------------- +SDC validates the authenticity and integrity of onboarding packages that are secured according to +Security option 2 described in `ETSI NFV-SOL 004v2.6.1`_. + +In this option the whole package is signed and delivered as part of a zip file. SDC supports both zip file structures +specified in the standard i.e + +1. Zip file containing 3 artifacts + + a. Package + b. Signing Certificate File + c. Signature File + +2. Zip file containing 2 artifacts + + a. Package + b. Signature File containing signing certificate + +SDC supports the signature in Cryptographic Message Syntax (CMS) format. + +.. note:: + For SDC to validate the authenticity and integrity of the onboarding package, the root certificate of the trusted CA + needs to be pre-installed in SDC before onboarding is started. The details of this procedure are described :ref:`here `. + +.. _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 \ No newline at end of file -- cgit 1.2.3-korg