path: root/docs/sections/components/dcae-cli/walkthrough.rst

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0

.. _walkthrough:

Walk-through
============

This section demonstrates the flow and usage of the dcae_cli tool to
onboard a typical component to the DCAE platform. The commands are
explained in more detail in :doc:`dcae_cli Commands <commands>`.

-  `Add (and validate) a data format <#add-a-data-format>`__
-  `Add (and validate) the component <#add-the-component>`__
-  `View the platform generated
   configuration <#view-the-platform-generated-configuration>`__
-  `If needed, Create the dmaap file for Dmaap Testing <#create-the-input-file-for-dmaap-testing>`__
-  `If needed, Create the input file for *Sourced at Deployment* Testing <#create-the-input-file-for-sourced-at-deployment-testing>`__
-  `Run the component <#run-the-component>`__
-  :any:`Undeploy the component <dcae_cli_undeploy_the_component>`
-  :any:`Publish the component and data_format <dcae_cli_publish_the_component_and_data_format>` to let others
   know its ready for reuse
-  `List the Catalog Contents <#list-the-catalog-contents>`__ to see
   your published resources


--------------

Add a Data Format
-----------------

::

    $ dcae_cli data_format add $HOME/yourapp/data-formats/health.json

Verify that the data_format was added

::

    $ dcae_cli data_format list | grep yourapp                                                                                              
    | sandbox.platform.yourapp.health | 0.1.0   | Data format used for the /health endpoint                   | staged    | 2017-11-07 21:48:47.736518 |

(Note: Each of the data formats for your component need to be added,
unless already existing in the onboarding catalog )

--------------

Add the Component
-----------------

::

    $ dcae_cli component add $HOME/yourapp/component-spec.json

Verify that the component was added

::

    $ dcae_cli component list 
    Active profile: solutioning

    +-------------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+
    | Name                          | Version | Type   | Description                                                   | Status | Modified                   | #Deployed |
    +-------------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+
    | sandbox.platform.yourapp      | 0.7.0   | docker | Web service used as a stand-alone test DCAE service compone.. | staged | 2017-11-08 20:27:34.168854 | 0         |
    +-------------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+

--------------

.. _dcae-cli-view-the-platform:

View the platform generated configuration
-----------------------------------------

The ``component dev`` command is useful during onboarding. Running this
command is part of a multi-step process that sets up a temporary test
environment, generates your application configuration, makes it
available in that environment, and allows you to view that configuration
to help with debugging.

Here is a step-by-step example based on a component specification called
``component-spec.json``.

Step 1 - Run the component dev command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(This creates a file called env_$ENV (in the current directory)- where
$ENV is the name of the active profile. Note: SERVICE_NAME and HOSTNAME
always resolve to the same value).

::

    $ dcae_cli component dev component-spec.json
    Ready for component development

    Setup these environment variables. Run "source env_solutioning":

    export DOCKER_HOST=yourdockerhost.com:2376
    export SERVICE_CHECK_INTERVAL=15s
    export CONFIG_BINDING_SERVICE=config_binding_service
    export HOSTNAME=user12.b599cf0e-75e8-484b-b8e2-557576d77036.0-7-0.sandbox-platform-yourapp
    export CONSUL_HOST=yourconsulhost.com
    export CDAP_BROKER=cdap_broker
    export SERVICE_NAME=user12.b599cf0e-75e8-484b-b8e2-557576d77036.0-7-0.sandbox-platform-yourapp
    export SERVICE_CHECK_TIMEOUT=1s
    export SERVICE_CHECK_HTTP=/health

    Press any key to stop and to clean up

Step 2 - Setup the environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In another window, setup the temporary testing environment, by executing
the environment file created above.

::

    $ source env_solutioning

(The application configuration is now available under the SERVICE_NAME
shown above -
``user12.b599cf0e-75e8-484b-b8e2-557576d77036.0-7-0.sandbox-platform-yourapp``).

Step 3 - Query CONSUL
~~~~~~~~~~~~~~~~~~~~~

Query CONSUL to get the IP/PORT of CONFIG BINDING SERVICE

::

    $ curl http://$CONSUL_HOST:8500/v1/catalog/service/$CONFIG_BINDING_SERVICE
    [
      {
        "ID": "bfbc220d-4603-7f90-ec2e-611d3c330f20",
        "Node":"docker00",
        "Address": "10.226.1.15",
        "Datacenter":"solutioning-central",
        "TaggedAddresses": {
          "lan":"10.226.1.15",
          "wan":"10.226.1.15"
        },
        "NodeMeta": {},
        "ServiceID": "472b116f9035:config_binding_service:10000",
        "ServiceName": "config_binding_service",
        "ServiceTags": [],
        "ServiceAddress":"135.205.226.126",
        "ServicePort":10000,
        "ServiceEnableTagOverride": false,
        "CreateIndex":1078990,
        "ModifyIndex":1078990
      }
    ]

