[VNFRQTS] updates to internal & external network def

Issue-ID: VNFRQTS-759
Signed-off-by: weinstock, alan <aw2574@att.com>
Change-Id: I3a9531a826a0e809daf6fb46d9707b63b7551798
Signed-off-by: weinstock, alan <aw2574@att.com>

1 files changed, 87 insertions, 50 deletions

diff --git a/docs/Chapter5/Heat/ONAP Heat Networking.rst b/docs/Chapter5/Heat/ONAP Heat Networking.rst
index 81ad997..754f455 100644
--- a/docs/Chapter5/Heat/ONAP Heat Networking.rst
+++ b/docs/Chapter5/Heat/ONAP Heat Networking.rst
@@ -12,50 +12,68 @@ ONAP defines two types of networks: External Networks and Internal Networks.
 External Networks
 ^^^^^^^^^^^^^^^^^^^^
 
-ONAP defines an external network in relation to the VNF and not with regard
-to the Network Cloud site. External networks may also be referred to as
-"inter-VNF" networks.  An external network must connect VMs in a VNF to
-VMs in another VNF or an external gateway or external router.
+An ONAP external network is created by using VID or by invoking SO directly
+to instantiate the network.
+External networks are orchestrated separately, independent of VNFs.
+A network instantiated via VID or by invoking SO directly is managed by
+ONAP and is inventoried in AAI.
 
-An External Network may be a Neutron Network or a Contrail Network.
+An external network can be created by using one of the following
+resources:
 
+- ``OS::Neutron::Net``
+- ``OS::Neutron::ProviderNet``
+- ``OS::ContrailV2::VirtualNetwork``
+
+An external network **MAY** be used to
+
+- Connect a VM in a VNF to VMs in another VNF
+- Connect a VM in a VNF to an external gateway or external router
+- Connect a VM in a VNF to other VMs in the same VNF
+
+An external network may be designed to perform
+
+- All three functions listed above or
+- Perform only two functions listed above or
+- Perform only one function listed above
 
 .. req::
     :id: R-16968
     :target: VNF
     :keyword: MUST NOT
     :validation_mode: static
-    :updated: casablanca
+    :updated: frankfurt
 
     A VNF's Heat Orchestration Templates **MUST NOT** include heat
-    resources to create external networks.
+    resources to create an ONAP external network.
 
-External networks must be orchestrated separately, independent of the VNF.
-This allows the network to be shared by multiple VNFs and managed
-independently of VNFs.
+    An ONAP external network **MUST** be instantiated by using VID
+    or by invoking SO directly.
 
 
 .. req::
     :id: R-00606
     :target: VNF
     :keyword: MAY
-    :updated: casablanca
+    :updated: frankfurt
 
-    A VNF **MAY** be connected to zero, one or more than one external
+    A VNF **MAY** be connected to zero, one or more than one ONAP external
     network.
 
 .. req::
     :id: R-57424
     :target: VNF
-    :keyword: MUST
+    :keyword: MAY
     :validation_mode: none
-    :updated: casablanca
+    :updated: frankfurt
 
-    A VNF's port connected to an external network **MUST**
-    use the port for the purpose of reaching
-    VMs in another VNF and/or an external gateway and/or external router.
-    A VNF's port connected to an external network **MAY**
-    use the port for the purpose of reaching VMs in the same VNF.
+    A VNF's port connected to an ONAP external network **MAY**
+    use the port for the purpose of
+
+    - Connecting a VM in the VNF to VMs in another VNF and/or
+    - Connecting a VM in the VNF to an external gateway or external router
+      and/or
+    - Connecting a VM in the VNF to other VMs in the same VNF
 
 .. req::
     :id: R-99794
@@ -64,7 +82,7 @@ independently of VNFs.
     :validation_mode: none
     :updated: casablanca
 
-    An external network **MUST** have one subnet. An external network
+    An ONAP external network **MUST** have one subnet. An external network
     **MAY** have more than one subnet.
 
 ONAP enforces a naming convention for
@@ -76,35 +94,52 @@ provides additional details.
 Internal Networks
 ^^^^^^^^^^^^^^^^^^^^
 
-ONAP defines an internal network in relation to the VNF and not with
-regard to the Network Cloud site. Internal networks may also be referred
-to as "intra-VNF" networks or "private" networks. An internal network
-only connects VMs in a single VNF; it must not connect to other VNFs
-or an external gateway or router
+An ONAP internal network is created by the VNF's Heat Orchestration Template.
+That is, the VNF's Heat Orchestration Template contains the heat resources to
+instantiate the network.
+An ONAP internal network is not inventoried by AAI and can not be managed
+independently of the VNF.
+
+An ONAP internal network MUST only be used for connecting a VM in the
+VNF to other VMs in the same VNF.
+
+An ONAP internal network MUST NOT be used for connecting a VM in the VNF to
+VMs in another VNF or connecting a VM in the VNF to an external gateway and/or
+external router.
+
+The reason for this is for operational simplicity.  An ONAP internal network
+will be deleted when the VNF that created the network (referred to as VNF A)
+is deleted.  If a different VNF (referred to as VNF B) attaches to the ONAP
+internal network created by VNF A, then VNF B must be deleted prior VNF A.
 
