aboutsummaryrefslogtreecommitdiffstats
path: root/docs/docs_vfw_edgex_k8s.rst
diff options
context:
space:
mode:
authormrichomme <morgan.richomme@orange.com>2019-10-15 18:21:58 +0200
committerDaniel Rose <dr695h@att.com>2019-10-15 16:32:47 +0000
commit7eb45c5f649114027ea3b67bab5cc5d032feb035 (patch)
tree4fc66eb83ba669a4c099852444fa82fadd635aa3 /docs/docs_vfw_edgex_k8s.rst
parentaa96184d7975b08ff2ea4df815857eb2ad9ffd3a (diff)
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>
Diffstat (limited to 'docs/docs_vfw_edgex_k8s.rst')
-rw-r--r--docs/docs_vfw_edgex_k8s.rst277
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: