add some initial documentation for the NIC project

Change-Id: I53789181e7f9a827fcace4a23b367977e869199d
Signed-off-by: David K. Bainbridge <[email protected]>

Author: dbainbri-ciena

manuals/developer-guide/src/main/asciidoc/bk-developers-guide.adoc

@@ -52,7 +52,7 @@ include::iotdm/iotdm-dev.adoc[]
 
 include::lacp/lacp-dev.adoc[]
 
-include::nic/nic-model-dev.adoc[]
+include::nic/nic-dev.adoc[]
 
 include::neutron/neutron.adoc[]
 

manuals/developer-guide/src/main/asciidoc/nic/nic-dev.adoc

@@ -0,0 +1,58 @@
+== Network Intent Composition (NIC) Developer Guide
+
+=== Overview
+The Network Intent Composition (NIC) provides four features:
+
+* odl-nic-core - the basic model and infrastructure for the NIC capabilities
+
+* odl-nic-cli - support for the Karaf console CLI NIC commands
+
+* odl-nic-renderer-vtn - a feature that transforms an intent to a network
+modification using the VTN project
+
+* odl-nic-renderer-gbp - a feature that transforms an intent to a network
+modification using the Group Policy project
+
+_Only a single renderer feature should be installed at a time for the Lithium
+release._
+
+=== odl-nic-core
+This feature supplies the base models for the Network Intent Composition (NIC)
+capability. This includes the definition of intent as well as the configuration
+and operational data trees.
+
+This feature only provides an information model. The interface for NIC is to
+modify the information model via the configuraiton data tree, which will
+trigger the renderer to make the appropriate changes in the controlled
+network.
+
+==== POST / PUT (configuration)
+This operations create instances of an intent in the configuration data tree
+and trigger the creation or modification of an intent.
+
+==== GET (configuration / operational)
+This operation lists all or fetches a single intent from the data tree.
+
+==== DELETE (configuration)
+This operation will cause an intent to be removed from the system and trigger
+any configuration changes on the network rendered from this intent to be
+removed.
+
+=== odl-nic-cli
+This feature provides karaf console CLI command to manipulate the intent
+data model. The CLI essentailly invokes the equivalent data operations.
+
+==== intent:add
+Creates a new intent in the configuration data tree
+
+==== intent:update
+Updates an existing intent in the configuration data tree
+
+==== intent:delete
+Removes an existing intent from the system
+
+==== intent:list
+Lists all the intents in the system
+
+==== intent:show
+Displayes the details of a single intent

manuals/developer-guide/src/main/asciidoc/nic/nic-model-dev.adoc

@@ -42,10 +42,12 @@ include::usc/odl-usc-channel-user.adoc[USC]
 
 include::ttp/ttp-cli-tools-user.adoc[TTP]
 
-include::capwap/capwap-user.adoc[CAPWAP] 
+include::capwap/capwap-user.adoc[CAPWAP]
 
 include::tsdr/tsdr-hbase-user.adoc[]
 
 include::tsdr/tsdr-h2-user.adoc[]
 
 include::didm/didm-user.adoc[]
+
+include::nic/nic-user.adoc[NIC]

manuals/user-guide/src/main/asciidoc/bk-user-guide.adoc

@@ -0,0 +1,94 @@
+== Network Intent Composition (NIC) User Guide
+
+=== Overview
+Network Intent Composition (NIC) is an interface that allows clients to
+express a desired state in an implementation-neutral form that will be
+enforced via modification of available resources under the control of
+the OpenDaylight system.
+
+This description is purposely abstract as an intent interface might
+encompass network services, virtual devices, storage, etc.
+
+The intent interface is meant to be a controller-agnostic interface
+so that "intents" are portable across implementations, such as OpenDaylight
+and ONOS. Thus an intent specification should not contain implementation
+or technology specifics.
+
+The intent specification will be implemented by decomposing the intent
+and augmenting it with implementation specifics that are driven by
+local implementation rules, policies, and/or settings.
+
+=== Network Intent Composition (NIC) Architecture
+The core of the NIC architecture is the intent model, which specifies
+the details of the desired state. It is the responsibility of the NIC
+implementation transforms this desired state to the resources under
+the control of OpenDaylight. The component that transforms the
+intent to the implementation is typically referred to as a renderer.
+
+For the Lithium release, multiple, simultaneous renderers will not be supported.
+Instead either the VTN or GBP renderer feature can be installed, but
+not both.
+
+For the Litium release, the only actions supported are "ALLOW" and
+"BLOCK". The "ALLOW" action indicates that traffic can flow between
+the source and destination end points, while "BLOCK" prevents that
+flow; although it is possible that an given implementation may augment
+the available actions with additional actions.
+
+Besides transforming a desired state to an actual state it is the
+responsibility of a renderer to update the operational state tree for
+the NIC data model in OpenDaylight to reflect the intent which the
+renderer implemented.
+
+=== Configuring Network Intent Composition (NIC)
+For the Litium release there is no default implementation of a renderer,
+thus without an additional module installed the NIC will not function.
+
+=== Administering or Managing Network Intent Composition (NIC)
+There is no additional administration of management capabilities
+related to the Network Intent Composition features.
+
+=== Interactions
+A user can interact with the Network Intent Composition (NIC) either
+through the RESTful interface using standard RESTCONF operations and
+syntax or via the Karaf console CLI.
+
+==== REST
+
+===== Configuration
+The Network Intent Composition (NIC) feature supports the following REST
+operations against the configuration data store.
+
+* POST - creates a new instance of an intent in the configuration store,
+which will trigger the realization of that intent. An ID _must_ be specified
+as part of this request as an attribute of the intent.
+
+* PUT - creates or updates an instance of an intent in the configuration store,
+which will trigger the realization of that intent.
+
+* GET - fetches a list of all configured intents or a specific configured
+intent.
+
+* DETELE - removes a configured intent from the configuration store, which
+triggers the removal of the intent from the network.
+
+===== Operational
+The Network Intent Composition (NIC) feature supports the following REST
+operations against the operational data store.
+
+* GET - fetches a list of all operational intents or a specific operational
+intent.
+
+==== Karaf Console CLI
+Using the Karaf console CLI intents can be manipulated. The following Karaf
+console CLI commands are available.
+
+* intent:add <intent-data> - creates a new intent
+
+* intent:update <id> <intent-data> - updates an existing intent
+
+* intent:list - lists all intents in the system
+
+* intent:show <id> - display the details of a specific intent
+
+* intent:delete <id> - removes an intent from the system