Fetch the generated configuration from CONFIG BINDING SERVICE using the
‘serviceaddress’ and ‘serviceport’ from above along with $SERVICE_NAME
from earlier.

::

    $ curl http://135.205.226.126:10000/service_component/user12.b599cf0e-75e8-484b-b8e2-557576d77036.0-7-0.sandbox-platform-yourapp

    {"streams_subscribes": {}, "services_calls": {}, "multiplier": 3, "streams_publishes": {}}

--------------

.. _dcae-cli-walkthrough-dmaap-testing:

Create the input file for Dmaap Testing
---------------------------------------

Currently, the dcae-cli tool does not have the capability to provision
topics or feeds. Therefore, in order to test with ``message router`` or
``data router`` feeds, the developer must manually provision the topic
or feed and then provide the connection details in the form of a DMaap
JSON file for testing. This file is then passed in on the
``component run`` or ``component dev`` commands by using the argument
``--dmaap-file``.

The structure of the DMaaP JSON is an object of config keys with the
topic or feed connection details. The config keys are the ``config_key``
values specified in the component specification streams section where
the streams must be type ``message router`` or ``data router``. This
file corresponds to the ``Dmaap Connection Object`` which is generated
by the platform and provided to the component at runtime. The exception
is that ``delivery_url`` cannot be provided in the dmaap-file because it
is not created until the component is deployed. Refer to :any:`Dmaap Connection Object <dmaap-connection-objects>`, for details on creating the dmaap-file for testing.

--------------

Create the input file for *Sourced at Deployment* Testing
---------------------------------------------------------

Components may have configuration parameters whose values are to be
sourced at deployment time. This is established in the
:any:`component specification <common-specification-parameters>`
by setting the property ``sourced_at_deployment`` to ``true`` for each
applicable parameter.

Then, use the ``--inputs-file`` command-line argument when running the
component ``dev`` or ``run`` command for your component. This is to
simulate providing the dynamic, deployment time values for those
parameters marked as ``sourced_at_deployment``.

For example, if your component specification has the following
configuration parameters:

::

    "parameters": [{
        "name": "vnf-ip",
        "value": "",
        "sourced_at_deployment": true
    },
    {
        "name": "static-param",
        "value": 5
    }]

Pass in an input file that looks like:

::

    {
        "vnf-ip": "10.100.1.100"
    }

The application configuration would look like:

::

    {
        "vnf-ip": "10.100.1.100",
        "static-param": 5
    }

--------------

Run the component
-----------------

The ``run`` operation is to be used for running your application in its
container remotely on the activated environment. Docker containers have
the additional option to run locally on your development machine. If the
component uses Dmaap, you can specify the Dmaap Connection Object as
well. Refer to :any:`Dmaap Connection Object <dmaap-connection-objects>`.

In order to run the component, the data formats and component must have
been added to the onboarding catalog.

To verify what’s in the catalog:

::

    $ dcae_cli catalog list --expanded                                                                                      
    Active profile: solutioning
    +---------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+
    | Name                      | Version | Type   | Description                                                   | Status | Modified                   | #Deployed |
    +---------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+
    | sandbox.platform.yourapp  | 0.7.0   | docker | Web service used as a stand-alone test DCAE service compone.. | staged | 2017-11-08 20:27:34.168854 | 0         |
    +---------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+

For Docker

**NOTE** Make sure the Docker image has been uploaded to the shared
registry.

A docker component can be run in either ``attached`` or ``unattached``
mode. (Default is unattached).

+------------------+-----------------------------------------------------------+
| Mode             | Description                                               |
+==================+===========================================================+
| attached         | component is run in the foreground, container             |
|                  | logs are streamed to stdout. Ctrl-C is used to            |
|                  | terminate the dcae_cli session.                           |
+------------------+-----------------------------------------------------------+
| unattached       | component is run in the background container              |
|                  | logs are viewed via ``docker logs`` command,              |
|                  | container runs until undeployed with dcae_cli             |
|                  | ``undeploy`` command.                                     |
+------------------+-----------------------------------------------------------+

Run a component in attached mode:
---------------------------------

