From d2cd31b73c0282f7aafd5b4adada00c0f4533d61 Mon Sep 17 00:00:00 2001 From: Ralph Knag Date: Mon, 2 Apr 2018 16:27:46 -0400 Subject: Onboarding documentation update for CLI Change-Id: I1d4d0111063ea62c3759aa9b7232998b70229644 Issue-ID: DCAEGEN2-350 Signed-off-by: Ralph Knag --- .../dmaap-connection-objects.rst | 276 +++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100755 docs/sections/components/component-specification/dmaap-connection-objects.rst (limited to 'docs/sections/components/component-specification/dmaap-connection-objects.rst') diff --git a/docs/sections/components/component-specification/dmaap-connection-objects.rst b/docs/sections/components/component-specification/dmaap-connection-objects.rst new file mode 100755 index 00000000..dfd4980f --- /dev/null +++ b/docs/sections/components/component-specification/dmaap-connection-objects.rst @@ -0,0 +1,276 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _dmaap-connection-objects: + +DMaaP connection objects +======================== + +DMaaP Connection Objects are JSON objects that: + +1. At Runtime - this is generated by the DCAE Platform and passed to the + component in its application_configuration to be used to connect to + the DMaaP feed or topic. Components will receive the entire object + with all properties populated (default will be \`null) unless + specified otherwise. +2. During dcae_cli testing - this is provided through the command-line + argument ``--dmaap-file`` to test the component with manually + provisioned feeds and topics. Developers are not required to provide + the entire object. The required properties are labeled below with + “*Required as input*”. + +.. _dmaap-message-router: + +Message Router +-------------- + +Publishers and subscribers have the same generated +``Dmaap Connection Object`` structure. Here’s an example for any given +config-key: (This is what will be in application_configuration) + +.. code:: json + + { + "type": "message_router", + "aaf_username": "some-user", + "aaf_password": "some-password", + "dmaap_info": { + "client_role": "com.dcae.member", + "client_id": "1500462518108", + "location": "mtc00", + "topic_url": "https://we-are-message-router.us:3905/events/some-topic" + } + } + +At the top-level: + ++--------------------------------+---------+---------------------------+ +| Property Name | Type | Description | ++================================+=========+===========================+ +| type | string | *Required as input*. Must | +| | | be ``message_router`` for | +| | | message router topics | ++--------------------------------+---------+---------------------------+ +| aaf_username | string | AAF username message | +| | | router clients use to | +| | | authenticate with secure | +| | | topics | ++--------------------------------+---------+---------------------------+ +| aaf_password | string | AAF password message | +| | | router clients use to | +| | | authenticate with secure | +| | | topics | ++--------------------------------+---------+---------------------------+ +| dmaap_info | JSON | *Required as input*. | +| | object | Contains the topic | +| | | connection details | ++--------------------------------+---------+---------------------------+ + +The ``dmaap_info`` object contains: + ++--------------------------------+---------+---------------------------+ +| Property Name | Type | Description | ++================================+=========+===========================+ +| client_role | string | AAF client role that’s | +| | | requesting publish or | +| | | subscribe access to the | +| | | topic | ++--------------------------------+---------+---------------------------+ +| client_id | string | Client id for given AAF | +| | | client | ++--------------------------------+---------+---------------------------+ +| location | string | DCAE location for the | +| | | publisher or subscriber, | +| | | used to set up routing | ++--------------------------------+---------+---------------------------+ +| topic_url | string | *Required as input*. URL | +| | | for accessing the topic | +| | | to publish or receive | +| | | events | ++--------------------------------+---------+---------------------------+ + +The –dmaap-file argument (to the component ``run`` or ``dev`` command), +must minimally contain: + +.. code:: json + + { + "type": "message_router", + "dmaap_info": { + "topic_url": "https://we-are-message-router.us:3905/events/some-topic" + } + } + +.. _dmaap-data-router: + +Data Router +----------- + +Publisher +~~~~~~~~~ + +Here’s an example of what the generated ``Dmaap Connection Object`` for +Data Router Publisher looks like: (This is what will be in +application_configuration) + +.. code:: json + + { + "type": "data_router", + "dmaap_info": { + "location": "mtc00", + "publish_url": "https://we-are-data-router.us/feed/xyz", + "log_url": "https://we-are-data-router.us/feed/xyz/logs", + "username": "some-user", + "password": "some-password", + "publisher_id": "123456" + } + } + +At the top-level: + ++--------------------------------+---------+---------------------------+ +| Property Name | Type | Description | ++================================+=========+===========================+ +| type | string | *Required as input*. Must | +| | | be ``data_router`` for | +| | | data router feeds | ++--------------------------------+---------+---------------------------+ +| dmaap_info | JSON | *Required as input*. | +| | object | Contains the feed | +| | | connection details | ++--------------------------------+---------+---------------------------+ + +The ``dmaap_info`` object contains: + ++--------------------------------+---------+---------------------------+ +| Property Name | Type | Description | ++================================+=========+===========================+ +| location | string | DCAE location for the | +| | | publisher, used to set up | +| | | routing | ++--------------------------------+---------+---------------------------+ +| publish_url | string | *Required as input*. URL | +| | | to which the publisher | +| | | makes Data Router publish | +| | | requests | ++--------------------------------+---------+---------------------------+ +| log_url | string | URL from which log data | +| | | for the feed can be | +| | | obtained | ++--------------------------------+---------+---------------------------+ +| username | string | Username the publisher | +| | | uses to authenticate to | +| | | Data Router | ++--------------------------------+---------+---------------------------+ +| password | string | Password the publisher | +| | | uses to authenticate to | +| | | Data Router | ++--------------------------------+---------+---------------------------+ +| publisher_id | string | Publisher id in Data | +| | | Router | ++--------------------------------+---------+---------------------------+ + +The –dmaap-file argument (to the component ``run`` or ``dev`` command), +must minimally contain: + +.. code:: json + + { + "type": "data_router", + "dmaap_info": { + "publish_url": "https://we-are-data-router.us/feed/xyz" + } + } + +Subscriber +~~~~~~~~~~ + +Here’s an example of what the generated ``Dmaap Connection Object`` for +a Data Router Subscriber looks like: (This is what will be passed in +application_configuration) + +.. code:: json + + { + "type": "data_router", + "dmaap_info": { + "location": "mtc00", + "delivery_url": "https://my-subscriber-app.dcae:8080/target-path", + "username": "some-user", + "password": "some-password", + "subscriber_id": "789012" + } + } + +At the top-level: + ++--------------------------------+---------+---------------------------+ +| Property Name | Type | Description | ++================================+=========+===========================+ +| type | string | *Required as input*. Must | +| | | be ``data_router`` for | +| | | data router feeds | ++--------------------------------+---------+---------------------------+ +| dmaap_info | JSON | *Required as input*. | +| | object | Contains the feed | +| | | connection details | ++--------------------------------+---------+---------------------------+ + +The ``dmaap_info`` object contains: + ++--------------------------------+---------+---------------------------+ +| Property Name | Type | Description | ++================================+=========+===========================+ +| location | string | DCAE location for the | +| | | subscriber, used to set | +| | | up routing | ++--------------------------------+---------+---------------------------+ +| delivery_url | string | URL to which the Data | +| | | Router should deliver | +| | | files | ++--------------------------------+---------+---------------------------+ +| username | string | Username Data Router uses | +| | | to authenticate to the | +| | | subscriber when | +| | | delivering files | ++--------------------------------+---------+---------------------------+ +| password | string | Password Data Router uses | +| | | to authenticate to the | +| | | subscriber when | +| | | delivering files | ++--------------------------------+---------+---------------------------+ +| subscriber_id | string | Subscriber id in Data | +| | | Router | ++--------------------------------+---------+---------------------------+ + +The –dmaap-file argument (to the component ``run`` or ``dev`` command), +must minimally contain: + +.. code:: json + + { + "type": "data_router", + "dmaap_info": { + } + } + +It is the recommended security practice that ``username`` and +``password`` are specified. You cannot provide the ``delivery_url`` in +your dmaap-file, because it’s not constructed until deployment time. +Therefore, after the test deployment, go back to the Data Router Feed +and provide the delivery_url (in order to start receiving the feeds). + +Data Router Example +~~~~~~~~~~~~~~~~~~~ + +(After the Data Router feed has been manually provisioned) + +:: + + $ dcae_cli component run --dmaap-file $dmaap_file $component-name + DCAE.Run | WARNING | Your component is a data router subscriber. Here are the delivery urls: + + some-sub-dr: http://135.205.226.128:32838/identity + +(Update the Data Router Feed to provide the delivery_url). -- cgit 1.2.3-korg