+In addition, if an ONAP internal network is used to connect two (or more) VNFs,
+there is no record in AAI inventory.  This could lead to additional
+operational complications.
 
 .. req::
     :id: R-87096
     :target: VNF
     :keyword: MAY
-    :updated: casablanca
+    :updated: frankfurt
 
-    A VNF **MAY** contain zero, one or more than one internal network.
+    A VNF **MAY** contain zero, one or more than one ONAP internal network.
 
 .. req::
     :id: R-35666
     :target: VNF
     :keyword: MUST
     :validation_mode: static
-    :updated: dublin
+    :updated: frankfurt
 
-    If a VNF has an internal network, the VNF Heat Orchestration Template
-    **MUST** include the heat resources to create the internal network.
+    If a VNF has an ONAP internal network, the VNF's Heat Orchestration
+    Template **MUST** include the heat resources to create the
+    ONAP internal network.
 
-    A VNF's Internal Network is created using Neutron Heat Resources
-    (i.e., ``OS::Neutron::Net``, ``OS::Neutron::Subnet``) and/or
-    Contrail Heat Resources (i.e., ``OS::ContrailV2::VirtualNetwork``,
-    ``ContrailV2::NetworkIpam``).
+    A VNF's ONAP internal network is created using Neutron Heat Resources
+    (e.g., ``OS::Neutron::Net``, ``OS::Neutron::Subnet``,
+    ``OS::Neutron::ProviderNet``) and/or
+    Contrail Heat Resources (e.g., ``OS::ContrailV2::VirtualNetwork``,
+    ``OS::ContrailV2::NetworkIpam``).
 
 
 .. req::
@@ -112,9 +147,9 @@ or an external gateway or router
     :target: VNF
     :keyword: MUST
     :validation_mode: none
-    :updated: casablanca
+    :updated: frankfurt
 
-    A VNF's port connected to an internal network **MUST**
+    A VNF's port connected to an ONAP internal network **MUST**
     use the port for the purpose of reaching VMs in the same VNF.
 
 .. req::
@@ -122,9 +157,10 @@ or an external gateway or router
     :target: VNF
     :keyword: MUST NOT
     :validation_mode: none
-    :updated: casablanca
+    :updated: frankfurt
 
-    A VNF's port connected to an internal network **MUST NOT** use the port
+    A VNF's port connected to an ONAP internal network **MUST NOT**
+    use the port
     for the purpose of reaching VMs in another VNF and/or an
     external gateway and/or
     external router.
@@ -134,10 +170,10 @@ or an external gateway or router
     :target: VNF
     :keyword: MUST
     :validation_mode: static
-    :updated: casablanca
+    :updated: frankfurt
 
-    A VNF's internal network **MUST** have one subnet.
-    A VNF's internal network **MAY** have more than one subnet.
+    A VNF's ONAP internal network **MUST** have one subnet.
+    A VNF's ONAP internal network **MAY** have more than one subnet.
 
 .. req::
     :id: R-86972
@@ -145,8 +181,8 @@ or an external gateway or router
     :keyword: SHOULD
     :updated: casablanca
 
-    A VNF **SHOULD** create the internal network in the VNF's Heat
-    Orchestration Template Base Module.
+    A VNF **SHOULD** create the ONAP internal network in the VNF's Heat
+    Orchestration Template's Base Module.
 
 
 .. req::
@@ -154,12 +190,13 @@ or an external gateway or router
     :target: VNF
     :keyword: MUST
     :validation_mode: static
-    :updated: dublin
+    :updated: frankfurt
 
-    When a VNF's Heat Orchestration Template creates an internal network
+    When a VNF's Heat Orchestration Template creates an ONAP internal network
     (per the ONAP definition, see Requirements R-52425 and R-46461
-    and R-35666) and the internal network needs to be shared between modules
-    within a VNF,  the internal network **MUST** be created either in the
+    and R-35666) and the ONAP internal network needs to be shared between
+    modules within a VNF, the ONAP
+    internal network **MUST** be created either in the
 
     * the base module
     * a nested YAML file invoked by the base module
@@ -174,12 +211,12 @@ or an external gateway or router
       parameter name in the base template **MUST** follow the naming convention
       ``int_{network-role}_net_name``
 
-    ``{network-role}`` **MUST** be the network-role of the internal network
-    created in the Base Module.
+    The ``{network-role}`` **MUST** be the network-role of the ONAP
+    internal network created in the Base Module.
 
     The Base Module Output Parameter MUST be declared in the ``parameters:``
     section of the Incremental Module(s) where the ``OS::Neutron::Port``
-    resource(s) is attaching to the internal network.
+    resource(s) is attaching to the ONAP internal network.
 
 ONAP does not programmatically enforce a naming convention for
 parameters for internal network. However, a naming convention is