Update use cases, requirements, etc

JIRA: COPPER-3

Change-Id: I9cccac8afb95e8d08e0e8aeef0934f24c59a40d7
Signed-off-by: blsaws <bs3131@att.com>

7 files changed, 185 insertions, 73 deletions

diff --git a/design_docs/architecture.rst b/design_docs/architecture.rst
index bd91ffb..9949c1a 100644
--- a/design_docs/architecture.rst
+++ b/design_docs/architecture.rst
@@ -10,13 +10,13 @@ The following example diagram illustrates a "relationship diagram" type view of
    :alt: policy_architecture.png
    :align: center
 
-(source of the diagram above: https://wiki.opnfv.org/_media/copper/copper_work_items/policy_architecture.pptx)
+(source of the diagram above: https://git.opnfv.org/cgit/copper/plain/design_docs/images/policy_architecture.pptx)
 
 Architectural Aspects
 ---------------------
   * Policies are reflected in two high-level goals
   
-    * Ensure resource requirements of VNFs are applied per VNF designer, service, and tenant intent
+    * Ensure resource requirements of VNFs and services are applied per VNF designer, service, and tenant intent
     * Ensure that generic policies are not violated, e.g. *networks connected to VMs must either be public or owned by the VM owner*
 
   * Policies are distributed through two main means
diff --git a/design_docs/definitions.rst b/design_docs/definitions.rst
index 26671f7..4423d45 100644
--- a/design_docs/definitions.rst
+++ b/design_docs/definitions.rst
@@ -12,3 +12,27 @@ Definitions
 
    * - Event
      - An item of significance to the policy engine, for which the engine has become aware through some method of discovery e.g. polling or notification.
+
+Abbreviations
+=============
+.. list-table:: Abbreviations
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Term
+     - Meaning
+
+   * - CRUD
+     - Create, Read, Update, Delete (database operation types)
+
+   * - FCAPS
+     - Fault, Configuration, Accounting, Performance, Security
+
+   * - NF
+     - Network Function
+	 
+   * - SFC
+     - Service Function Chaining
+
+   * - VNF
+     - Virtual Network Function
diff --git a/design_docs/images/policy_architecture.png b/design_docs/images/policy_architecture.png
index d03f4b3..eb37e36 100644
--- a/design_docs/images/policy_architecture.png
+++ b/design_docs/images/policy_architecture.png
diff --git a/design_docs/images/policy_architecture.pptx b/design_docs/images/policy_architecture.pptx
index 3ff0a5b..5739f0f 100644
--- a/design_docs/images/policy_architecture.pptx
+++ b/design_docs/images/policy_architecture.pptx
diff --git a/design_docs/requirements.rst b/design_docs/requirements.rst
index b45f77d..90ccc5e 100644
--- a/design_docs/requirements.rst
+++ b/design_docs/requirements.rst
@@ -1,52 +1,72 @@
 Requirements
 ============
-General requirements for a policy architecture are below, with an assessment of the current state of support for these across major OPNFV components (1=poor, 5=excellent).
-
-  1. Polled monitoring: Exposure of state via request-response APIs.
-  2. Notifications: Exposure of state via pub-sub APIs.
-  3. Realtime/near-realtime notifications: Notifications that occur in actual or near realtime.
-  4. Delegated policy: CRUD operations on policies that are distributed to specific components for local handling, including one/more of monitoring, violation reporting, and enforcement.
-  5. Violation reporting: Reporting of conditions that represent a policy violation.
-  6. Reactive enforcement: Enforcement actions taken in response to policy violation events.
-  7. Proactive enforcement: Enforcement actions taken in advance of policy violation events, e.g. blocking actions that could result in a policy violation.
-  8. Compliance auditing: Periodic auditing of state against policies.
-  
-.. list-table:: Table 1: Assessment of NFVI VIM Support for General Requirements
-   :widths: 10 40 40
-   :header-rows: 1
-
-   * - #
-     - OpenStack
-     - OpenDaylight
-     
-   * - 1
-     - 
-     - 
-
-   * - 2
-     - 
-     - 
-
-   * - 3
-     - 
-     - 
-
-   * - 4
-     - 
-     - 
-
-   * - 5
-     - 
-     - 
-
-   * - 6
-     - 
-     - 
-
-   * - 7
-     - 
-     - 
-
-   * - 8
-     - 
-     - 
+This section outlines general requirements for configuration policies, per the two main aspects in the Copper project scope:
+	* Ensuring resource requirements of VNFs and services are applied per VNF designer, service, and tenant intent
+	* Ensuring that generic policies are not violated, e.g. *networks connected to VMs must either be public or owned by the VM owner*
+	
+Resource Requirements
++++++++++++++++++++++
+Resource requirements describe the characteristics of virtual resources (compute, storage, network) that are needed for VNFs and services, and how those resources should be managed over the lifecycle of a VNF/service. Upstream projects  already include multiple ways in which resource requirements can be expressed and fulfilled, e.g.:
+	* OpenStack Nova
+		* the `image <http://docs.openstack.org/openstack-ops/content/user_facing_images.html>`_ feature, enabling "VM templates" to be defined for NFs, and referenced by name as a specific NF version to be used
+		* the `flavor <http://docs.openstack.org/openstack-ops/content/flavors.html>`_ feature, addressing basic compute and storage requirements, with extensibility for custom attributes
+	* OpenStack Heat
+		* the `Heat Orchestration Template <http://docs.openstack.org/developer/heat/template_guide/index.html>`_ feature, enabling a variety of VM aspects to be defined and managed by Heat throughout the VM lifecycle, notably
+			* alarm handling (requires `Ceilometer <https://wiki.openstack.org/wiki/Ceilometer>`_)
+			* attached volumes (requires `Cinder <https://wiki.openstack.org/wiki/Cinder>`_)
+			* domain name assignment (requires `Designate <https://wiki.openstack.org/wiki/Designate>`_)
+			* images (requires `Glance <https://wiki.openstack.org/wiki/Glance>`_)
+			* autoscaling
+			* software configuration associated with VM "lifecycle hooks (CREATE, UPDATE, SUSPEND, RESUME, DELETE"
+			* wait conditions and signaling for sequencing orchestration steps
+			* orchestration service user management (requires `Keystone <http://docs.openstack.org/developer/keystone/>`_)
+			* shared storage (requires `Manila <https://wiki.openstack.org/wiki/Manila>`_)
+			* load balancing (requires Neutron `LBaaS <http://docs.openstack.org/admin-guide-cloud/content/section_lbaas-overview.html>`_)
+			* firewalls (requires Neutron `FWaaS <http://docs.openstack.org/admin-guide-cloud/content/install_neutron-fwaas-agent.html>`_)
+			* various Neutron-based network and security configuration items
+			* Nova flavors
+			* Nova server attributes including access control
+			* Nova server group affinity and anti-affinity
+			* "Data-intensive application clustering" (requires `Sahara <https://wiki.openstack.org/wiki/Sahara>`_)
+			* DBaaS (requires `Trove <http://docs.openstack.org/developer/trove/>`_)
+			* "multi-tenant cloud messaging and notification service" (requires `Zaqar <http://docs.openstack.org/developer/zaqar/>`_)
+	* OpenStack `Group-Based Policy <https://wiki.openstack.org/wiki/GroupBasedPolicy>`_
+		* API-based grouping of endpoints with associated contractual expectations for data flow processing and service chaining
+	* OpenStack `Tacker <https://wiki.openstack.org/wiki/Tacker>`_
+		* "a fully functional ETSI MANO based general purpose NFV Orchestrator and VNF Manager for OpenStack"
+	* OpenDaylight `Group-Based Policy <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`_
+		* model-based grouping of endpoints with associated contractual expectations for data flow processing
+	* OpenDaylight `Service Function Chaining (SFC) <https://wiki.opendaylight.org/view/Service_Function_Chaining:Main>`_
+		* model-based management of "service chains" and the infrastucture that enables them
+	* Additional projects that are commonly used for configuration management, implemented as client-server frameworks using model-based, declarative, or scripted configuration management data.
+		* `Puppet <https://puppetlabs.com/puppet/puppet-open-source>`_ 
+		* `Chef <https://www.chef.io/chef/>`_ 
+		* `Ansible <http://docs.ansible.com/ansible/index.html>`_
+		* `Salt <http://saltstack.com/community/>`_ 	
+	
+Generic Policy Requirements
++++++++++++++++++++++++++++	
+Generic policy requirements address conditions related to resource state and events which need to be monitored for, and optionally responded to or prevented. These conditions are typically expected to be VNF/service-independent, as VNF/service-dependent condition handling (e.g. scale in/out) are considered to be addressed by VNFM/NFVO/VIM functions as described under Resource Requirements or as FCAPS related functions. However the general capabilities below can be applied to VNF/service-specific policy handling as well, or in particular to invocation of VNF/service-specific management/orchestration actions. The high-level required capabilities include:
+	* Polled monitoring: Exposure of state via request-response APIs.
+	* Notifications: Exposure of state via pub-sub APIs.
+	* Realtime/near-realtime notifications: Notifications that occur in actual or near realtime.
+	* Delegated policy: CRUD operations on policies that are distributed to specific components for local handling, including one/more of monitoring, violation reporting, and enforcement.
+	* Violation reporting: Reporting of conditions that represent a policy violation.
+	* Reactive enforcement: Enforcement actions taken in response to policy violation events.
+	* Proactive enforcement: Enforcement actions taken in advance of policy violation events, e.g. blocking actions that could result in a policy violation.
+	* Compliance auditing: Periodic auditing of state against policies.
+ 
+ Upstream projects already include multiple ways in which configuration conditions can be monitored and responded to:
+	* OpenStack `Congress <https://wiki.openstack.org/wiki/Congress>`_ provides a table-based mechanism for state monitoring and proactive/reactive policy enforcement, including (as of the Kilo release) data obtained from internal databases of Nova, Neutron, Ceilometer, Cinder, Glance, Keystone, and Swift. The Congress design approach is also extensible to other VIMs (e.g. SDNCs) through development of data source drivers for the new monitored state information.
+	* OpenStack `Ceilometer <https://wiki.openstack.org/wiki/Ceilometer>`_ provides means to trigger alarms upon a wide variety of conditions derived from its monitored OpenStack analytics.
+	* `Nagios <https://www.nagios.org/#/>`_ "offers complete monitoring and alerting for servers, switches, applications, and services".
+	
+Requirements Validation Approach
+++++++++++++++++++++++++++++++++
+The Copper project will assess the completeness of the upstream project solutions for requirements in scope though a process of:
+	* developing configuration policy use cases to focus solution assessment tests
+	* integrating the projects into the OPNFV platform for testing
+	* executing functional and performance tests for the solutions
+	* assessing overall requirements coverage and gaps in the most complete upstream solutions
+	
+Depending upon the priority of discovered gaps, new requirements will be submitted to upstream projects for the next available release cycle.
\ No newline at end of file
diff --git a/design_docs/usecases.rst b/design_docs/usecases.rst
index 33f9d78..7d55c87 100644
--- a/design_docs/usecases.rst
+++ b/design_docs/usecases.rst
@@ -1,13 +1,99 @@
 Use Cases
 =========
 
+Resource Requirements
++++++++++++++++++++++
+
+Workload Placement
+------------------
+
+Affinity
+........
+
+Ensures that the VM instance is launched "with affinity to" specific resources, e.g. within a compute or storage cluster. This is analogous to the affinity rules in `VMWare vSphere DRS <https://pubs.vmware.com/vsphere-50/topic/com.vmware.vsphere.resmgmt.doc_50/GUID-FF28F29C-8B67-4EFF-A2EF-63B3537E6934.html>`_. Examples include: "Same Host Filter", i.e. place on the same compute node as a given set of instances, e.g. as defined in a scheduler hint list.
+
+As implemented by OpenStack Heat using server groups:
+
+*Note: untested example...*
+
+.. code::
+
+	resources: 
+	  servgrp1: 
+		type: OS::Nova::ServerGroup
+		properties: 
+		  policies: 
+		  - affinity
+		  serv1:
+			type: OS::Nova::Server
+			properties:
+				image: { get_param: image }
+				flavor: { get_param: flavor }
+				networks:
+					- network: {get_param: network}
+		  serv2:
+			type: OS::Nova::Server
+			properties:
+				image: { get_param: image }
+				flavor: { get_param: flavor }
+				networks:
+					- network: {get_param: network}
+
+Anti-Affinity
+.............
+
+Ensures that the VM instance is launched "with anti-affinity to" specific resources, e.g. outside a compute or storage cluster, or geographic location. This filter is analogous to the anti-affinity rules in vSphere DRS. Examples include: "Different Host Filter", i.e. ensures that the VM instance is launched on a different compute node from a given set of instances, as defined in a scheduler hint list.
+
+As implemented by OpenStack Heat using scheduler hints:
+
+*Note: untested example...*
+
+.. code::
+
+	heat template version: 2013-05-23
+	parameters:
+	  image:
+		type: string
+		default: TestVM
+	  flavor:
+		type: string
+		default: m1.micro
+	  network:
+		type: string
+		default: cirros_net2
+	resources:
+	  serv1:
+		type: OS::Nova::Server
+		properties:
+			image: { get_param: image }
+			flavor: { get_param: flavor }
+			networks:
+				- network: {get_param: network}
+			scheduler_hints: {different_host: {get_resource: serv2}}
+	  serv2:
+		type: OS::Nova::Server
+		properties:
+			image: { get_param: image }
+			flavor: { get_param: flavor }
+			networks:
+				- network: {get_param: network}
+			scheduler_hints: {different_host: {get_resource: serv1}}
+
+Configuration Auditing
+----------------------
+
+As a service provider or tenant, I need to periodically verify that resource configuration requirements have not been violated, as a backup means to proactive or reactive policy enforcement.
+
+Generic Policy Requirements
++++++++++++++++++++++++++++
+
 NFVI Self-Service Constraints
 -----------------------------
 
 As an NFVI provider, I need to ensure that my self-service tenants are not able to configure their VNFs in ways that would impact other tenants or the reliability, security, etc of the NFVI.
 
-Example: Network Access Control
-...............................
+Network Access Control
+......................
 
 Networks connected to VMs must be public, or owned by someone in the VM owner's group.
 
@@ -75,21 +161,3 @@ As implemented through OpenStack Congress:
   nova:servers(vm, vm_name, user_id),
   keystone:users(user_id, email)
 
-Workload Placement
-------------------
-
-Affinity
-........
-
-Ensures that the VM instance is launched "with affinity to" specific resources, e.g. within a compute or storage cluster. This is analogous to the affinity rules in `VMWare vSphere DRS <https://pubs.vmware.com/vsphere-50/topic/com.vmware.vsphere.resmgmt.doc_50/GUID-FF28F29C-8B67-4EFF-A2EF-63B3537E6934.html>`_. Examples include: "Same Host Filter", i.e. place on the same compute node as a given set of instances, e.g. as defined in a scheduler hint list.
-
-Anti-Affinity
-.............
-
-Ensures that the VM instance is launched "with anti-affinity to" specific resources, e.g. outside a compute or storage cluster, or geographic location. This filter is analogous to the anti-affinity rules in vSphere DRS. Examples include: "Different Host Filter", i.e. ensures that the VM instance is launched on a different compute node from a given set of instances, as defined in a scheduler hint list.
-
-Configuration Auditing
-----------------------
-
-As a service provider or tenant, I need to periodically verify that resource configuration requirements have not been violated, as a backup means to proactive or reactive policy enforcement.
-
diff --git a/etc/conf.py b/etc/conf.py
index 6a26dab..486983f 100644
--- a/etc/conf.py
+++ b/etc/conf.py
@@ -28,7 +28,7 @@ latex_elements = {
     'printindex': '',
 }
 
-project = u'Copper: Virtual Infrastructure Deploy;ment Policies'
+project = u'Copper: Virtual Infrastructure Deployment Policies'
 copyright = u'%s, OPNFV' % datetime.date.today().year
 version = u'1.0.0'
 release = u'1.0.0'
\ No newline at end of file