::

    $ dcae_cli -v component run --attached sandbox.platform.yourapp:0.7.0
    DCAE.Docker | INFO | Running image 'nexus01.server.com:18443/repository/solutioning01-mte2-docker/dcae-platform/yourapp:0.7.0' as 'user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp'
    DCAE.Docker.user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp | INFO | Consul host: yourconsulhost.com

    DCAE.Docker.user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp | INFO | service name: user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp

    DCAE.Docker.user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp | INFO | get_config returned the following configuration: {"streams_subscribes": {}, "multiplier": 3, "services_calls": {}, "streams_publishes": {}}

    DCAE.Docker.user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp | INFO |  * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)

    DCAE.Docker.user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp | INFO | 135.205.226.156 - - [08/Nov/2017 23:27:30] "GET /health HTTP/1.1" 200 -


    Hit Ctrl-C to terminate session.

    ^C
    DCAE.Docker | INFO | Stopping container 'user12.dbb13a3c-d870-487e-b584-89929b856b5c.0-7-0.sandbox-platform-yourapp' and cleaning up...

Run a component in unattached mode:
-----------------------------------

::

    $ dcae_cli -v component run sandbox.platform.yourapp:0.7.0
    DCAE.Docker | INFO | Running image 'nexus01.server.com:18443/repository/solutioning01-mte2-docker/dcae-platform/yourapp:0.7.0' as 'user12.22629ebd-417e-4e61-a9a0-f0cb16d4cef2.0-7-0.sandbox-platform-yourapp'
    DCAE.Run | INFO | Deployed user12.22629ebd-417e-4e61-a9a0-f0cb16d4cef2.0-7-0.sandbox-platform-yourapp. Verifying..
    DCAE.Run | INFO | Container is up and healthy

**NOTE** You must undeploy this component when finished testing. This is
important to conserve resources in the environment.

Run a component that subscribes to Dmaap Message Router or Data Router
----------------------------------------------------------------------

::

    $ dcae_cli -v component run $component-that-uses-dmamp --dmaap-file $dmaap-connection-object

Run a component that expects input that is ``sourced at deployment``
--------------------------------------------------------------------

::

    $ dcae_cli -v component run $component-that-expects-dti --inputs-file $input-file-to-simulate-dti

--------------


.. _dcae_cli_undeploy_the_component:

Undeploy the component
----------------------

The ``undeploy`` command is used to undeploy any instance of a specified component/version that you have deployed. This includes cleaning up the configuration. 
Undeploy ``sandbox.platform.yourapp:0.7.0`` that was deployed above: 
``$ dcae_cli -v component undeploy sandbox.platform.yourapp:0.7.0 DCAE.Undeploy | WARNING | Undeploying components: 1 DCAE.Undeploy | WARNING | Undeployed components: 1`` 

.. _dcae_cli_publish_the_component_and_data_format:

Publish the component and data_format
-------------------------------------

Once a component has been tested, it (and the data_format(s)) should be
published in the onboarding catalog using the ``publish`` sub-command
for both the ``data_format`` and ``component`` command.

**Note** Before a component can be published, all data_formats that it
references must be published.

Publishing will change the status of a component or data_format,
indicating that it has been tested, make accessible for other developers
to use.

::

    $ dcae_cli data_format publish sandbox.platform.yourapp:0.7.0
    Data format has been published

    $dcae_cli component publish sandbox.platform.yourapp:0.7.0
    Component has been published

--------------

List the catalog contents
-------------------------

::

    $dcae_cli catalog list

    $ dcae_cli data_format list | grep sandbox
    | sandbox.platform.yourapp         | 0.7.0   | docker | Web service used as a stand-alone test DCAE service compone..      | user12    | published | 2017-11-13 |
    | sandbox.platform.yourapp.health            | 0.1.0  | Data format used for the /health endpoint                          | published | 2017-11-13 17:48:10.121588 |
    | sandbox.platform.any                       | 0.1.0  | Data format used when no data format is required.                  | published | 2017-11-13 17:47:51.622607 |
    | sandbox.platform.yourapp.identity.response | 0.1.0  | Data format used for the /identity endpoint response which should  | published | 2017-11-13 17:47:43.234715 |
    | sandbox.platform.yourapp.identity.request  | 0.1.0  | Data format used for the /identity endpoint request. This is       | published | 2017-11-13 17:47:36.693643 |
    | sandbox.platform.yourapp.rollcall.response | 0.1.0  | Data format used for the /rollcall endpoint respon..               | published | 2017-11-13 17:46:30.026846 |