docs/docs_vfw_edgex_k8s.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2018 ONAP
   4
   5 .. _docs_vfw_edgex_multicloud_k8s:
   6
   7 vFW/Edgex with Multicloud Kubernetes Plugin: Setting Up and Configuration
   8 -------------------------------------------------------------------------
   9
  10 Description
  11 -----------
  12
  13 This use case covers the deployment of vFW and Edgex HELM Charts in a Kubernetes
  14 based cloud region via the multicloud-k8s plugin.
  15 The multicloud-k8s plugin provides APIs to upload self-contained HELM Charts
  16 that can be customized via the profile API and later installed in a particular
  17 cloud region.
  18
  19 When the installation is complete (all the pods are either in running or
  20 completed state)
  21
  22 vFW Helm Chart link:
  23 ~~~~~~~~~~~~~~~~~~~~
  24
  25 https://github.com/onap/multicloud-k8s/tree/master/kud/demo/firewall
  26
  27 EdgeXFoundry Helm Chart link:
  28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29
  30 https://github.com/onap/multicloud-k8s/tree/master/kud/tests/vnfs/edgex/helm/edgex
  31
  32
  33 Create CSAR with Helm chart as an artifact
  34 ------------------------------------------
  35
  36 The CSAR is a heat template package with Helm chart in it. The basic package
  37 consists of:
  38
  39 * an **environment file**
  40 * a **base_dummy.yaml file** (example)
  41 * a **MANIFEST.json**
  42 * a **tar.gz** file (of Helm chart)
  43
  44 These files must be zipped before onboarding.
  45 One thing to pay much attention to is the naming convention which MUST
  46 be followed while making the tgz.
  47
  48 **NOTE**: The Naming convention is for the helm chart tgz file.
  49
  50 **Naming convention follows the format:**
  51
  52 <free format string>\_\ ***cloudtech***\ \_<technology>\_<subtype>.extension
  53
  54 1. *Cloudtech:* is a fixed pattern and should not be changed if not
  55    necessary
  56 2. *Technology:* k8s, azure, aws
  57 3. *Subtype*: charts, day0, config template
  58 4. *Extension*: zip, tgz, csar
  59
  60 **NOTE**: The .tgz file must be a tgz created from the top level helm chart
  61 folder. I.e. a folder that contains a Chart.yaml file in it.
  62 For vFW use case the content of tgz file must look as follows:
  63
  64 ::
  65
  66     $ helm package firewall
  67
  68     $ tar -tf firewall-0.1.0.tgz
  69
  70     firewall/.helmignore
  71     firewall/Chart.yaml
  72     firewall/templates/onap-private-net.yaml
  73     firewall/templates/_helpers.tpl
  74     firewall/templates/protected-private-net.yaml
  75     firewall/templates/deployment.yaml
  76     firewall/templates/unprotected-private-net.yaml
  77     firewall/values.yaml
  78     firewall/charts/sink/.helmignore
  79     firewall/charts/sink/Chart.yaml
  80     firewall/charts/sink/templates/configmap.yaml
  81     firewall/charts/sink/templates/_helpers.tpl
  82     firewall/charts/sink/templates/service.yaml
  83     firewall/charts/sink/templates/deployment.yaml
  84     firewall/charts/sink/values.yaml
  85     firewall/charts/packetgen/.helmignore
  86     firewall/charts/packetgen/Chart.yaml
  87     firewall/charts/packetgen/templates/_helpers.tpl
  88     firewall/charts/packetgen/templates/deployment.yaml
  89     firewall/charts/packetgen/values.yaml
  90
  91
  92 An example of the contents inside a heat template package can be found hereafter.
  93
  94 ::
  95
  96      $ vfw-k8s/package$ ls
  97       MANIFEST.json base_dummy.env base_dummy.yaml
  98       vfw_cloudtech_k8s_charts.tgz vfw_k8s_demo.zip
  99
 100
 101 MANIFEST.json
 102 ~~~~~~~~~~~~~
 103
 104 Key thing is note the addition of cloud artifact
 105
 106 ::
 107
 108   type: "CLOUD_TECHNOLOGY_SPECIFIC_ARTIFACTS"
 109
 110   {
 111     "name": "",
 112     "description": "",
 113     "data": [
 114         {
 115             "file": "base_dummy.yaml",
 116             "type": "HEAT",
 117             "isBase": "true",
 118             "data": [
 119                 {
 120                     "file": "base_dummy.env",
 121                     "type": "HEAT_ENV"
 122                 }
 123             ]
 124         },
 125         {
 126             "file": "vfw_cloudtech_k8s_charts.tgz",
 127             "type": "CLOUD_TECHNOLOGY_SPECIFIC_ARTIFACTS"
 128         }
 129         ]
 130   }
 131
 132 base\_dummy.yaml
 133 ~~~~~~~~~~~~~~~~
 134
 135 It is an example of the minimal HEAT template.
 136
 137 ::
 138
 139  ##==================LICENSE_START========================================
 140   ##
 141   ## Copyright (C) 2019 Intel Corporation
 142   ## SPDX-License-Identifier: Apache-2.0
 143   ##
 144   ##==================LICENSE_END===========================================
 145
 146   heat_template_version: 2016-10-14
 147   description: Heat template to deploy dummy VNF
 148
 149   parameters:
 150     dummy_name_0:
 151       type: string
 152       label: name of vm
 153       description: Dummy name
 154
 155     vnf_id:
 156       type: string
 157             label: id of vnommand to read (GET) Definition
 158       description: Provided by ONAP
 159
 160     vnf_name:
 161       type: string
 162       label: name of vnf
 163       description: Provided by ONAP
 164
 165     vf_module_id:
 166       type: string
 167       label: vnf module id
 168       description: Provided by ONAP
 169
 170     dummy_image_name:
 171           type: string
 172       label: Image name or ID
 173       description: Dummy image name
 174
 175     dummy_flavor_name:
 176       type: string
 177       label: flavor
 178       description: Dummy flavor
 179
 180   resources:
 181     dummy_0:
 182       type: OS::Nova::Server
 183       properties:
 184         name: { get_param: dummy_name_0 }
 185         image: { get_param: dummy_image_name }
 186         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 }}
 187
 188
 189 **base\_dummy.env**
 190
 191 ::
 192
 193   parameters:
 194     vnf_id: PROVIDED_BY_ONAP
 195     vnf_name: PROVIDED_BY_ONAP
 196     vf_module_id: PROVIDED_BY_ONAP
 197     dummy_name_0: dummy_1_0
 198     dummy_image_name: dummy
 199     dummy_flavor_name: dummy.default
 200
 201 Onboard the CSAR
 202 ----------------
 203
 204 For onboarding instructions please refer to steps 4-9 from the document
 205 `here <https://wiki.onap.org/display/DW/vFWCL+instantiation%2C+testing%2C+and+debuging>`__.
 206
 207 Steps for installing KUD Cloud
 208 ------------------------------
 209
 210 Follow the link to install KUD Kubernetes Deployment. KUD contains all the
 211 packages required for running vfw use case.
 212
 213 Kubernetes Baremetal deployment instructions can be found here_
 214
 215 .. _here: https://wiki.onap.org/display/DW/Kubernetes+Baremetal+deployment+setup+instructions/
 216
 217 REGISTER KUD CLOUD REGION with K8s-Plugin
 218 -----------------------------------------
 219
 220 You must declare the KUD as a new cloud region in ONAP thanks to ONAP multicloud
 221 API.
 222
 223 POST connectivity info
 224 ~~~~~~~~~~~~~~~~~~~~~~
 225
 226 Create a the post.json file as follows:
 227
 228 ::
 229
 230   {
 231     "cloud-region" : "<name>",   // Must be unique
 232     "cloud-owner" :  "<owner>",
 233     "other-connectivity-list" : {
 234            }
 235
 236 Then send the POST HTTP request as described below:
 237
 238 ::
 239
 240  curl -i -F "metadata=<post.json;type=application/json" -F file=@
 241   /home/ad_kkkamine/.kube/config -X POST http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info
 242
 243 GET Connectivity Info
 244 ~~~~~~~~~~~~~~~~~~~~~~
 245
 246 ::
 247
 248   curl -i -X GET http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info/{name}
 249
 250
 251 DELETE Connectivity Info
 252 ~~~~~~~~~~~~~~~~~~~~~~~~
 253
 254 ::
 255
 256   curl -i -X GET http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info/{name}
 257
 258
 259 UPDATE/PUT Connectivity Info
 260 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 261
 262 ::
 263
 264   curl -i -X GET http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/connectivity-info/{name}
 265
 266 Register KUD Cloud region with AAI
 267 ----------------------------------
 268
 269 A tenant must be added to the k8s cloud region.
 270 The 'easy' way is to have the ESR information (in step 1 of cloud
 271 registration) pointing to a real OpenStack tenant (e.g. the OOF tenant in
 272 the lab where we tested).
 273
 274 This will cause multicloud to add the tenant to the k8s cloud region and
 275 then, similarly to #10 in the documentation
 276 `here <https://onap.readthedocs.io/en/casablanca/submodules/integration.git/docs/docs_vfwHPA.html#docs-vfw-hpa>`__,
 277 the service-subscription can be added to that object.
 278
 279 **NOTE:** use same name cloud-region and cloud-owner name
 280
 281 An example is shown below for K8s cloud but following the steps 1,2,3
 282 from
 283 `here <https://docs.onap.org/projects/onap-multicloud-framework/en/latest/multicloud-plugin-windriver/UserGuide-MultiCloud-WindRiver-TitaniumCloud.html?highlight=multicloud>`__.
 284 The sample input below is for k8s cloud type.
 285
 286 **Step 1**: Cloud Registration/ Create a cloud region to represent the instance
 287
 288 Note: the highlighted part of the body refers to an existing OpenStack
 289 tenant (OOF in this case). It is provided as an illustration and must be adapted
 290 according to your configuration.
 291
 292 ::
 293
 294  PUT https://{{AAI1_PUB_IP}}:{{AAI1_PUB_PORT}}/aai/v13/cloud-infrastructure/cloud-regions/cloud-region/k8scloudowner4/k8sregionfour
 295   {
 296         "cloud-owner": "k8scloudowner4",
 297         "cloud-region-id": "k8sregionfour",
 298         "cloud-type": "k8s",
 299         "owner-defined-type": "t1",
 300         "cloud-region-version": "1.0",
 301         "complex-name": "clli1",
 302         "cloud-zone": "CloudZone",
 303         "sriov-automation": false,
 304     "cloud-extra-info":"{\"openstack-region-id\":\"k8sregionthree\"}",
 305         "esr-system-info-list": {
 306                "esr-system-info": [
 307                               {
 308                                                 "esr-system-info-id": "55f97d59-6cc3-49df-8e69-926565f00066",
 309                                                 "service-url": "http://10.12.25.2:5000/v3",
 310                                                 "user-name": "demo",
 311                                                 "password": "onapdemo",
 312                                                 "system-type": "VIM",
 313                                                 "ssl-insecure": true,
 314                                                 "cloud-domain": "Default",
 315                                                 "default-tenant": "OOF",
 316                                                 "tenant-id": "6bbd2981b210461dbc8fe846df1a7808",
 317                                                 "system-status": "active"
 318                                              }
 319                               ]
 320         }
 321   }
 322
 323 **Step 2:**  Add a complex to the cloud
 324
 325 Adding an already existing complex is enough. You do not need to create new ones.
 326
 327 ::
 328
 329  PUT https://{{AAI1_PUB_IP}}:{{AAI1_PUB_PORT}}/aai/v13/cloud-infrastructure/cloud-regions/cloud-region/k8scloudowner4/k8sregionfour/relationship-list/relationship
 330   {
 331   "related-to": "complex",
 332   "related-link": "/aai/v13/cloud-infrastructure/complexes/complex/clli1",
 333   "relationship-data": [
 334     {
 335        "relationship-key": "complex.physical-location-id",
 336        "relationship-value": "clli1"
 337     }
 338   ]
 339   }
 340
 341 **Step 3:** Trigger the Multicloud plugin registration process
 342
 343 ::
 344
 345   POST http://{{MSB_IP}}:{{MSB_PORT}}/api/multicloud-titaniumcloud/v1/k8scloudowner4/k8sregionfour/registry
 346
 347
 348 This step allws the registration of the K8S cloud with Multicloud. It also
 349 reaches out and adds tenant information to the cloud (see example below, you
 350 will see all kinds of flavor, image information that are associated with the OOF
 351 tenant).
 352
 353 If you did not follow the procedure described above then you will have to connect
 354 on AAI point and manually add a tenant to the cloud region.
 355
 356 Once the tenant declared, you can add the service-subscription to it:
 357
 358 **Step 4:** Create a Service Type
 359
 360 ::
 361
 362  PUT https://{{AAI1_PUB_IP}}:{{AAI1_PUB_PORT}}/aai/v13/service-design-and-creation/services/service/vfw-k8s
 363   {
 364               "service-description": "vfw-k8s",
 365               "service-id": "vfw-k8s"
 366   }
 367
 368 Add subscription service info to the service type of the customer.
 369
 370 ::
 371
 372  PUT https://{{AAI1_PUB_IP}}:{{AAI1_PUB_PORT}}/aai/v16/business/customers/customer/Demonstration/service-subscriptions/service-subscription/vfw-k8s
 373   {
 374            "service-type": "vfw-k8s"
 375   }
 376
 377 Add Service-Subscription to the tenant. The parameter resource-version is a
 378 timestamp.
 379
 380 ::
 381
 382  PUT https://{{AAI1_PUB_IP}}:{{AAI1_PUB_PORT}}/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/k8scloudowner4/k8sregionfour/tenants/tenant/6bbd2981b210461dbc8fe846df1a7808?resource-version=1559345527327
 383   {
 384   "tenant-id": "6bbd2981b210461dbc8fe846df1a7808",
 385   "tenant-name": "OOF",
 386   "resource-version": "1559345527327",
 387   "relationship-list": {
 388        "relationship": [
 389            {
 390                "related-to": "service-subscription",
 391                "relationship-label": "org.onap.relationships.inventory.Uses",
 392                "related-link": "/aai/v13/business/customers/customer/Demonstration/service-subscriptions/service-subscription/vfw-k8s",
 393                "relationship-data": [
 394                    {
 395                        "relationship-key": "customer.global-customer-id",
 396                        "relationship-value": "Demonstration"
 397                    },
 398                    {
 399                        "relationship-key": "service-subscription.service-type",
 400                        "relationship-value": "vfw-k8s"
 401                    }
 402                ]
 403            }
 404     ]
 405   }
 406   }
 407
 408 Distribute the CSAR
 409 -------------------
 410
 411 Once the cloud region is properly declared, it is possible to onboard the service
 412 in the SDC and triggers a distribution from the SDC to the main ONAP components.
 413 SO and other services are notified. A sdc listener is also getting the
 414 distribution information in the multicloud sidecar.
 415 When distribution happens it takes tar.gz file and uploads it to k8s plugin.
 416
 417 Create Profile Manually
 418 -----------------------
 419
 420 K8s-plugin artifacts start in the form of Definitions. These are nothing
 421 but Helm Charts wrapped with some metadata about the chart itself. Once
 422 the Definitions are created, some profiles can be created. Finally it is
 423 possible to customize the definition and instantiate it in the targeted
 424 Kubernetes.
 425
 426 **NOTE:** Refer this link_ for complete API lists and documentation:
 427
 428 .. _link : https://wiki.onap.org/display/DW/MultiCloud+K8s-Plugin-service+API
 429
 430 The profile consists in:
 431
 432 * the **manifest.yaml**. It contains the details for the profile
 433 * a **HELM** values override yaml file: It can have any name as long as it matches
 434   the corresponding entry in the **manifest.yaml**
 435 * Additional files organized in a folder structure: all these files should have
 436   a corresponding entry in **manifest.yaml** file
 437
 438 Create a Profile Artifact
 439 ~~~~~~~~~~~~~~~~~~~~~~~~~
 440
 441 ::
 442
 443  > cd multicloud-k8s/kud/tests/vnfs/testrb/helm/profile
 444   > find .
 445   manifest.yaml
 446   override_values.yaml
 447   testfol
 448   testfol/subdir
 449   testfol/subdir/deployment.yaml
 450
 451   # Create profile tar.gz
 452   > cd profile
 453   > tar -cf profile.tar *
 454   > gzip profile.tar
 455   > mv profile.tar.gz ../
 456
 457 The manifest file contains the following parameters:
 458
 459 ::
 460
 461  ---
 462  version: v1
 463  type:
 464  values: "values_override.yaml"
 465  configresource:
 466    - filepath: testfol/subdir/deployment.yaml
 467      chartpath: vault-consul-dev/templates/deployment.yaml
 468
 469 **Note:** values: "values\_override.yaml" can **be** empty **file** **if**
 470 you are creating **a** dummy **profile**
 471
 472 **Note:** A dummy profile does not need any customization. The following is
 473 optional in the manifest file.
 474
 475 ::
 476
 477  configresource:
 478    - filepath: testfol/subdir/deployment.yaml
 479      chartpath: vault-consul-dev/templates/deployment.yaml
 480
 481 The name of the Definition is retrived from SDC service distribution stage.
 482
 483 Retrieve the definition name
 484 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 485
 486 Execute the following command on the ONAP K8s Rancher host to read the definition
 487 name and its version:
 488
 489 ::
 490
 491  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
 492
 493 From the output read the name of the definition which is "rb-name" and
 494 "rb-version" respectively
 495
 496 ::
 497
 498  127.0.0.1 - - [15/Jul/2019:07:56:21 +0000] "POST /v1/rb/definition/test-rbdef/1/content HTTP/1.1"
 499
 500 Get definition
 501 ^^^^^^^^^^^^^^
 502
 503 With this information, it is possible to upload the profile with the following JSON data
 504
 505 ::
 506
 507  {
 508    "rb-name": "test-rbdef",
 509    "rb-version": "1",
 510    "profile-name": "p1",
 511    "release-name": "r1", //If release-name is not provided, profile-name will be used
 512    "namespace": "testnamespace1",
 513    "kubernetes-version": "1.13.5"
 514  }
 515
 516
 517 Create Profile
 518 ^^^^^^^^^^^^^^
 519 ::
 520
 521  curl -i -d @create_rbprofile.json -X POST http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile
 522
 523
 524
 525 UPLOAD artifact for Profile
 526 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 527
 528 ::
 529
 530  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
 531
 532
 533 GET Profiles
 534 ^^^^^^^^^^^^
 535
 536 ::
 537
 538  curl -i http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile
 539   # Get one Profile
 540   curl -i http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile/p1
 541
 542
 543 DELETE Profile
 544 ^^^^^^^^^^^^^^
 545
 546 ::
 547
 548  curl -i -X DELETE http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/rb/definition/test-rbdef/1/profile/p1
 549
 550
 551 Instantiation
 552 -------------
 553
 554 Instantiation is done by SO. SO then talks to Multi Cloud-broker via MSB
 555 and that in turn looks up the cloud region in AAI to find the endpoint.
 556 If k8sregion one is properly registered in AAI (SO check),
 557 then the broker will know that it needs to talk to k8s-plugin based on
 558 the type of the registration.
 559
 560 Instantiate the created Profile via the following REST API
 561 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 562
 563 ::
 564
 565  Using the following JSON:
 566   {
 567    "cloud-region": "kud",
 568    "profile-name": "p1",
 569    "rb-name":"test-rbdef",
 570    "rb-version":"1",
 571    "labels": {
 572    }
 573   }
 574
 575 **NOTE**: Make sure that the namespace is already created before instantiation.
 576
 577 Instantiate the profile with the ID provided above
 578
 579 Instantiate a Profile
 580 ~~~~~~~~~~~~~~~~~~~~~
 581
 582 ::
 583
 584  curl -d @create_rbinstance.json http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/instance
 585
 586
 587 The command shall return the following JSON
 588
 589 ::
 590
 591  {
 592  "id": "ZKMTSaxv",
 593  "rb-name": "mongo",
 594  "rb-version": "1",
 595  "profile-name": "profile1",
 596  "cloud-region": "kud",
 597  "namespace": "testns",
 598  "resources": [
 599    {
 600      "GVK": {
 601        "Group": "",
 602        "Version": "v1",
 603        "Kind": "Service"
 604      },
 605      "Name": "mongo"
 606    },
 607    {
 608      "GVK": {
 609        "Group": "",
 610        "Version": "v1",
 611        "Kind": "Service"
 612      },
 613      "Name": "mongo-read"
 614    },
 615    {
 616      "GVK": {
 617        "Group": "apps",
 618        "Version": "v1beta1",
 619        "Kind": "StatefulSet"
 620      },
 621      "Name": "profile1-mongo"
 622    }
 623  ]
 624  }
 625
 626 Delete Instantiated Kubernetes resources
 627 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 628
 629 The **id** field from the returned JSON can be used to **DELETE** the
 630 resources created in the previous step. This executes a Delete operation
 631 using the Kubernetes API.
 632
 633 ::
 634
 635  curl -X DELETE http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/instance/ZKMTSaxv
 636
 637
 638 GET Instantiated Kubernetes resources
 639 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 640
 641 The **id** field from the returned JSON can be used to **GET** the
 642 resources created in the previous step. This executes a get operation
 643 using the Kubernetes API.
 644
 645 ::
 646
 647  curl -X GET http://MSB_NODE_IP:30280/api/multicloud-k8s/v1/v1/instance/ZKMTSaxv
 648
 649
 650 `*\ 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>`__
 651
 652 Create User parameters
 653 ~~~~~~~~~~~~~~~~~~~~~~
 654
 655 We need to create parameters that ultimately get translated as:
 656
 657 ::
 658
 659  "user_directives": {
 660  "attributes": [
 661  {
 662  "attribute_name": "definition-name",
 663  "attribute_value": "edgex"
 664  },
 665  {
 666  "attribute_name": "definition-version",
 667  "attribute_value": "v1"
 668  },
 669  {
 670  "attribute_name": "profile-name",
 671  "attribute_value": "profile1"
 672  }
 673  ]
 674  }