refactor instantiate section to be more "purpose" oriented

adding configure section
Issue-ID: DOC-500

Signed-off-by: Rene_Robert <rene.robert@orange.com>
Change-Id: I7f05b3ff526a501a70533f9a9506844477a73419

14 files changed, 369 insertions, 54 deletions

diff --git a/docs/guides/onap-user/configure/change_config/index.rst b/docs/guides/onap-user/configure/change_config/index.rst
new file mode 100644
index 000000000..b03d30f02
--- /dev/null
+++ b/docs/guides/onap-user/configure/change_config/index.rst
@@ -0,0 +1,11 @@
+.. 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.
+
+
+Change Configure
+================
+The following guides are provided to describe tasks that a user of
+ONAP may need to perform to change a VNF configuration.
+
+TO BE COMPLETED
\ No newline at end of file
diff --git a/docs/guides/onap-user/configure/index.rst b/docs/guides/onap-user/configure/index.rst
new file mode 100644
index 000000000..d44da30f8
--- /dev/null
+++ b/docs/guides/onap-user/configure/index.rst
@@ -0,0 +1,18 @@
+.. 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.
+
+
+Configure Service, VNF, PNF
+===========================
+The following guides are provided to describe tasks that a user of
+ONAP may need to perform to configure a PNF or a VNF.
+
+Configuration includes the following topics:
+
+.. toctree::
+   :maxdepth: 1
+
+   Connect PNF to ONAP <./pnf_connect/index.rst>
+   Connect VNF to ONAP <./vnf_connect/index.rst>
+   Change PNF/VNF configuration <./change_config/index.rst>
diff --git a/docs/guides/onap-user/configure/pnf_connect/index.rst b/docs/guides/onap-user/configure/pnf_connect/index.rst
new file mode 100644
index 000000000..311bf911e
--- /dev/null
+++ b/docs/guides/onap-user/configure/pnf_connect/index.rst
@@ -0,0 +1,18 @@
+.. 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.
+
+
+ONAP and PNF connection configuration
+=====================================
+
+The following guides are provided to describe tasks that a user of
+ONAP may need to perform to allow a PNF to communicate with ONAP.
+
+Pre-requisites
+--------------
+- PNF provides the appropriate API to perform the espected operations
+- ONAP and PNF are interconnected via a network
+- any firewall between ONAP and PNF is correctly configured
+
+TO BE COMPLETED
diff --git a/docs/guides/onap-user/configure/vnf_connect/index.rst b/docs/guides/onap-user/configure/vnf_connect/index.rst
new file mode 100644
index 000000000..2e09b2aeb
--- /dev/null
+++ b/docs/guides/onap-user/configure/vnf_connect/index.rst
@@ -0,0 +1,17 @@
+.. 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.
+
+
+ONAP and VNF connection configuration
+=====================================
+The following guides are provided to describe tasks that a user of
+ONAP may need to perform to allow a VNF to communicate with ONAP
+
+Pre-requisites
+--------------
+- VNF provides the appropriate API to perform the espected operations
+- ONAP and VNF are interconnected via a network
+- any firewall between ONAP and VNF is correctly configured
+
+TO BE COMPLETED
diff --git a/docs/guides/onap-user/design/index.rst b/docs/guides/onap-user/design/index.rst
index 615535850..a77984456 100644
--- a/docs/guides/onap-user/design/index.rst
+++ b/docs/guides/onap-user/design/index.rst
@@ -4,8 +4,8 @@
 
 .. _doc_guide_user_des:
 
-Design
-======
+Design Service
+==============
 
 The goal of the design process is to create all artifacts (models)
 that are required to instantiate and manage resources, services,
diff --git a/docs/guides/onap-user/index.rst b/docs/guides/onap-user/index.rst
index 79a3faadc..e1d235fae 100644
--- a/docs/guides/onap-user/index.rst
+++ b/docs/guides/onap-user/index.rst
@@ -18,5 +18,6 @@ an instance of ONAP.
    cloud_site/index.rst
    design/index.rst
    instantiate/index.rst
