Review K8S based Cloud Region Support - EdgeXFoundry Use case doc

Issue-ID: INT-1287

Change-Id: I9f1797f23c3d386b953af548bfe6640149cfe917
Signed-off-by: mrichomme <morgan.richomme@orange.com>

1 files changed, 143 insertions, 134 deletions

diff --git a/docs/docs_vfw_edgex_k8s.rst b/docs/docs_vfw_edgex_k8s.rst
index a9bad2d9b..a25b349a2 100644
--- a/docs/docs_vfw_edgex_k8s.rst
+++ b/docs/docs_vfw_edgex_k8s.rst
@@ -8,33 +8,44 @@ vFW/Edgex with Multicloud Kubernetes Plugin: Setting Up and Configuration
 -------------------------------------------------------------------------
 
 Description
-~~~~~~~~~~~
-This use case covers the deployment of vFW and Edgex HELM Charts in a Kubernetes based cloud region via the multicloud-k8s plugin.
-The multicloud-k8s plugin provides APIs to upload self-contained HELM Charts that can be customized via the profile API and later installed in a particular cloud region.
+-----------
 
-When the installation is complete (all the pods are either in running or completed state)
+This use case covers the deployment of vFW and Edgex HELM Charts in a Kubernetes
+based cloud region via the multicloud-k8s plugin.
+The multicloud-k8s plugin provides APIs to upload self-contained HELM Charts
+that can be customized via the profile API and later installed in a particular
+cloud region.
+
+When the installation is complete (all the pods are either in running or
+completed state)
 
 vFW Helm Chart link:
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 https://github.com/onap/multicloud-k8s/tree/master/kud/demo/firewall
 
 EdgeXFoundry Helm Chart link:
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 https://github.com/onap/multicloud-k8s/tree/master/kud/tests/vnfs/edgex/helm/edgex
 
 
-**Create CSAR with Helm chart as an artifact**
-----------------------------------------------
+Create CSAR with Helm chart as an artifact
+------------------------------------------
 
 The CSAR is a heat template package with Helm chart in it. The basic package
-consists of an **environment file**, **base_dummy.yaml file** (example),
-**MANIFEST.json** and the **tar.gz** file (of Helm chart).
-We need to zip all of these files before onboarding.
-One thing to pay much attention to is the naming convention which must
+consists of:
+
+* an **environment file**
+* a **base_dummy.yaml file** (example)
+* a **MANIFEST.json**
+* a **tar.gz** file (of Helm chart)
+
+These files must be zipped before onboarding.
+One thing to pay much attention to is the naming convention which MUST
 be followed while making the tgz.
-**NOTE: The Naming convention is for the helm chart tgz file.**
+
+**NOTE**: The Naming convention is for the helm chart tgz file.
 
 **Naming convention follows the format:**
 
@@ -46,9 +57,10 @@ be followed while making the tgz.
 3. *Subtype*: charts, day0, config template
 4. *Extension*: zip, tgz, csar
 
-NOTE: The .tgz file must be a tgz created from the top level helm chart
+**NOTE**: The .tgz file must be a tgz created from the top level helm chart
 folder. I.e. a folder that contains a Chart.yaml file in it.
-For vFW use case the content of tgz file must be following
+For vFW use case the content of tgz file must look as follows:
+
 ::
 
     $ helm package firewall
@@ -77,9 +89,8 @@ For vFW use case the content of tgz file must be following
     firewall/charts/packetgen/values.yaml
 
 
+An example of the contents inside a heat template package can be found hereafter.
 
-Listed below is an example of the contents inside a heat template
-package
 ::
 
      $ vfw-k8s/package$ ls
@@ -87,12 +98,11 @@ package
       vfw_cloudtech_k8s_charts.tgz vfw_k8s_demo.zip
 
 
-
-
-**MANIFEST.json**
-~~~~~~~~~~~~~~~~~
+MANIFEST.json
+~~~~~~~~~~~~~
 
 Key thing is note the addition of cloud artifact
+
 ::
 
   type: "CLOUD_TECHNOLOGY_SPECIFIC_ARTIFACTS"
@@ -119,9 +129,10 @@ Key thing is note the addition of cloud artifact
 	]
   }
 
-**base\_dummy.yaml**
-~~~~~~~~~~~~~~~~~~~~~
-Designed to be minimal HEAT template
+base\_dummy.yaml
+~~~~~~~~~~~~~~~~
+
+It is an example of the minimal HEAT template.
 
 ::
 
@@ -175,10 +186,6 @@ Designed to be minimal HEAT template
         flavor: { get_param: dummy_flavor_name } metadata: { vnf_name: { get_param: vnf_name }, vnf_id: { get_param: vnf_id }, vf_module_id: { get_param: vf_module_id }}
 
 
-
-
-
-
 **base\_dummy.env**
 
 ::
@@ -191,94 +198,96 @@ Designed to be minimal HEAT template
     dummy_image_name: dummy
     dummy_flavor_name: dummy.default
 
-**Onboard the CSAR**
---------------------
+Onboard the CSAR
+----------------
 
 For onboarding instructions please refer to steps 4-9 from the document
 `here <https://wiki.onap.org/display/DW/vFWCL+instantiation%2C+testing%2C+and+debuging>`__.
 
-**Steps for installing KUD Cloud**
-----------------------------------
+Steps for installing KUD Cloud
+------------------------------
 
-Follow the link to install KUD Kubernetes Deployment. KUD contains all
-the packages required for running vfw use case.
+Follow the link to install KUD Kubernetes Deployment. KUD contains all the
+packages required for running vfw use case.
 
-Kubernetes Baremetal deployment instructions here_
+Kubernetes Baremetal deployment instructions can be found here_
 
 .. _here: https://wiki.onap.org/display/DW/Kubernetes+Baremetal+deployment+setup+instructions/
 
-**REGISTER KUD CLOUD REGION with K8s-Plugin**
----------------------------------------------
+REGISTER KUD CLOUD REGION with K8s-Plugin
+-----------------------------------------
+
+You must declare the KUD as a new cloud region in ONAP thanks to ONAP multicloud
+API.
+
+POST connectivity info
+~~~~~~~~~~~~~~~~~~~~~~
 
-API to support Reachability for Kubernetes Cloud
+Create a the post.json file as follows:
 
-**The command to POST connectivity info**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ::
 
   {
-    "cloud-region" : "<name>",   // Must be unique across
+    "cloud-region" : "<name>",   // Must be unique
     "cloud-owner" :  "<owner>",
     "other-connectivity-list" : {
            }
 
-This is a multipart upload and here is how you do the POST for this.
+Then send the POST HTTP request as described below:
 
-#Using a json file (eg: post.json) containing content as above
 ::
 
  curl -i -F "metadata=<post.json;type=application/json" -F file=@
   /home/ad_kkkamine/.kube/config -X POST http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info
 
-**Command to GET Connectivity Info**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+GET Connectivity Info
+~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
   curl -i -X GET http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info/{name}
 
 
-**Command to DELETE Connectivity Info**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DELETE Connectivity Info
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
   curl -i -X GET http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info/{name}
 
 
-**Command to UPDATE/PUT Connectivity Info**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+UPDATE/PUT Connectivity Info
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
   curl -i -X GET http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info/{name}
 
-**Register KUD Cloud region with AAI**
---------------------------------------
+Register KUD Cloud region with AAI
+----------------------------------
 
-With k8s cloud region, we need to add a tenant to the k8s cloud region.
+A tenant must be added to the k8s cloud region.
 The 'easy' way is to have the ESR information (in step 1 of cloud
-registration) point to a real OpenStack tenant (e.g. the OOF tenant in
+registration) pointing to a real OpenStack tenant (e.g. the OOF tenant in
 the lab where we tested).
 
 This will cause multicloud to add the tenant to the k8s cloud region and
-then, similar to #10 in the documentation
+then, similarly to #10 in the documentation
 `here <https://onap.readthedocs.io/en/casablanca/submodules/integration.git/docs/docs_vfwHPA.html#docs-vfw-hpa>`__,
 the service-subscription can be added to that object.
 
-NOTE: use same name cloud-region and cloud-owner name
+**NOTE:** use same name cloud-region and cloud-owner name
 
 An example is shown below for K8s cloud but following the steps 1,2,3
 from
 `here <https://onap.readthedocs.io/en/latest/submodules/multicloud/framework.git/docs/multicloud-plugin-windriver/UserGuide-MultiCloud-WindRiver-TitaniumCloud.html#tutorial-onboard-instance-of-wind-river-titanium-cloud>`__.
 The sample input below is for k8s cloud type.
 
-**Step 1 - Cloud Registration/ Create a cloud region to represent the instance.**
-
+**Step 1**: Cloud Registration/ Create a cloud region to represent the instance
 
-Note: highlighted part of the body refers to an existing OpenStack
-tenant (OOF in this case). Has nothing to do with the K8s cloud region
-we are adding.
+Note: the highlighted part of the body refers to an existing OpenStack
+tenant (OOF in this case). It is provided as an illustration and must be adapted
+according to your configuration.
 
 ::
 
@@ -311,9 +320,9 @@ we are adding.
 	}
   }
 
-**Step 2  add a complex to the cloud**
+**Step 2:**  Add a complex to the cloud
 
-Note: just adding one that exists already
+Adding an already existing complex is enough. You do not need to create new ones.
 
 ::
 
@@ -329,27 +338,24 @@ Note: just adding one that exists already
   ]
   }
 
-**Step 3 - Trigger the Multicloud plugin registration process**
-
+**Step 3:** Trigger the Multicloud plugin registration process
 
 ::
 
   POST http://{{MSB_IP}}:{{MSB_PORT}}/api/multicloud-titaniumcloud/v1/k8scloudowner4/k8sregionfour/registry
 
 
-This registers the K8S cloud with Multicloud  it also reaches out and
-adds tenant information to the cloud (see example below  you'll see all
-kinds of flavor, image information that is associated with the OOF
+This step allws the registration of the K8S cloud with Multicloud. It also
+reaches out and adds tenant information to the cloud (see example below, you
+will see all kinds of flavor, image information that are associated with the OOF
 tenant).
 
-If we had not done it this way, then wed have to go in to AAI at this
-point and manually add a tenant to the cloud region. The first time I
-tried this (k8s region one), I just made up some random tenant id and
-put it in.)
+If you did not follow the procedure described above then you will have to connect
+on AAI point and manually add a tenant to the cloud region.
 
-The tenant is there so you can add the service-subscription to it:
+Once the tenant declared, you can add the service-subscription to it:
 
-**Making a Service Type:**
+**Step 4:** Create a Service Type
 
 ::
 
@@ -359,8 +365,7 @@ The tenant is there so you can add the service-subscription to it:
               "service-id": "vfw-k8s"
   }
 
-Add subscription to service type to the customer (Demonstration in this
-case  which was already created by running the robot demo scripts)
+Add subscription service info to the service type of the customer.
 
 ::
 
@@ -369,8 +374,8 @@ case  which was already created by running the robot demo scripts)
            "service-type": "vfw-k8s"
   }
 
-Add Service-Subscription to the tenant (resource-version changes based
-on actual value at the time):
+Add Service-Subscription to the tenant. The parameter resource-version is a
+timestamp.
 
 ::
 
@@ -400,42 +405,38 @@ on actual value at the time):
   }
   }
 
-**Distribute the CSAR**
------------------------
-Onboard a service it gets stored in SDC final action is distributed. SO
-and other services are notified sdc listener in the multicloud sidecar.
-When distribution happens it takes tar.gz file and uploads to k8s
-plugin.
+Distribute the CSAR
+-------------------
 
-**Create Profile Manually**
----------------------------
+Once the cloud region is properly declared, it is possible to onboard the service
+in the SDC and triggers a distribution from the SDC to the main ONAP components.
+SO and other services are notified. A sdc listener is also getting the
+distribution information in the multicloud sidecar.
+When distribution happens it takes tar.gz file and uploads it to k8s plugin.
+
+Create Profile Manually
+-----------------------
 
 K8s-plugin artifacts start in the form of Definitions. These are nothing
 but Helm Charts wrapped with some metadata about the chart itself. Once
-the Definitions are created, we are ready to create some profiles so
-that we can customize that definition and instantiate it in Kubernetes.
+the Definitions are created, some profiles can be created. Finally it is
+possible to customize the definition and instantiate it in the targeted
+Kubernetes.
 
-NOTE: Refer this link_ for complete API lists and
-documentation:
+**NOTE:** Refer this link_ for complete API lists and documentation:
 
 .. _link : https://wiki.onap.org/display/DW/MultiCloud+K8s-Plugin-service+API
 
-A profile consists of the following:
-
-**manifest.yaml**
-
-- Contains the details for the profile and everything contained within
+The profile consists in:
 
-A **HELM** values override yaml file.
+* the **manifest.yaml**. It contains the details for the profile
+* a **HELM** values override yaml file: It can have any name as long as it matches
+  the corresponding entry in the **manifest.yaml**
+* Additional files organized in a folder structure: all these files should have
+  a corresponding entry in **manifest.yaml** file
 
-- It can have any name as long as it matches the corresponding entry in the **manifest.yaml**
-
-Any number of files organized in a folder structure
-
-- All these files should have a corresponding entry in **manifest.yaml** file
-
-**Creating a Profile Artifact**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Create a Profile Artifact
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
@@ -447,13 +448,13 @@ Any number of files organized in a folder structure
   testfol/subdir
   testfol/subdir/deployment.yaml
 
-  #Create profile tar.gz
+  # Create profile tar.gz
   > cd profile
   > tar -cf profile.tar *
   > gzip profile.tar
   > mv profile.tar.gz ../
 
-The manifest file contains the following
+The manifest file contains the following parameters:
 
 ::
 
@@ -465,10 +466,10 @@ The manifest file contains the following
    - filepath: testfol/subdir/deployment.yaml
      chartpath: vault-consul-dev/templates/deployment.yaml
 
