6 files changed, 211 insertions, 0 deletions
diff --git a/docs/development/design/architecture.rst b/docs/development/design/architecture.rst
new file mode 100644
index 0000000..02d8335
--- /dev/null
+++ b/docs/development/design/architecture.rst
@@ -0,0 +1,100 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) 2015-2017 AT&T Intellectual Property, Inc
+
+Architecture
+============
+
+Architectural Concept
+---------------------
+The following example diagram illustrates a "relationship diagram" type view of
+an NFVI platform, in which the roles of components focused on policy management,
+services, and infrastructure are shown.
+
+This view illustrates that a large-scale deployment of NFVI may leverage multiple
+components of the same "type" (e.g. SDN Controller), which fulfill specific
+purposes for which they are optimized. For example, a global SDN controller and
+cloud orchestrator can act as directed by a service orchestrator in the
+provisioning of VNFs per intent, while various components at a local and global
+level handle policy-related events directly and/or feed them back through a
+closed-loop policy design that responds as needed, directly or through the
+service orchestrator.
+
+.. image:: ./images/policy_architecture.png
+   :width: 700 px
+   :alt: policy_architecture.png
+   :align: center
+
+(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 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
+
+    * As part of VNF packages, customized if needed by Service Design tools,
+      expressing intent of the VNF designer and service provider, and possibly
+      customized or supplemented by service orchestrators per the intent of
+      specific tenants
+    * As generic policies provisioned into VIMs (SDN controllers and cloud
+      orchestrators), expressing intent of the service provider re what
+      states/events need to be policy-governed independently of specific VNFs
+
+  * Policies are applied locally and in closed-loop systems per the capabilities
+    of the local policy enforcer and the impact of the related state/event conditions
+
+    * VIMs should be able to execute most policies locally
+    * VIMs may need to pass policy-related state/events to a closed-loop system,
+      where those events are relevant to other components in the architecture
+      (e.g. service orchestrator), or some additional data/arbitration is needed
+      to resolve the state/event condition
+
+  * Policies are localized as they are distributed/delegated
+
+    * High-level policies (e.g. expressing "intent") can be translated into VNF
+      package elements or generic policies, perhaps using distinct syntaxes
+    * Delegated policy syntaxes are likely VIM-specific, e.g. Datalog (Congress)
+
+  * Closed-loop policy and VNF-lifecycle event handling are //somewhat// distinct
+
+    * Closed-loop policy is mostly about resolving conditions that can't be
+      handled locally, but as above in some cases the conditions may be of
+      relevance and either delivered directly or forwarded to service orchestrators
+    * VNF-lifecycle events that can't be handled by the VIM locally are delivered
+      directly to the service orchestrator
+
+  * Some events/analytics need to be collected into a more "open-loop" system
+    which can enable other actions, e.g.
+
+    * audits and manual interventions
+    * machine-learning focused optimizations of policies (largely a future objective)
+
+Issues to be investigated as part of establishing an overall cohesive/adaptive
+policy architecture:
+
+  * For the various components which may fulfill a specific purpose, what
+    capabilities (e.g. APIs) do they have/need to
+
+    * handle events locally
+    * enable closed-loop policy handling components to subscribe/optimize
+      policy-related events that are of interest
+
+  * For global controllers and cloud orchestrators
+
+    * How do they support correlation of events impacting resources in different
+      scopes (network and cloud)
+    * What event/response flows apply to various policy use cases
+
+  * What specific policy use cases can/should fall into each overall class
+
+    * locally handled by NFVI components
+    * handled by a closed-loop policy system, either VNF/service-specific or
+      VNF-independent
diff --git a/docs/development/design/conf.py b/docs/development/design/conf.py
new file mode 100644
index 0000000..99b1ca2
--- /dev/null
+++ b/docs/development/design/conf.py
@@ -0,0 +1,50 @@
+# Copyright 2015 Open Platform for NFV Project, Inc. and its contributors
+#  
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#  
+# http://www.apache.org/licenses/LICENSE-2.0
+#  
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# What this is: Configuration file for OPNFV Copper project documentation
+# generation via Sphinx.
+#
+# Status: Tested and used in production of Copper project documentation.
+#
+
+import datetime
+import sys
+import os
+
+try:
+    __import__('imp').find_module('sphinx.ext.numfig')
+    extensions = ['sphinx.ext.numfig']
+except ImportError:
+    # 'pip install sphinx_numfig'
+    extensions = ['sphinx_numfig']
+
+# numfig:
+number_figures = True
+figure_caption_prefix = "Fig."
+
+source_suffix = '.rst'
+master_doc = 'index'
+pygments_style = 'sphinx'
+html_use_index = False
+html_theme = 'sphinx_rtd_theme'
+
+pdf_documents = [('index', u'OPNFV', u'OPNFV Copper Project', u'OPNFV')]
+pdf_fit_mode = "shrink"
+pdf_stylesheets = ['sphinx','kerning','a4']
+#latex_domain_indices = False
+#latex_use_modindex = False
+
+latex_elements = {
+    'printindex': '',
+}
diff --git a/docs/development/design/definitions.rst b/docs/development/design/definitions.rst
new file mode 100644
index 0000000..5552696
--- /dev/null
+++ b/docs/development/design/definitions.rst
@@ -0,0 +1,46 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) 2015-2017 AT&T Intellectual Property, Inc
+
+Definitions
+===========
+.. list-table:: Definitions
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Term
+     - Meaning
+
+   * - State
+     - Information that can be used to convey or imply the state of something, e.g. an application, resource, entity, etc. This can include data held inside OPNFV components, "events" that have occurred (e.g. "policy violation"), etc.
+
+   * - 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
+
+   * - NFVI
+     - Network Function Virtualization Infrastructure
diff --git a/docs/development/design/images/policy_architecture.png b/docs/development/design/images/policy_architecture.png
new file mode 100644
index 0000000..eb37e36
--- /dev/null
+++ b/docs/development/design/images/policy_architecture.png
diff --git a/docs/development/design/images/policy_architecture.pptx b/docs/development/design/images/policy_architecture.pptx
new file mode 100644
index 0000000..5739f0f
--- /dev/null
+++ b/docs/development/design/images/policy_architecture.pptx
diff --git a/docs/development/design/index.rst b/docs/development/design/index.rst
new file mode 100644
index 0000000..aa51e54
--- /dev/null
+++ b/docs/development/design/index.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) 2015-2017 AT&T Intellectual Property, Inc
+
+==========================
+OPNFV Copper Danube Design
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   definitions.rst
+   architecture.rst
+