+   configure/index.rst
    onapcli.rst
    Verified Use Cases <../../submodules/integration.git/docs/docs_usecases.rst>
diff --git a/docs/guides/onap-user/instantiate/index.rst b/docs/guides/onap-user/instantiate/index.rst
index 21177b59a..fb14e698e 100644
--- a/docs/guides/onap-user/instantiate/index.rst
+++ b/docs/guides/onap-user/instantiate/index.rst
@@ -3,29 +3,16 @@
 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
 
 
-Instantiate
-===========
+Instantiate Service, PNF, VNF, Network
+======================================
 The following guides are provided to describe tasks that a user of
 ONAP may need to perform when instantiating a service.
 
 Instantiation includes the following topics:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    Pre-instantiation operations <./pre_instantiation/index.rst>
 
    Instantiation operation(s) <./instantiation/index.rst>
-
-
-**e2eServiceInstance** method is a hard-coded approach with dedicated/specific
-service BPMN workflow. That means it is linked to ONAP source code
-and lifecycle.
-
-**A La Carte** method requires the Operations actor to build and send
-a lot of operations. To build those requests, Operator actor needs to
-define/collect by himself all VNF parameters/values.
-
-**Macro** method required the Operations actor to build and send only one
-request and, thanks to CDS Blueprint templates, ONAP will collect and assign
-all required parameters/values by itself.
diff --git a/docs/guides/onap-user/instantiate/instantiation/index.rst b/docs/guides/onap-user/instantiate/instantiation/index.rst
index 455bdf070..0d2981b4d 100644
--- a/docs/guides/onap-user/instantiate/instantiation/index.rst
+++ b/docs/guides/onap-user/instantiate/instantiation/index.rst
@@ -2,27 +2,40 @@
 .. International License. http://creativecommons.org/licenses/by/4.0
 .. Copyright 2019 ONAP Contributors.  All rights reserved.
 
-.. _doc_guide_user_ser_inst:
 
+Declare PNF instances:
 
-Service Instantiation methods
-=============================
+.. toctree::
+   :maxdepth: 1
 
+   Declare PNF instances <./pnf_instance/index.rst>
 
-Declare PNF instances:
+Instantiate a Service
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   Instantiate a Service <./service_instance/index.rst>
+
+
+Instantiate a VNF:
+
+.. toctree::
+   :maxdepth: 1
+
+    Instantiate a VNF <./vnf_instance/index.rst>
+
+Configure a VNF:
+
+.. toctree::
+   :maxdepth: 1
+
+    Configure a VNF <./vnf_configure/index.rst>
 
-   Declare PNF instances <./pnf_instance/index.rst>
 
-Instantiate a Service:
+Instantiate a Virtual Link:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   using ONAP VID Portal with "A La Carte" method <./vid/index.rst>
-   using ONAP UUI Portal with "e2eServiceInstance" method <./uui/index.rst>
-   using ONAP NBI REST API (TM Forum) <./nbi/index.rst>
-   using ONAP SO REST API with "A La Carte" method <./so1/index.rst>
-   using ONAP SO REST API with "Macro" mode method <./so2/index.rst>
+    Instantiate a Virtual Link <./virtual_link_instance/index.rst>
diff --git a/docs/guides/onap-user/instantiate/instantiation/pnf_instance/index.rst b/docs/guides/onap-user/instantiate/instantiation/pnf_instance/index.rst
index 7fbfdbe79..765dd1f79 100644
--- a/docs/guides/onap-user/instantiate/instantiation/pnf_instance/index.rst
+++ b/docs/guides/onap-user/instantiate/instantiation/pnf_instance/index.rst
@@ -4,8 +4,8 @@
 
 
 
-Declare PNF instances in ONAP
-=============================
+Declare PNF instances
+=====================
 
 PNF instances can be declared in ONAP inventory (AAI) using REST API
 
diff --git a/docs/guides/onap-user/instantiate/instantiation/service_instance/index.rst b/docs/guides/onap-user/instantiate/instantiation/service_instance/index.rst
new file mode 100644
index 000000000..b23a90f33
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/service_instance/index.rst
@@ -0,0 +1,63 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+
+Service Instantiation
+=====================
+
+**Pre-requisites**
+
+- the Service has been designed and distributed (see: Service Design)
+- pre-instantiation operations have been performed
+  (see: pre instantiation section)
+
+**Possible Tools to perform Service Instantiation**
+
+- **via a Graphical User Interface tool**
+  using ONAP applications such as **ONAP VID** and **ONAP UUI** tools
+
+- **via any tool able to perform REST API requests**
+  (for example : Robot Framework, Postman, Curl...) connected
+  to **ONAP SO** legacy API or **ONAP extAPI/NBI** standard TMF641 API
+  to add/delete Service.
+
+**Possible methods with ONAP to instantiate a Service**
+
+- **A La Carte**
+  method requires the user to build and send
+  operations **for each object** to instantiate : Service, VNFs,
+  VFModules and Networks (in other words : once you have instantiated
+  the Service object, you still have to instantiate the various VNFs
+  or Networks that compose your Service).
+  To build those requests, the user needs to define/collect by himself
+  all necessary parameters/values.
+
+- **Macro**
+  method allows the user to build and send
+  **only one request to instantiate all objects** : Service, VNFs,
+  VFModules and Networks. Thanks to templates (see CDS Blueprint in
+  Design section),
+  ONAP will collect and assign all required parameters/values by itself.
+
+
+   Note: **Macro** method is not (yet) available via ONAP VID
+   nor via extAPI/NBI
+
+With "A La Carte" method
+------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+      using ONAP VID Portal  <../vid/index.rst>
+      using ONAP NBI REST API (TM Forum) <../nbi/index.rst>
+      using ONAP SO REST API <../so1/index.rst>
+
+With "Macro" method
+-------------------
+
+.. toctree::
+   :maxdepth: 1
+
+      using ONAP SO REST API <../so2/index.rst>
diff --git a/docs/guides/onap-user/instantiate/instantiation/so1/index.rst b/docs/guides/onap-user/instantiate/instantiation/so1/index.rst
index 86f03bdd3..c7bd27880 100644
--- a/docs/guides/onap-user/instantiate/instantiation/so1/index.rst
+++ b/docs/guides/onap-user/instantiate/instantiation/so1/index.rst
@@ -8,29 +8,82 @@
 A La Carte mode Service Instantiation via ONAP SO API
 =====================================================
 
-Using ONAP SO API in "A La Carte" mode, you need to send several requests,
-depending on the service model composition.
+Using ONAP SO API in "A La Carte" mode, the user needs to send
+a request to instantiate the service object but also for each VNF/VF-module
+and network that compose the Service.
 
-For example, if your service model is composed of 2 VNF and a Network,
-you will have to build and send :
+ONAP will instantiate resources on Cloud platforms only when user is requesting
+to instantiate VF-module or Network (openstack neutron or contrail).
 
-* a request to SO to create the "service instance" object
-* a request to SO to create the VNF 1 instance object
-* a request to SDNC to declare VNF 1 instance parameters and values
-  (SDNC preload)
-* a request to SO to create the Vf-module 1 instance object
-* a request to SO to create the VNF 2 instance object
-* a request to SDNC to declare VNF 2 instance parameters and values
-  (SDNC preload)
-* a request to SO to create the Vf-module 2 instance object
-* a request to SO to create the Network instance object
+To instantiate a VF-module, it is required to have instantiated a VNF object.
 
+To instantiate a VNF object, it is required to have instantiated
+a Service object.
 
+To instantiate a Network object, it is required to have instantiated
+a Service object.
+
+**Requests**
+    * `Request to instantiate Service object`_
+    * `Request to instantiate VNF object`_
+    * `Requests to instantiate VF-module object`_
+    * `Requests to instantiate Neutron Network object`_
+    * `Requests to instantiate a Contrail Network object`_
+
+
+Request to instantiate Service object
+-------------------------------------
 
 Example to request a service instance directly to ONAP SO
 
+::
 
-TO BE COMPLETED
+  curl -X POST \
+    http://so.api.simpledemo.onap.org:30277/onap/so/infra/serviceInstances/v7/serviceInstances \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
+    -H 'Content-Type: application/json' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: get_aai_subscr' \
+    -H 'cache-control: no-cache' \
+    -d '{
+    "requestDetails": {
+      "requestInfo": {
+        "instanceName": "integration_test_service_instance_001",
+        "source": "VID",
+        "suppressRollback": false,
+        "requestorId": "demo"
+      },
+      "modelInfo": {
+        "modelType": "service",
+        "modelInvariantId": "b0631a6c-ec7a-4f0c-a9ac-4423d9d67a7f",
+        "modelVersionId": "aafd5523-2cc5-4c86-957e-18bc37355f7a",
+        "modelName": "integration_test_ubuntu16",
+        "modelVersion": "1.0"
+      },
+          "cloudConfiguration": {
+              "tenantId": "3e3b55ca4c9948d1a9fa68715831c6bd",
+              "cloudOwner": "OPNFV",
+              "lcpCloudRegionId": "RegionOne"
+          },
+      "requestParameters": {
+        "userParams": [],
+        "testApi": "VNF_API",
+        "subscriptionServiceType": "integration_test_ubuntu16",
+        "aLaCarte": true
+      },
+      "subscriberInfo": {
+        "globalSubscriberId": "integration_test_customer"
+      },
+      "project": {
+        "projectName": "integration_test_project"
+      },
+      "owningEntity": {
+        "owningEntityId": "6b5b6b70-4e9a-4f6f-8b7b-cbd7cf990c6e",
+        "owningEntityName": "integration_test_OE"
+      }
+    }
+  }'
 
 
 
@@ -53,7 +106,10 @@ This will allow you to get the serviceOrder Status (completed, failed...)
     -H 'cache-control: no-cache'
 
 
-To instantiate a VNF, you need to build a complex request.
+Request to instantiate VNF object
+---------------------------------
+
+To instantiate a VNF, you need to build an other request.
 All necessary parameters are available in the Tosca service template
 generated by SDC when you defined your service model.
 
@@ -115,6 +171,10 @@ generated by SDC when you defined your service model.
   }
   }'
 
+
+Requests to instantiate VF-module object
+----------------------------------------
+
 To instantiate a VF module, you need to build two complex requests
 All necessary parameters are available in the Tosca service template
 generated by SDC when you defined your service model.
@@ -235,12 +295,15 @@ The 2nd request is to instantiate the VF module via ONAP SO
 
 
 
+Requests to instantiate Neutron Network object
+----------------------------------------------
+
 To instantiate a Neutron Network, you need to build two complex request.
 All necessary parameters are available in the Tosca service template
 generated by SDC when you defined your service model.
 
 
-1st request is the "SDNC-preload" for a network object:
+1st request is the "SDNC-preload" for a neutron network object:
 
 ::
 
@@ -303,7 +366,7 @@ generated by SDC when you defined your service model.
   }'
 
 
-2nd request is to instantiate the network via ONAP SO
+2nd request is to instantiate the neutron network via ONAP SO
 (instance name must be identical in both requests)
 
 
@@ -364,3 +427,9 @@ generated by SDC when you defined your service model.
       }]
     }
   }'
+
+
+Requests to instantiate a Contrail Network object
+-------------------------------------------------
+
+TO BE COMPLETED
diff --git a/docs/guides/onap-user/instantiate/instantiation/so2/index.rst b/docs/guides/onap-user/instantiate/instantiation/so2/index.rst
index 02a5f70d3..9e2f9f98f 100644
--- a/docs/guides/onap-user/instantiate/instantiation/so2/index.rst
+++ b/docs/guides/onap-user/instantiate/instantiation/so2/index.rst
@@ -8,7 +8,8 @@
 Macro mode Service Instantiation via ONAP SO API
 ================================================
 
-Using Macro mode, you have to build and send only one request to ONAP SO
+Using Macro mode, you have to build and send one and only one
+request to ONAP SO.
 
 In that request you need to indicate all object instances
 that you want to be instantiated.
@@ -16,9 +17,9 @@ that you want to be instantiated.
 Reminder : ONAP SO in Macro mode will perform the VNF parameters/values
 assignment based on CDS Blueprint templates
 that are supposed to be defined during Design and Onboard steps.
