[VNFRQTS] break up larger rst files into toxtree

Broke all chapter files up so they follow the same patter

Change-Id: I8a2152b92f0568cf4858615054bb66fabf0ea343
Issue-ID: VNFRQTS-253
Signed-off-by: stark, steven <ss820f@att.com>

1 files changed, 352 insertions, 0 deletions

diff --git a/docs/Chapter4/Modularity.rst b/docs/Chapter4/Modularity.rst
new file mode 100644
index 0000000..12024bd
--- /dev/null
+++ b/docs/Chapter4/Modularity.rst
@@ -0,0 +1,352 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
+
+
+VNF Modularity
+--------------
+
+ONAP Heat Orchestration Templates: Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ONAP supports a modular Heat Orchestration Template design pattern,
+referred to as *VNF Modularity.*
+
+ONAP VNF Modularity Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With VNF Modularity, a single VNF may be composed from one or more Heat
+Orchestration Templates, each of which represents a subset of the
+overall VNF. These component parts are referred to as “\ *VNF
+Modules*\ ”. During orchestration, these modules are deployed
+incrementally to create the complete VNF.
+
+A modular Heat Orchestration Template can be either one of the following
+types:
+
+1. Base Module
+
+2. Incremental Module
+
+3. Cinder Volume Module
+
+* R-37028 The VNF **MUST** be composed of one “base” module.
+* R-41215 The VNF **MAY** have zero to many “incremental” modules.
+* R-20974 The VNF **MUST** deploy the base module first, prior to
+  the incremental modules.
+
+ONAP also supports the concept of an optional, independently deployed
+Cinder volume via a separate Heat Orchestration Templates, referred to
+as a Cinder Volume Module. This allows the volume to persist after a
+Virtual Machine (VM) (i.e., OS::Nova::Server) is deleted, allowing the
+volume to be reused on another instance (e.g., during a failover
+activity).
+
+* R-11200 The VNF **MUST** keep the scope of a Cinder volume module,
+  when it exists, to be 1:1 with the VNF Base Module or Incremental Module.
+
+* R-38474 The VNF **MUST** have a corresponding environment file for
+  a Base Module.
+* R-81725 The VNF **MUST** have a corresponding environment file for
+  an Incremental Module.
+* R-53433 The VNF **MUST** have a corresponding environment file for
+  a Cinder Volume Module.
+
+These concepts will be described in more detail throughout the document.
+This overview is provided to set the stage and help clarify the concepts
+that will be introduced.
+
+
+ONAP VNF Modularity
+^^^^^^^^^^^^^^^^^^^^^^
+
+ONAP supports a modular Heat Orchestration Template design pattern,
+referred to as *VNF Modularity.* With this approach, a single VNF may be
+composed from one or more Heat Orchestration Templates, each of which
+represents a subset of the overall VNF. These component parts are
+referred to as “\ *VNF Modules*\ ”. During orchestration, these modules
+are deployed incrementally to create the complete VNF.
+
+A modular Heat Orchestration Template can be either one of the following
+types:
+
+1. Base Module
+
+2. Incremental Module
+
+3. Cinder Volume Module
+
+A VNF must be composed of one “base” module and may be composed of zero
+to many “incremental” modules. The base module must be deployed first,
+prior to the incremental modules.
+
+ONAP also supports the concept of an optional, independently deployed
+Cinder volume via a separate Heat Orchestration Templates, referred to
+as a Cinder Volume Module. This allows the volume to persist after a VM
+(i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on
+another instance (e.g., during a failover activity).
+
+The scope of a Cinder volume module, when it exists, must be 1:1 with a
+Base module or Incremental Module.
+
+A Base Module must have a corresponding environment file.
+
+An Incremental Module must have a corresponding environment file.
+
+A Cinder Volume Module must have a corresponding environment file.
+
+A VNF module (base, incremental, cinder) may support nested templates.
+
+A shared Heat Orchestration Template resource must be defined in the
+base module. A shared resource is a resource that that will be
+referenced by another resource that is defined in the Base Module and/or
+one or more incremental modules.
+
+When the shared resource needs to be referenced by a resource in an
+incremental module, the UUID of the shared resource must be exposed by
+declaring an ONAP Base Module Output Parameter.
+
+Note that a Cinder volume is *not* a shared resource. A volume template
+must correspond 1:1 with a base module or incremental module.
+
+An example of a shared resource is the resource
+OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules
+that are applied to a VNF’s networking. The resource OS::Neutron::Port
+has a property security\_groups which provides the security groups
+associated with port. The value of parameter(s) associated with this
+property must be the UUIDs of the resource(s)
+OS::Neutron::SecurityGroup.
+
+*Note:* A Cinder volume is *not* considered a shared resource. A volume
+template must correspond 1:1 with a base template or add-on module
+template.
+
+Suggested Patterns for Modular VNFs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are numerous variations of VNF modularity. Below are two suggested
+usage patterns.
+
+**Option 1: Modules per VNFC type**
+
+a. Base module contains only the shared resources.
+
+b. Group all VMs (e.g., VNFCs) of a given type (i.e. {vm-type}) into its
+   own incremental module. That is, the VNF has an incremental module
+   for each {vm-type}.
+
+c. For a given {vm-type} incremental module, the VNF may have
+
+   i.  One incremental module used for both initial turn up and re-used
+       for scaling. This approach is used when the number of VMs
+       instantiated will be the same for initial deployment and scaling.
+
+   ii. Two incremental modules, where one is used for initial turn up
+       and one is used for scaling. This approach is used when the
+       number of VMs instantiated will be different for initial
+       deployment and scaling.
+
+**Option 2: Base VNF with Incremental Growth Modules**
+
+a. Base module contains a complete initial VNF instance
+
+b. Incremental modules for incremental scaling units
+
+   i.  May contain VMs of multiple types in logical scaling combinations
+
+   ii. May be separated by VM type for multi-dimensional scaling
+
+With no growth units, Option 2 is equivalent to the “One Heat Template
+per VNF” model.
+
+Note that modularization of VNFs is not required. A single Heat
+Orchestration Template (a base module) may still define a complete VNF,
+which might be appropriate for smaller VNFs that do not have any scaling
+options.
+
+Modularity Rules
+^^^^^^^^^^^^^^^^^^^
+
+There are some rules to follow when building modular VNF templates:
+
+1. All VNFs must have one Base VNF Module (template) that must be the
+   first one deployed. The base template:
+
+   a. Must include all shared resources (e.g., private networks, server
+      groups, security groups)
+
+   b. Must expose all shared resources (by UUID) as “outputs” in its
+      associated Heat template (i.e., ONAP Base Module Output
+      Parameters)
+
+   c. May include initial set of VMs
+
+   d. May be operational as a stand-alone “minimum” configuration of the
+      VNF
+
+2. VNFs may have one or more incremental modules which:
+
+   a. Defines additional resources that can be added to an existing VNF
+
+   b. Must be complete Heat templates
+
+      i. i.e. not snippets to be incorporated into some larger template
+
+   c. Should define logical growth-units or sub-components of an overall
+      VNF
+
+   d. On creation, receives appropriate Base Module outputs as
+      parameters
+
+      i.  Provides access to all shared resources (by UUID)
+
+      ii. must not be dependent on other Add-On VNF Modules
+
+   e. Multiple instances of an incremental Module may be added to the
+      same VNF (e.g., incrementally grow a VNF by a fixed “add-on”
+      growth units)
+
+3. Each VNF Module (base or incremental) may have (optional) an
+   associated Cinder Volume Module (see Cinder Volume Templates)
+
+   a. Volume modules must correspond 1:1 with a base module or
+      incremental module
+
+   b. A Cinder volume may be embedded within the base module or
+      incremental module if persistence is not required
+
+4. Shared resource UUIDs are passed between the base module and
+   incremental modules via Heat Outputs Parameters (i.e., Base Module
+   Output Parameters)
+
+   a. The output parameter name in the base must match the parameter
+      name in the add-on module
+
+VNF Modularity Examples
+^^^^^^^^^^^^^^^^^^^^^^^
+
+*Example: Base Module creates SecurityGroup*
+
+A VNF has a base module, named base.yaml, that defines a
+OS::Neutron::SecurityGroup. The security group will be referenced by an
+OS::Neutron::Port resource in an incremental module, named
+INCREMENTAL\_MODULE.yaml. The base module defines a parameter in the out
+section named dns\_sec\_grp\_id. dns\_sec\_grp\_id is defined as a
+parameter in the incremental module. ONAP captures the UUID value of
+dns\_sec\_grp\_id from the base module output statement and provides the
+value to the incremental module.
+
+Note that the example below is not a complete Heat Orchestration
+Template. The {network-role} has been defined as oam to represent an oam
+network and the {vm-type} has been defined as dns.
+
+base\_MODULE.yaml
+
+.. code-block:: yaml
+
+ parameters:
+   . . .
+
+ resources:
+   DNS_SECURITY_GROUP:
+     type: OS::Neutron::SecurityGroup
+     properties:
+       description: vDNS security group
+       name:
+         str_replace:
+           template: VNF_NAME_sec_grp_DNS
+           params:
+             VMF_NAME: {get_param: vnf_name}
+       rules: [. . . . .
+
+   . . .
+
+ outputs:
+   dns_sec_grp_id:
+     description: UUID of DNS Resource SecurityGroup
+     value: { get_resource: DNS_SECURITY_GROUP }
+
+
+INCREMENTAL\_MODULE.yaml
+
+.. code-block:: yaml
+
+ parameters:
+   dns_sec_grp_id:
+     type: string
+     description: security group UUID
+   . . .
+
+ resources:
+   dns_oam_0_port:
+     type: OS::Neutron::Port
+     properties:
+       name:
+         str_replace:
+           template: VNF_NAME_dns_oam_port
+           params:
+             VNF_NAME: {get_param: vnf_name}
+       network: { get_param: oam_net_name }
+       fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
+       security_groups: [{ get_param: dns_sec_grp_id }]
+
+
+*Examples: Base Module creates an internal network*
+
+A VNF has a base module, named base\_module.yaml, that creates an
+internal network. An incremental module, named incremental\_module.yaml,
+will create a VM that will connect to the internal network. The base
+module defines a parameter in the out section named int\_oam\_net\_id.
+int\_oam\_net\_id is defined as a parameter in the incremental module.
+ONAP captures the UUID value of int\_oam\_net\_id from the base module
+output statement and provides the value to the incremental module.
+
+Note that the example below is not a complete Heat Orchestration
+Template. The {network-role} has been defined as oam to represent an oam
+network and the {vm-type} has been defined as lb for load balancer.
+
+base.yaml
+
+.. code-block:: yaml
+
+ heat_template_version: 2013-05-23
+
+ resources:
+    int_oam_network:
+       type: OS::Neutron::Network
+       properties:
+          name: {… }
+          . . .
+ outputs:
+    int_oam_net_id:
+       value: {get_resource: int_oam_network }
+
+
+incremental.yaml
+
+.. code-block:: yaml
+
+ heat_template_version: 2013-05-23
+
+ parameters:
+    int_oam_net_id:
+       type: string
+       description: ID of shared private network from Base template
+    lb_name_0:
+       type: string
+       description: name for the add-on VM instance
+
+ Resources:
+    lb_server:
+       type: OS::Nova::Server
+       properties:
+          name: {get_param: lb_name_0}
+          networks:
+             - port: { get_resource: lb_port }
+          . . .
+
+    lb_port:
+       type: OS::Neutron::Port
+       properties:
+          network_id: { get_param: int_oam_net_id }
+ ...