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