datarouter-prov-client/README.md

   1 <!---
   2  ============LICENSE_START===============================================
   3  org.onap.dmaap
   4  ========================================================================
   5  Copyright (c) 2023 J. F. Lucas. All rights reserved.
   6  ========================================================================
   7  Licensed under the Apache License, Version 2.0 (the "License");
   8  you may not use this file except in compliance with the License.
   9  You may obtain a copy of the License at
  10
  11         http://www.apache.org/licenses/LICENSE-2.0
  12
  13  Unless required by applicable law or agreed to in writing, software
  14  distributed under the License is distributed on an "AS IS" BASIS,
  15  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  See the License for the specific language governing permissions and
  17  limitations under the License.
  18  ============LICENSE_END=================================================
  19 --->
  20 # Data Router provisioning client
  21
  22 ## Overview
  23 The Data Router (DR) provisioning client runs as a Kubernetes initContainer for ONAP DCAE applications that use DR feeds to
  24 transfer data between applications.   The logic for the client is contained in a script that makes requests to the DR provisioning
  25 node using the DR provisioning API.  (See the [API documentation](https://docs.onap.org/projects/onap-dmaap-datarouter/en/london/apis/data-router-api.html#dmaap-data-router-api) for details.)
  26
  27 The DR provisioning client (drprov-client) replaces the DMaaP Bus Controller client (dbc-client).  The dbc-client used the DMaaP Bus Controller to
  28 provision data router feeds and subscribers and DMaaP Message Router topics and clients.  The Message Router provisioning functionality
  29 is no longer needed, and Bus Controller will be deprecated and removed from the ONAP tree.
  30
  31 The provisioning logic is in the [drprov-client.sh script](./misc/drprov-client.sh).  This script is set as the entrypoint for the initContainer.
  32
  33 The drprov-client performs two high-level tasks:
  34
  35 - Makes requests to the DR provisioning API to create feeds and subscriptions and captures the API's responses.
  36 - Uses the API's response to update a component's configuration file by replacing placeholders in the file (in the form of environment variable names) with values from the API responses.
  37
  38 The drprov-client script queries the DR provisioning API to determine if a feed already exists (based on the feed name and feed version) and does not attempt to create the feed again.  Instead, it retrieves the feed information for the existing feed and supplies that information to a component.
  39
  40 Similarly, the drprov-client script queries the DR provisioning API to determine if a subscription already exists (based on the username, password, and delivery URL for the subscription).  If one exists, the script does not create a new subscription.
  41
  42 ## Usage
  43 DR has been used only by components in the DCAE project.
  44   The [DCAE common
  45 Helm templates](https://git.onap.org/oom/tree/kubernetes/dcaegen2-services/common/dcaegen2-services-common/templates) create the files need by the drprov-client to make API requests to the DR provisioning server.  They also insert the drprov-client initContainer into the Kubernetes deployment spec for an application that uses DR feeds.  The DCAE common templates rely on the [common DMaaP provisioning template](https://git.onap.org/oom/tree/kubernetes/common/common/templates/_dmaapProvisioning.tpl).
  46
  47  The developer of a DCAE component that uses DR simply adds a section to the component's `values.yaml` file.  For details on how feeds and subscriptions are defined in a component's `values.yaml` file, see the [inline documentation for the common DMaaP provisioning template](https://git.onap.org/oom/tree/kubernetes/common/common/templates/_dmaapProvisioning.tpl).
  48
  49 ## Changes from dbc-client
  50 The DMaaP bus controller provided a unified API that supported provisioning for both DR and the DMaaP Message Router.   The bus controller was
  51 a Java program with its own database, and it shielded its clients from some of the details of the DR provisioning interface.   The drprov-client interacts
  52 directly with the DR provisioning API, and there are some changes in how it behaves and how components that use DR are configured via their values.yaml files.
  53
  54 ### What happened to publishers?
  55 DR does not have a concept of a publisher that's distinct from a feed.  Every feed has at least one "endpoint", a username/password pair that an
  56 application will supply via HTTP Basic Authentication when publishing a file.  The bus controller always created an endpoint (with random username
  57 and password) when a client requested creation of a feed.  The bus controller then allowed clients to request creation of a "publisher".  The bus
  58 controller implemented this by using the DR API's updating capability (via an HTTP PUT request) to add an endpoint to the feed.   It would have been
  59 possible to replicate this functionality in a script, but it would have added complexity.  The one current use case employing DR feeds does not require this capability.   Note that it's still possible
  60 to have multiple applications (or multiple instances of the same application) publishing to a DR feed.  They just have to use the same username and
  61 password that was provided when the feed was first created.
  62
  63 This change implies two changes for the values.yaml files of DR clients:
  64   - A client that publishes to DR creates a feed that includes an endpoint.  It no longer creates a separate publisher.
  65   - A client that subscribes to a feed does not need to supply a definition for the feed.  The subscription definition
  66    includes the feed name and feed version, and that's enough information to allow the drprov-client to associate the
  67    subscription with the feed.
  68
  69 A client that subscribes to a feed needs to include the publisher in its readiness check, so that the feed is set up before the subscriber provisioning runs.  (This is already the case for the one existing DR subscriber in ONAP.)
  70
  71 ### Location
  72 The bus controller also had a notion of "location" which has no corresponding notion in DR, so references to "dcaeLocation" in the provisioning data are no longer needed.
  73
  74 ### Owner
  75 The bus controller interface included a field called "owner" for a feed.  This may have had some function within the bus controller.  It had a minor effect on the bus controller's invocation of the DR provisioning API (setting the `X-DMAAP-DR-ON-BEHALF-OF` header in the API requests associated with the feed).  It adds no real value.  Maintaining it would add complexity to the drprov-client script and would complicate debugging DR provisioning issues.
  76
  77 Note that the drprov-client.sh script uses "drprovcl" by default as the value in the `X-DMAAP-DR-ON-BEHALF-OF`.  This can be overriden by setting the environment
  78 variable `ONBEHALFHDR` in the [common DMaaP provisioning template](https://git.onap.org/oom/tree/kubernetes/common/common/templates/_dmaapProvisioning.tpl).
  79
  80 `X-DMAAP-DR-ON-BEHALF-OF` forms the basis of a simple authorization mechanism used by the DR provisioning API.  The value passed in this header when creating a
  81 feed or a subscription is stored by the DR provisioning server.  When the DR API receives a request to retrieve the data for a specific feed or a specific subscription, the API checks that the value in the `X-DMAAP-DR-ON-BEHALF-OF` header in the incoming request matches the stored value for the target feed or subscription.   Sometimes during testing or debugging, it is useful to query the DR provisioning API about a specific feed or subscription using a tool like `curl`.  Using `X-DMAAP-DR-ON-BEHALF-OF: drprovcl` will allow access to the feeds and subscription created by the drprov-client.sh script.
  82
  83 ### Classification
  84 The bus controller interface included a field called "asprClassification" for a feed.  The field is required by DR and indicates the sensitivity of the information transmitted in a feed.  This has not been used in ONAP, but it is a required field. "aspr" is an internal acronym at the company where DR was originally developed. The field has been renamed "classification".  "unclassified" is a reasonable value to use in ONAP.
  85
  86 ### One initContainer instead of two
  87 Using the dbc-client involved running two initContainers.  The first made API requests to the bus controller API and stored the responses in a volume on the pod.  The second used the stored data to update the component's configuration using
  88 information returned by the API calls.  The drprov-client runs in a single initContainer that makes the API calls and updates the component's configuration.
  89
  90 ## Limitations
  91
  92 The drprov-client targets a limited range of uses for DR within ONAP.  It is not a general purpose provisioning solution for DR.  The following is a summary of some of the important limitations:
  93
  94   - A pod running a subscriber to a feed must wait for the feed's publisher to become ready, to ensure that the feed has been created.
  95   - While multiple applications (or multiple instances of the same application) can publish to the same feed, they must use the same username and password.
  96   - Feeds and subscriptions are not known to Kubernetes or Helm, so that deleting a publisher or a subscriber via Kubernetes or Helm does not delete the corresponding feeds or subscriptions in DR.  The drprov-client handles the case of a pod being restarted by reusing an existing feed or subscription.
  97
  98 DR was originally designed to move large files to multiple destinations over a wide geographic area.  While it clearly works for large file transfers within a Kubernetes cluster, it isn't optimal.  Currently (as of the Montreal release of ONAP), DR is used by two components ([the DCAE datafile collector](https://git.onap.org/dcaegen2/collectors/datafile/tree/), which publishes performance management data to a DR feed), and [the DCAE pm-mapper](https://git.onap.org/dcaegen2/services/pm-mapper/tree/), which subscribes to the same feed.  If new use cases requiring large file transfer emerge in the future, it would be wise to look at transfer mechanisms designed specifically for the Kubernetes environment.