docs/sections/components/dcae-cli/walkthrough.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
   2 .. http://creativecommons.org/licenses/by/4.0\r
   3 \r
   4 .. _walkthrough:\r
   5 \r
   6 Walk-through\r
   7 ============\r
   8 \r
   9 The goal of this quickstart is to provide an overview of the\r
  10 functionalities of the ``dcae-cli`` and walk you through the\r
  11 capabilities:\r
  12 \r
  13 -  `Adding data formats <#adding-data-formats>`__\r
  14 -  `Adding component <#adding-component>`__\r
  15 -  `Setting profile <#setting-profile>`__\r
  16 -  `Development and testing <#development-and-testing>`__\r
  17 -  `Publishing component <#publishing-component>`__\r
  18 -  `Shared catalog <#shared-catalog>`__\r
  19 \r
  20 .. This walk-through uses example projects: COMMENTED OUT FOR NOW TBD\r
  21 .. \r
  22 .. -  `laika <ONAP%20URL%20TBD>`__\r
  23 .. -  `CDAP examples <ONAP%20URL%20TBD>`__\r
  24 \r
  25 .. _adding-data-formats:\r
  26 \r
  27 Adding data formats\r
  28 -------------------\r
  29 \r
  30 ``data_format`` is the sub-command that is used to execute operations\r
  31 that manage `data formats <../data-formats.md>`__.\r
  32 \r
  33 ::\r
  34 \r
  35     $ dcae_cli data_format --help\r
  36     Usage: dcae_cli data_format [OPTIONS] COMMAND [ARGS]...\r
  37 \r
  38     Options:\r
  39       --help  Show this message and exit.\r
  40 \r
  41     Commands:\r
  42       add      Tracks a data format file SPECIFICATION...\r
  43       generate Generates a data format file from JSON input examples\r
  44       list     Lists all your data formats\r
  45       publish  Publishes data format to make publicly...\r
  46       show     Provides more information about FORMAT\r
  47 \r
  48 Your data format must be in the catalog in order to use in the component\r
  49 specification. Check the catalog using the ``data_format list``\r
  50 sub-command:\r
  51 \r
  52 ::\r
  53 \r
  54     $ dcae_cli data_format list\r
  55 \r
  56     Data formats for mh677g\r
  57     +------+---------+-------------+--------+----------+\r
  58     | Name | Version | Description | Status | Modified |\r
  59     +------+---------+-------------+--------+----------+\r
  60     |      |         |             |        |          |\r
  61     +------+---------+-------------+--------+----------+\r
  62 \r
  63 The fields ``name``, ``version``, ``description`` are referenced from\r
  64 the data format JSON from the ``self`` JSON.\r
  65 \r
  66 There are no data formats so you must add the data formats that your\r
  67 component specification references. Use the ``data_format add``\r
  68 sub-command:\r
  69 \r
  70 Here’s an example command:\r
  71 \r
  72 ::\r
  73 \r
  74     dcae_cli data_format add health.json\r
  75 \r
  76 Verify that it was added:\r
  77 \r
  78 ::\r
  79 \r
  80     $ dcae_cli data_format list\r
  81 \r
  82     Data formats for mh677g\r
  83     +-------------------------------+---------+-------------------------------------------+--------+----------------------------+\r
  84     | Name                          | Version | Description                               | Status | Modified                   |\r
  85     +-------------------------------+---------+-------------------------------------------+--------+----------------------------+\r
  86     | sandbox.platform.laika.health | 0.1.0   | Data format used for the /health endpoint | staged | 2017-05-23 04:02:38.952799 |\r
  87     +-------------------------------+---------+-------------------------------------------+--------+----------------------------+\r
  88 \r
  89 Go ahead and add other referenced data formats.\r
  90 \r
  91 If you have JSON input you can generate a data format like this:\r
  92 \r
  93 ::\r
  94 \r
  95     $ dcae_cli data_format --keywords generate myname:1.0.0  myjsoninputfile\r
  96 \r
  97 where ``myname`` is the name of your data format, ``1.0.0`` is an\r
  98 example version, and ``myjsoninputfile`` is an example JSON input file\r
  99 (a directory of input JSON files can also be provided). The\r
 100 ``--keywords`` option adds additional data attributes that can be\r
 101 completed to provide a more detailed data characterization. In any event\r
 102 the output should be reviewed for accuracy. The data format is written\r
 103 to stdout.\r
 104 \r
 105 .. _adding-component:\r
 106 \r
 107 Adding component\r
 108 ----------------\r
 109 \r
 110 ``component`` is the sub-command that is used to work with operations\r
 111 for components:\r
 112 \r
 113 ::\r
 114 \r
 115     $ dcae_cli component --help\r
 116     Usage: dcae_cli component [OPTIONS] COMMAND [ARGS]...\r
 117 \r
 118     Options:\r
 119       --help  Show this message and exit.\r
 120 \r
 121     Commands:\r
 122       add\r
 123       dev       Set up component in development for...\r
 124       list      Lists components in the public catalog.\r
 125       publish   Pushes COMPONENT to the public catalog\r
 126       run       Runs the latest version of COMPONENT.\r
 127       show      Provides more information about COMPONENT\r
 128       undeploy  Undeploys the latest version of COMPONENT.\r
 129 \r
 130 Your component must be accessible from the catalog in order for it to be\r
 131 used. Check the catalog using the ``component list`` sub-command:\r
 132 \r
 133 ::\r
 134 \r
 135     $ dcae_cli component list\r
 136     Active profile: solutioning\r
 137 \r
 138     +------+---------+------+-------------+--------+----------+-----------+\r
 139     | Name | Version | Type | Description | Status | Modified | #Deployed |\r
 140     +------+---------+------+-------------+--------+----------+-----------+\r
 141     |      |         |      |             |        |          |           |\r
 142     +------+---------+------+-------------+--------+----------+-----------+\r
 143 \r
 144     Use the "--deployed" option to see more details on deployments\r
 145 \r
 146 The fields ``name``, ``version``, ``type``, ``description`` are\r
 147 referenced from the component specification’s ``self`` JSON.\r
 148 \r
 149 There are no components so you must add your component. Use the\r
 150 ``component add`` sub-command. The command is the same for docker and\r
 151 cdap components:\r
 152 \r
 153 ::\r
 154 \r
 155     $ dcae_cli component add --help\r
 156     Usage: dcae_cli component add [OPTIONS] SPECIFICATION\r
 157 \r
 158     Options:\r
 159       --update  Updates a locally added component if it has not been already\r
 160                 pushed\r
 161       --help    Show this message and exit.\r
 162 \r
 163 *Note* use the ``--update`` flag to replace existing staged instances.\r
 164 \r
 165 The ``component dev`` sub-command can be useful in validating and\r
 166 experimenting when crafting your component specification. See details\r
 167 about ``dev`` under `Development and\r
 168 testing <#development-and-testing>`__.\r
 169 \r
 170 Once we add the components laika and helloworld, let’s verify that they\r
 171 got added ok:\r
 172 \r
 173 ::\r
 174 \r
 175     $ dcae_cli component list\r
 176     Active profile: solutioning\r
 177 \r
 178     +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
 179     | Name                    | Version | Type   | Description                                                   | Status | Modified                   | #Deployed |\r
 180     +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
 181     | cdap.helloworld.endnode | 0.8.0   | cdap   | cdap test component                                           | staged | 2017-05-23 04:14:35.588075 | 0         |\r
 182     | sandbox.platform.laika  | 0.5.0   | docker | Web service used as a stand-alone test DCAE service compone.. | staged | 2017-05-23 04:07:44.065610 | 0         |\r
 183     +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
 184 \r
 185     Use the "--deployed" option to see more details on deployments\r
 186 \r
 187 .. _setting-profile:\r
 188 \r
 189 Setting profile\r
 190 ---------------\r
 191 \r
 192 ``profile`` is the sub-command that is used to manage profiles. These\r
 193 profiles contain environment variables used to connect to different\r
 194 environments. This is used in the running and deployment of your\r
 195 component using the ``dcae_cli component run`` command. The ``dcae-cli``\r
 196 ships with profiles for ``solutioning`` and ``rework``.\r
 197 \r
 198 ::\r
 199 \r
 200     $ dcae_cli profiles --help\r
 201     Usage: dcae_cli profiles [OPTIONS] COMMAND [ARGS]...\r
 202 \r
 203     Options:\r
 204       --help  Show this message and exit.\r
 205 \r
 206     Commands:\r
 207       activate  Sets profile NAME as the active profile\r
 208       create    Creates a new profile NAME initialized with...\r
 209       delete    Deletes profile NAME\r
 210       list      Lists available profiles\r
 211       set       Updates profile NAME such that KEY=VALUE\r
 212       show      Prints the profile dictionary\r
 213 \r
 214 To see what variables a profile contains, you can use the ``show``\r
 215 command, as in ``dcae_cli profiles show PROFILE_NAME``\r
 216 \r
 217 Use the ``create`` sub-command to create your own profile and assign new\r
 218 values using the ``set`` command. Afterwards you will need to\r
 219 ``activate`` the profile you wish to use. First take a look at which\r
 220 profile is active:\r
 221 \r
 222 ::\r
 223 \r
 224     $ dcae_cli profiles list\r
 225        rework\r
 226     *  solutioning\r
 227 \r
 228 The active profile is ``solutioning`` so to activate *rework* to use\r
 229 ``rework``:\r
 230 \r
 231 ::\r
 232 \r
 233     $ dcae_cli profiles activate rework\r
 234 \r
 235 Check\r
 236 \r
 237 ::\r
 238 \r
 239     $ dcae_cli profiles list\r
 240     *  rework\r
 241        solutioning\r
 242 \r
 243 .. _development-and-testing:\r
 244 \r
 245 Development and testing\r
 246 -----------------------\r
 247 \r
 248 The following operations under the sub-command ``component`` are aimed\r
 249 to help developers with testing:\r
 250 \r
 251 -  ``run``\r
 252 -  ``undeploy``\r
 253 -  ``dev``\r
 254 \r
 255 ``run``\r
 256 ~~~~~~~\r
 257 \r
 258 The ``run`` operation is to be used for running your application in its\r
 259 container remotely on the activated environment. Docker containers have\r
 260 the additional option to run locally on your development machine.\r
 261 \r
 262 In order to run your application, you must have added your data formats\r
 263 and your component to your catalog.\r
 264 \r
 265 Let’s verify that your component is in the catalog:\r
 266 \r
 267 ::\r
 268 \r
 269     $ dcae_cli component list                                                                                       \r
 270     Active profile: solutioning\r
 271 \r
 272     +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
 273     | Name                    | Version | Type   | Description                                                   | Status | Modified                   | #Deployed |\r
 274     +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
 275     | cdap.helloworld.endnode | 0.8.0   | cdap   | cdap test component                                           | staged | 2017-05-23 04:14:35.588075 | 0         |\r
 276     | sandbox.platform.laika  | 0.5.0   | docker | Web service used as a stand-alone test DCAE service compone.. | staged | 2017-05-23 04:07:44.065610 | 0         |\r
 277     +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
 278 \r
 279     Use the "--deployed" option to see more details on deployments\r
 280 \r
 281 Docker\r
 282 ^^^^^^\r
 283 \r
 284 **NOTE** Make sure your Docker image has been uploaded to the shared\r
 285 registry.\r
 286 \r
 287 For Docker containers, you can run either attached or unattached.\r
 288 Attached means that the dcae-cli tool will launch the container and not\r
 289 terminate. The dcae-cli while attached will stream in the logs of the\r
 290 Docker container. Doing a Ctrl-C will terminate the run session which\r
 291 means undeploy your container and force a clean up automatically.\r
 292 \r
 293 Running unattached means simply deploy your container. You will need to\r
 294 execute ``undeploy`` when you are done testing. #### CDAP\r
 295 \r
 296 **NOTE** Make sure your CDAP jar has been uploaded to Nexus.\r
 297 \r
 298 TODO\r
 299 \r
 300 ``undeploy``\r
 301 ~~~~~~~~~~~~\r
 302 \r
 303 The ``undeploy`` operation is to be used to undeploy any instances of a\r
 304 specified component, version that you have deployed. This includes\r
 305 cleaning up of configuration.\r
 306 \r
 307 Let’s undeploy ``sandbox.platform.laika`` that was deployed from the\r
 308 previous section:\r
 309 \r
 310 ::\r
 311 \r
 312     $ dcae_cli component undeploy sandbox.platform.laika:0.5.0\r
 313     DCAE.Undeploy | WARNING | Undeploying components: 1\r
 314     DCAE.Undeploy | WARNING | Undeployed components: 1\r
 315 \r
 316 .. _walkthrough-dev:\r
 317 \r
 318 ``dev``\r
 319 ~~~~~~~\r
 320 \r
 321 The ``dev`` operation is a convenient operation that can be useful for\r
 322 the development and testing of your component. It can be used to:\r
 323 \r
 324 -  Help validate your experimental component specification before\r
 325    uploading to the catalog\r
 326 -  Generate the application configuration from the component\r
 327    specification and make it available in a test environment. This\r
 328    allows you to view your resulting configuration for local development\r
 329    and to help debug potential related issues.\r
 330 \r
 331 Let’s say you have a component specification called\r
 332 ``component-spec.json``:\r
 333 \r
 334 ::\r
 335 \r
 336     $ dcae_cli component dev component-spec.json \r
 337     Ready for component development\r
 338 \r
 339     Setup these environment varibles. Run "source env_solutioning":\r
 340 \r
 341     export DOCKER_HOST=SOME_DOCKER_HOST:2376\r
 342     export SERVICE_CHECK_INTERVAL=15s\r
 343     export CONFIG_BINDING_SERVICE=config_binding_service\r
 344     export HOSTNAME=mh677g.95740959-63d2-492a-b964-62a6dce2591d.0-6-0.sandbox-platform-laika\r
 345     export CONSUL_HOST=SOME_CONSUL_HOST\r
 346     export CDAP_BROKER=cdap_broker\r
 347     export SERVICE_NAME=mh677g.95740959-63d2-492a-b964-62a6dce2591d.0-6-0.sandbox-platform-laika\r
 348     export SERVICE_CHECK_TIMEOUT=1s\r
 349     export SERVICE_CHECK_HTTP=/health\r
 350 \r
 351     Press any key to stop and to clean up\r
 352 \r
 353 Your application configuration is now available under the name\r
 354 ``mh677g.95740959-63d2-492a-b964-62a6dce2591d.0-6-0.sandbox-platform-laika``.\r
 355 \r
 356 To view the resulting configuration, you can ``curl`` a request to the\r
 357 config binding service or programmatically fetch your configuration\r
 358 within your application.\r
 359 \r
 360 You need to first query Consul to get the ip and port of config binding\r
 361 service:\r
 362 \r
 363 ::\r
 364 \r
 365     curl http://$CONSUL_HOST:8500/v1/catalog/service/$CONFIG_BINDING_SERVICE\r
 366     [\r
 367       {\r
 368         "ID": "983d5c94-c508-4a8a-9be3-5912bd09786b",\r
 369         "Node": "realsolcnsl00",\r
 370         "Address": "10.226.1.22",\r
 371         "TaggedAddresses": {\r
 372           "lan": "10.226.1.22",\r
 373           "wan": "10.226.1.22"\r
 374         },\r
 375         "NodeMeta": {},\r
 376         "ServiceID": "5f371f295c90:config_binding_service:10000",\r
 377         "ServiceName": "config_binding_service",\r
 378         "ServiceTags": [],\r
 379         "ServiceAddress": "XXXX",\r
 380         "ServicePort": 32770,\r
 381         "ServiceEnableTagOverride": false,\r
 382         "CreateIndex": 487,\r
 383         "ModifyIndex": 487\r
 384       }\r
 385     ]\r
 386 \r
 387 .. _dmaap-testing:\r
 388 \r
 389 DMaaP testing\r
 390 ~~~~~~~~~~~~~\r
 391 \r
 392 Currently, the dcae-cli does not have the capability of provisioning\r
 393 topics. In order to do testing with message router topics or with data\r
 394 router feeds, the developer must provision the topic or the feed\r
 395 manually and provide the connection details in the form of a JSON in a\r
 396 file to the dcae-cli. This file is to be passed in when using the\r
 397 ``run`` and ``dev`` commands with the option ``--dmaap-file``.\r
 398 \r
 399 The structure of the DMaaP JSON is an object of config keys to matching\r
 400 topic or feed connection details. Config keys are the ``config_key``\r
 401 values specified in your component specification streams section where\r
 402 the streams must be type message router or data router. Information\r
 403 about the associated connection details can be found on `this\r
 404 page <dmaap-connection-objects.md>`__. Please check it out.\r
 405 \r
 406 For example, if you have a component specification that has the\r
 407 following streams entry:\r
 408 \r
 409 .. code:: json\r
 410 \r
 411     "streams": {\r
 412         "publishes": [{\r
 413             "format": "ves",\r
 414             "version": "1.0.0",\r
 415             "type": "message router",\r
 416             "config_key": "ves_connection"\r
 417         }]\r
 418     }\r
 419 \r
 420 Then to deploy and to run your component, you must use the\r
 421 ``--dmaap-file`` command and pass in a JSON that looks like:\r
 422 \r
 423 .. code:: json\r
 424 \r
 425     {\r
 426         "ves_connection": {\r
 427             "type": "message_router",\r
 428             "dmaap_info": {\r
 429                 "topic_url": "https://we-are-message-router.us:3905/events/some-topic"\r
 430             }\r
 431         }\r
 432     }\r
 433 \r
 434 The provided DMaaP JSON is used to simulate the output of provisioning\r
 435 and will be used to merge with the generated application configuration\r
 436 at runtime.\r
 437 \r
 438 Your final application config will look like:\r
 439 \r
 440 .. code:: json\r
 441 \r
 442     {\r
 443         "streams_publishes": {\r
 444             "ves_connection": {\r
 445                 "type": "message_router",\r
 446                 "dmaap_info": {\r
 447                     "topic_url": "https://we-are-message-router.us:3905/events/some-topic"\r
 448                 }\r
 449             }\r
 450         }\r
 451     }\r
 452 \r
 453 Data router subscribers\r
 454 ^^^^^^^^^^^^^^^^^^^^^^^\r
 455 \r
 456 Note for data router subscriber testing, you will need the delivery url\r
 457 in order to provision the subscriber to the feed. This is constructed at\r
 458 deployment time and will be provided by the dcae-cli after you deploy\r
 459 your component. The delivery urls will be displayed to the screen:\r
 460 \r
 461 ::\r
 462 \r
 463     DCAE.Run | WARNING | Your component is a data router subscriber. Here are the delivery urls: \r
 464 \r
 465             some-sub-dr: http://SOME_IP:32838/identity\r
 466 \r
 467 *Sourced at deployment* testing\r
 468 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
 469 \r
 470 Components may have configuration parameters whose values are to be\r
 471 sourced at deployment time. For example, there are components whose\r
 472 configuration parameters are to come from DTI events which are only\r
 473 available when the component is getting deployed. These configuration\r
 474 parameters must be setup correctly in the `component\r
 475 specification <http://localhost:8000/components/component-specification/docker-specification/#configuration-parameters>`__\r
 476 by setting the property ``sourced_at_deployment`` to ``true`` for each\r
 477 and every parameter that is expected to come in at deployment time.\r
 478 \r
 479 Once your component specification has been updated correctly, you must\r
 480 use the ``--inputs-file`` command-line argument when running the\r
 481 commands ``dev`` or ``run`` with your component. This is to simulate\r
 482 providing the dynamic, deployment time values for those parameters\r
 483 marked as ``sourced_at_deployment``.\r
 484 \r
 485 For example, if your component specification has the following\r
 486 configuration parameters:\r
 487 \r
 488 ::\r
 489 \r
 490     "parameters": [{\r
 491         "name": "vnf-ip",\r
 492         "value": "",\r
 493         "sourced_at_deployment": true\r
 494     },\r
 495     {\r
 496         "name": "static-param",\r
 497         "value": 5\r
 498     }]\r
 499 \r
 500 You would have to pass in an inputs file that looks like:\r
 501 \r
 502 ::\r
 503 \r
 504     {\r
 505         "vnf-ip": "10.100.1.100"\r
 506     }\r
 507 \r
 508 Your application configuration would look like:\r
 509 \r
 510 ::\r
 511 \r
 512     {\r
 513         "vnf-ip": "10.100.1.100",\r
 514         "static-param": 5\r
 515     }\r
 516 \r
 517 Publishing component\r
 518 --------------------\r
 519 \r
 520 Once components have their component specifications crafted and\r
 521 validated and have been tested, components should be published in the\r
 522 shared onboarding catalog using the ``publish`` sub-command for both\r
 523 data formats and components. You must publish all data formats of a\r
 524 component before publishing a component.\r
 525 \r
 526 Publishing will change the status of a component, be made accessible for\r
 527 other developers to use, and will generate the associated TOSCA models\r
 528 for use in designing of compositions.\r
 529 \r
 530 ::\r
 531 \r
 532     dcae_cli component publish sandbox.platform.laika:0.5.0\r
 533 \r
 534 Shared catalog\r
 535 --------------\r
 536 \r
 537 ``catalog`` is the sub-command used to access and to browse the shared\r
 538 onboarding catalog to view components and data formats that have been\r
 539 published and that are being worked on. Components and data formats have\r
 540 two statuses ``staged`` and ``published``.\r
 541 \r
 542 Staged means that the resource has been simply added and is under\r
 543 development. It is to be used only by the owner. Published means that\r
 544 the resource has been fully developed and tested and is ready to be\r
 545 shared.\r
 546 \r
 547 Published components can be deployed by non-owners and published data\r
 548 formats can be used in component specifications of non-owners.\r
 549 \r
 550 There are two available operations:\r
 551 \r
 552 ::\r
 553 \r
 554     $ dcae_cli catalog --help\r
 555     Usage: dcae_cli catalog [OPTIONS] COMMAND [ARGS]...\r
 556 \r
 557     Options:\r
 558       --help  Show this message and exit.\r
 559 \r
 560     Commands:\r
 561       list\r
 562       show\r
 563 \r
 564 Staged components can be viewed under the ``list`` operation using the\r
 565 ``--expanded`` flag.\r