-That means ONAP has all information
+That means ONAP should have all information
 to be able to get all necessary values by itself (there is no longer need
-for an Operator to provide "SDNC preload").
+for a user to provide those values via the "SDNC preload" operation).
 
 Additional info in:
 
diff --git a/docs/guides/onap-user/instantiate/instantiation/virtual_link_instance/index.rst b/docs/guides/onap-user/instantiate/instantiation/virtual_link_instance/index.rst
new file mode 100644
index 000000000..0fb9f1147
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/virtual_link_instance/index.rst
@@ -0,0 +1,54 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+
+Network Instantiation
+=====================
+
+Note: in ONAP SDC, network object is called "virtual link"
+
+**Various possible methods are available with ONAP to instantiate a network**
+
+- With **A La Carte**
+  method, the user needs to build and send a Network instantiation
+  request.
+
+    Note 1: prior to be able to send a request to instantiate
+    a Network, the user needs to instantiate a Service Object and then will
+    need to refer to that Service instance in the Network instantiate request.
+
+    Note 2: the request to instantiate the Network object will update
+    ONAP AAI (inventory) and will send a request to the selected Cloud Platform
+    (Openstack, Azure, K8S...).
+
+- With **Macro**
+  method, the user do not need to send any
+  Network instantiation request. Network instantiation is being automatically
+  performed by ONAP when sending the request to instantiate the Service
+  (see: Instantiate Service).
+
+**Possible Tools to perform Network Instantiation**
+
+the user needs such a tool only if using the "A La Carte" method.
+
+- **via ONAP VID Graphical User Interface tool**
+
+- **via any tool able to perform REST API requests**
+  (for example : Robot Framework, Postman, Curl...) connected
+  to **ONAP SO** legacy API.
+
+With "A La Carte" method
+------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   using ONAP VID Portal <../vid/index.rst>
+   using ONAP SO REST API <../so1/index.rst>
+
+With "Macro" method
+------------------------
+
+Network instantiation is performed automatically when performing
+Service Instantiation.
diff --git a/docs/guides/onap-user/instantiate/instantiation/vnf_instance/index.rst b/docs/guides/onap-user/instantiate/instantiation/vnf_instance/index.rst
new file mode 100644
index 000000000..822118f00
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/vnf_instance/index.rst
@@ -0,0 +1,63 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+
+VNF Instantiation
+=================
+
+**Pre-requisites**
+
+- the VNF is part of a Service Model (see: Service Design)
+
+   Note: in ONAP SDC tool, VNF is named "VF"
+
+
+**Possible methods with ONAP to instantiate a VNF**
+
+- With **A La Carte**
+  method, the user needs to build and send a VNF instantiation
+  request.
+
+    Note 1: prior to be able to send a request to instantiate
+    a VNF, the user needs to instantiate a Service Object and then will
+    need to refer to that Service instance in the VNF instantiate request.
+
+    Note 2: after having instantiated the VNF object, the user needs to
+    instantiate a VF-module object, refering to the previously instantiated
+    VNF object.
+
+    Note 3: the request to instantiate the VF-module object will, at last, send
+    a request to the selected Cloud Platform (Openstack, Azure, K8S...).
+
+- With **Macro**
+  method, the user do not need to send any
+  VNF instantiation request. VNF instantiation is being automatically
+  performed by ONAP when sending the request to instantiate the Service
+  (see: Instantiate Service).
+
+
+**Possible Tools to perform VNF Instantiation**
+
+the user needs such a tool only if using the "A La Carte" method.
+
+- **via ONAP VID Graphical User Interface tool**
+
+- **via any tool able to perform REST API requests**
+  (for example : Robot Framework, Postman, Curl...) connected
+  to **ONAP SO** legacy API.
+
+With "A La Carte" method
+------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   using ONAP VID Portal <../vid/index.rst>
+   using ONAP SO REST API <../so1/index.rst>
+
+With "Macro" method
+------------------------
+
+VNF and VF-Module instantiation are performed automatically when performing
+Service Instantiation.