-Note: values: "values\_override.yaml" can **be** empty **file** **if**
+**Note:** values: "values\_override.yaml" can **be** empty **file** **if**
 you are creating **a** dummy **profile**
 
-Note: A dummy profile does not need any customization. The following is
+**Note:** A dummy profile does not need any customization. The following is
 optional in the manifest file.
 
 ::
@@ -477,25 +478,29 @@ optional in the manifest file.
    - filepath: testfol/subdir/deployment.yaml
      chartpath: vault-consul-dev/templates/deployment.yaml
 
-We need to read the name of the Definition which was created while distribution of the service from SDC.
+The name of the Definition is retrived from SDC service distribution stage.
+
+Retrieve the definition name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**Command to read the Definition name and its version**
-On the ONAP K8s Rancher host execute following statement
+Execute the following command on the ONAP K8s Rancher host to read the definition
+name and its version:
 
 ::
 
  kubectl logs -n onap `kubectl get pods -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}' | grep multicloud-k8s | head -1` -c multicloud-k8s
 
-From the output read the name of the definition which is "rb-name" and "rb-version" respectively
+From the output read the name of the definition which is "rb-name" and
+"rb-version" respectively
 
 ::
 
  127.0.0.1 - - [15/Jul/2019:07:56:21 +0000] "POST /v1/rb/definition/test-rbdef/1/content HTTP/1.1"
 
-**Command to read (GET) Definition**
+Get definition
+^^^^^^^^^^^^^^
 
-With this information, we are ready to upload the profile with the
-following JSON data
+With this information, it is possible to upload the profile with the following JSON data
 
 ::
 
@@ -509,24 +514,24 @@ following JSON data
  }
 
 
-**Command to create (POST) Profile**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
+Create Profile
+^^^^^^^^^^^^^^
 ::
 
  curl -i -d @create_rbprofile.json -X POST http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile
 
 
 
-**Command to UPLOAD artifact for Profile**
+UPLOAD artifact for Profile
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
  curl -i --data-binary @profile.tar.gz -X POST http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile/p1/content
 
 
-
-**Command to GET Profiles**
+GET Profiles
+^^^^^^^^^^^^
 
 ::
 
@@ -535,23 +540,25 @@ following JSON data
   curl -i http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile/p1
 
 
+DELETE Profile
+^^^^^^^^^^^^^^
 
-**Command to DELETE Profile**
 ::
 
  curl -i -X DELETE http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile/p1
 
 
-**Instantiation**
------------------
+Instantiation
+-------------
 
 Instantiation is done by SO. SO then talks to Multi Cloud-broker via MSB
 and that in turn looks up the cloud region in AAI to find the endpoint.
-If k8sregion one is registered with AAI and SO makes a call with that,
+If k8sregion one is properly registered in AAI (SO check),
 then the broker will know that it needs to talk to k8s-plugin based on
 the type of the registration.
 
-**Instantiate the created Profile via the following REST API**
+Instantiate the created Profile via the following REST API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
@@ -565,19 +572,19 @@ the type of the registration.
    }
   }
 
-**NOTE**: Make sure that the namespace is already created before
-instantiation.
+**NOTE**: Make sure that the namespace is already created before instantiation.
 
 Instantiate the profile with the ID provided above
 
-**Command to Instantiate a Profile**
+Instantiate a Profile
+~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
  curl -d @create_rbinstance.json http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/instance
 
 
-The command returns the following JSON
+The command shall return the following JSON
 
 ::
 
@@ -616,7 +623,8 @@ The command returns the following JSON
  ]
  }
 
-**Delete Instantiated Kubernetes resources**
+Delete Instantiated Kubernetes resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The **id** field from the returned JSON can be used to **DELETE** the
 resources created in the previous step. This executes a Delete operation
@@ -627,10 +635,10 @@ using the Kubernetes API.
  curl -X DELETE http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/instance/ZKMTSaxv
 
 
-**GET Instantiated Kubernetes resources**
-
+GET Instantiated Kubernetes resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The **id field** from the returned JSON can be used to **GET** the
+The **id** field from the returned JSON can be used to **GET** the
 resources created in the previous step. This executes a get operation
 using the Kubernetes API.
 
@@ -641,7 +649,8 @@ using the Kubernetes API.
 
 `*\ https://github.com/onap/oom/blob/master/kubernetes/multicloud/resources/config/provider-plugin.json <https://github.com/onap/oom/blob/master/kubernetes/multicloud/resources/config/provider-plugin.json>`__
 
-**Create User parameters**
+Create User parameters
+~~~~~~~~~~~~~~~~~~~~~~
 
 We need to create parameters that ultimately get translated as: