README.md

   1
   2 #
   3 # ============LICENSE_START==========================================
   4 # org.onap.dmaap
   5 # ===================================================================
   6 # Copyright © 2018 AT&T Intellectual Property. All rights reserved.
   7 # ===================================================================
   8 # Licensed under the Apache License, Version 2.0 (the "License");
   9 # you may not use this file except in compliance with the License.
  10 # You may obtain a copy of the License at
  11 #
  12 #        http://www.apache.org/licenses/LICENSE-2.0
  13 #
  14 # Unless required by applicable law or agreed to in writing, software
  15 # distributed under the License is distributed on an "AS IS" BASIS,
  16 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17 # See the License for the specific language governing permissions and
  18 # limitations under the License.
  19 # ============LICENSE_END============================================
  20 # ECOMP is a trademark and service mark of AT&T Intellectual Property.
  21 #
  22 #
  23
  24 DMaaP Bus Controller API
  25 =======================
  26
  27 Data Movement as a Platform (DMaaP) Bus Controller provides an API for other ONAP infrastructure components to provision DMaaP resources.
  28 A typical DMaaP resource is a Data Router Feed or a Message Router Topic, and their associated publishers and subscribers.
  29 Other infrastucture resources such as DR Nodes and MR Clusters are also provisioned through this API.
  30
  31 ### Sub-components
  32
  33 This project produces the following mvn modules in their respective sub-directories:
  34 - dmaap-bc is a docker image intended to be used to instantiate the DMaaP Bus Controller container
  35 - dbc-client is a docker image intended to serve as a temporary http client of the Bus Controller API.  It will be instantiated in a container that is a Helm hook (e.g. post-install hook) that knows how to invoke the Bus Controller API.
  36
  37 ### Build Instructions for a Continuous Integration environment using Jenkins
  38
  39 When this component is included in a Continuous Integration environment, such as structured by the Linux Foundation, the artifacts can be created and deployed via Jenkins.  The following maven targets are currently supported in the Build step:
  40 ```
  41 clean install
  42 ```
  43
  44
  45 ### Build Instructions for external developers
  46
  47 This project is organized as a mvn project for a docker image.
  48 After cloning from this git repo:
  49
  50 ```
  51 mvn clean install
  52 ```
  53
  54
  55 ### Docker Packaging
  56
  57 We can utilize docker to build and register the buscontroller container in a local dev repository.
  58 Note the Dockerfile follows ONAP convention of running app as root.
  59
  60 ```
  61
  62 <assuming DOCKER_HOST is set appropriately for your environment>
  63
  64 $ mvn -P docker docker:build
  65 ```
  66
  67
  68 ### ONAP deployment
  69
  70 Two styles of deployment are supported for ONAP.
  71 1. OOM - by the time of Release Casablanca, this is the preferred deployment method which relies on a kubernetes environment, and uses helm charts.  Buscontroller is part of a larger overall dmaap chart which also deploys Message Router and Data Router.  See https://gerrit.onap.org/r/#/admin/projects/oom
  72 2. HEAT - an older style deployment which assumes VM running docker.
  73
  74 #### ONAP OOM Deployment
  75
  76 The default DMaaP charts for an OOM deployment should be able to be used without modification because the interdependencies between components rely on kubernetes service names.
  77 However, overrides can be made to the buscontroller values.yaml file (found in oom/kubernetes/dmaap/charts/dmaap-bus-controller/values.yaml) as needed.
  78
  79 Following a convention where Release is set to the component name (--name=dmaap) and using a dev namespace:
  80 ```
  81 <clone oom>
  82 cd kubernetes
  83 <edit values.yaml if necessary>
  84 make dmaap
  85 helm install dmaap --debug --name=dmaap --namespace=dev
  86
  87 ```
  88
  89 #### ONAP Heat deployment
  90 Prior to starting container, place environment specific vars in /tmp/docker-databus-controller.conf on the Docker host,
  91 and map that file to /opt/app/config/conf.
  92 Run the buscontroller image which starts execution of the dmaapbc deploy command, which will update the container runtime properties appropriately, and start the Bus Controller.
  93
  94 For example, in ONAP Future Lab environment, /tmp/docker-databus-controller.conf looks like:
  95 ```
  96
  97 # DMaaP Bus Controller OpenSource environment vars
  98 CONT_DOMAIN=demo.dmaap.onap.org
  99 DMAAPBC_INSTANCE_NAME=ONAPfuture
 100
 101 #   The https port
 102 #   set to 0 if certificate is not ready
 103 DMAAPBC_INT_HTTPS_PORT=0
 104
 105 DMAAPBC_KSTOREFILE=/opt/app/dcae-certificates
 106 DMAAPBC_KSTOREPASS=foofoofoo
 107 DMAAPBC_PVTKEYPASS=barbarbar
 108
 109 DMAAPBC_PG_ENABLED=true
 110 DMAAPBC_PGHOST=zldciad1vipstg00.simpledemo.openecomp.org
 111 DMAAPBC_PGCRED=test234-ftl
 112
 113 DMAAPBC_DRPROV_FQDN=zldciad1vidrps00.simpledemo.openecomp.org
 114
 115 DMAAPBC_AAF_URL=https://aafapi.${CONT_DOMAIN}:8095/proxy/
 116
 117 DMAAPBC_TOPICMGR_USER=m99751@dmaapBC.openecomp.org
 118 DMAAPBC_TOPICMGR_PWD=enc:zyRL9zbI0py3rJAjMS0dFOnYfEw_mJhO
 119 DMAAPBC_ADMIN_USER=m99501@dcae.openecomp.org
 120 DMAAPBC_ADMIN_PWD=enc:YEaHwOJrwhDY8a6usetlhbB9mEjUq9m
 121
 122 DMAAPBC_PE_ENABLED=false
 123 DMAAPBC_PE_AAF_ENV=TBD
 124 ```
 125 Then the following steps could be used to pull and run the Bus Controller.  (onap-nexus is just an example)
 126 ```
 127 $
 128 $ docker pull nexus3.onap.org:10003/onap/dmaap/dmaap-bc:latest
 129 $ docker run -d -p 18080:8080 -p 18443:8443 -v /tmp/docker-databus-controller.conf:/opt/app/config/conf nexus3.onap.org:10003/onap/dmaap/dmaap-bc:latest
 130 ```
 131
 132 ### Properties
 133
 134 This section is intended to describe the behavior customization of Bus Controller that can be obtained via properties file used by the dbcapi library.
 135 By default, this file is located in etc/dmaapbc.properties.
 136 However, a java argument -DConfigFile  can be set to a different path.  (Our kubernetes deployment relies on this and points to a configmap, for example.)
 137
 138 The table below lists all the settings, default values (if not set), and shows any explicit setting in ONAP oom kubernetes deployment.
 139
 140 |-|-|-|-|
 141 | Property | Description | Default | ONAP Kubernetes Setting |
 142 |-|-|-|-|
 143 |UseAAF                | Flag for whether AAF authz API is to be used            | false                                  | false |
 144 |-|-|-|-|
 145 |csit                  | Flag for stubbing out many southbound calls in a CSIT environment | No                           | No |
 146 |-|-|-|-|
 147 |DR.provhost           | FQDN of Data Router Provisioning Server (deprecated - now set via API) | notSet                  | dcae-drps.domain.not.set |
 148 |-|-|-|-|
 149 |ProvisioningURI       | URI to retrieve dynamic DR configuration                | /internal/prov                         | /internal/prov |
 150 |-|-|-|-|
 151 |Feed.deleteHandling   | indicator for handling feed delete request              | DeleteOnDR                             | SimulateDelete |
 152 |                      | DeleteOnDR - means use the DR API to DELETE a feed.  (default for backwards compatibility) | | |
 153 |                      | SimulateDelete - means preserve the feed on DR (after cleaning it up), and mark as DELETED in DBCL. | | |
 154 |-|-|-|-|
 155 |UsePGSQL              | flag indicates whether to retain data in Postgresql     | false                                  | true |
 156 |                      | when false, objects will be kept in memory but will be  |                                        | |
 157 |                      | lost on restart and not shared between instances        |                                        | |
 158 |-|-|-|-|
 159 |DB.host               | FQDN or service name of Postresql host                  | dcae-pstg-write-ftl.domain.notset.com  | dbc-pg-primary |
 160 |-|-|-|-|
 161 |DB.name               | name of Postresql database                              | dmaap                                  | |
 162 |-|-|-|-|
 163 |DB.schema             | name of database schema                                 | public                                 | |
 164 |-|-|-|-|
 165 |DB.user               | username for Postgresql access                          | dmaap_admin                            | |
 166 |-|-|-|-|
 167 |DB.cred               | password for Postrgresql access                         | test234-ftl                            | onapdemodb |
 168 |-|-|-|-|
 169 |MR.multisite          | Indicates if there can be multiple sites (locations) where MR is deployed | true                 | false |
 170 |-|-|-|-|
 171 |MR.CentralCname       |  FQDN or service name of MR (deployed in central if multilocation is true) | MRcname.not.set     | message-router |
 172 |-|-|-|-|
 173 |MR ClientDeleteLevel  | MR Client Delete thoroughness                           | 0                                      |  1 |
 174 |                      | 0 = don't delete | | |
 175 |                      | 1 = delete from persistent store (PG) | | |
 176 |                      | 2 = delete from persistent store (PG) and authorization store (AAF) | | |
 177 |-|-|-|-|
 178 |MR.TopicFactoryNS     | AAF namespace used to create perms for MR topics        | MR.topicFactoryNS.not.set              | org.onap.dmaap.mr.topicFactory |
 179 |-|-|-|-|
 180 |MR.TopicMgrRole       | AAF Role used by Buscontroller to create topics on MR   | MR.TopicMgrRole.not.set                | org.onap.dmaap-bc-topic-mgr.client |
 181 |-|-|-|-|
 182 |MR.projectID          | Value for some constructs of fully qualified topic names | 99999                                 | ONAP |
 183 |-|-|-|-|
 184 |cadi.properties       | Path to CADI properties file                            | /opt/app/osaaf/local/org.onap.dmaap-bc.props | /opt/app/osaaf/lcoal/org.onap.dmaap-bc.props |
 185 |-|-|-|-|
 186 |aaf.URL               | URL of the AAF server                                   | https://authentication.domain.netset.com:8095/proxy/ | https://aaf-authz/ |
 187 |-|-|-|-|
 188 |aaf.TopicMgrUser      | AAF Identity of Topic Mgr                               | noMechId@domain.netset.com             | dmaap-bc-topic-mgr@dmaap-bc-topic-mgr.onap.org |
 189 |-|-|-|-|
 190 |aaf.TopicMgrPassword  | AAF Credential for Topic Mgr                            | notSet                                 | demo123456! |
 191 |-|-|-|-|
 192 |aaf.AdminUser         | AAF Identity of user with Admin role for API namespace  | noMechId@domain.netset.com             | aaf_admin@people.osaaf.org |
 193 |-|-|-|-|
 194 |aaf.AdminPassword     | AAF credential of AdminUser                             | notSet                                 | demo123456! |
 195 |-|-|-|-|
 196 |aaf.NsOwnerIdentity     | AAF Identity to be used as topic Namespace owner      | notSet                                 | aaf_admin@people.osaaf.org |
 197 |topicNsRoot           | AAF namespace value used to create FQTN                 | org.onap.dcae.dmaap                    | org.onap.dcae.dmaap |
 198 |-|-|-|-|
 199 |CredentialCodeKeyfile | location of the codec keyfile used to decrypt passwords | LocalKey                               | etc/LocalKey |
 200 |                      | in this properties file before they are passed to AAF   | LocalKey                               | etc/LocalKey |
 201 |-|-|-|-|
 202 |AafDecryption.Class   | Specifies the Class to be used for decryption           | org.onap.dmaap.dbcapi.aaf.ClearDecrypt | |
 203 |-|-|-|-|
 204 |ApiNamespace          | Root namespace for AAF perms related to dbcapi access   | apiNamespace.not.set                   | org.onap.dmaap-bc.api |
 205 |-|-|-|-|
 206 |ApiPermission.Class   | the Class that determines if a call to API is authorized| allow                                  | |
 207 |-|-|-|-|
 208 |MM.ProvRole           | AAF Role of client publishing MM prov cmds              | notSet                                 | org.onap.dmaap-bc-mm-prov.prov |
 209 |-|-|-|-|
 210 |MM.ProvUserMechId     | AAF Identity when publishing to MM command topic        | notSet                                 | dmaap-bc-mm-prov@dmaap-bc-mm-prov.onap.org|
 211 |-|-|-|-|
 212 |MM.ProvUserPwd        | AAF credenital for ProvUserMechId                       | notSet                                 | demo123456! |
 213 |-|-|-|-|
 214 |MM.AgentRole          | AAF Role of client susbcribing to MM command topic      | notSet                                 | org.onal.dmaap-bc-mm-prov.agent |
 215 |-|-|-|-|
 216 |DR.provApi            | Version name of DR API (ONAP or AT&T)                   | ONAP                                   | ONAP |
 217 |-|-|-|-|
 218 |DR.onBehalfHeader     | String for "On Behalf Of" HTTP Header in DR API         | X-DR-ON-BEHALF-OF                      | X-DR-ON-BEHALF-OF |
 219 |-|-|-|-|
 220 |DR.feedContentType    | Value for Content-Type Header in DR Feed API            | application/vnd.dr.feed                | application/vnd.dr.feed |
 221 |-|-|-|-|
 222 |DR subContentType     | Value for Content-Type Header in DR Subscription API    | application/vnd.dr.subscription        | application/vnd.dr.subscription |
 223 |-|-|-|-|
 224 |HttpAllowed           | flag indicating whether http is supported               | false                                  | true |
 225 |-|-|-|-|
 226 |IntHttpPort           | Internal port for http service                          | 80                                     | 8080 |
 227 |-|-|-|-|
 228 |IntHttpsPort          | Internal port for https service (0 if no cert is avail) | 443                                    | 8443 |
 229 |-|-|-|-|
 230 |ExtHttpsPort          | Externally advertised port for https service (deprecated)| 443                                   | 443 |
 231 |-|-|-|-|
 232 |KeyStoreType          | Format of Java keystore                                 | jks                                    | jks |
 233 |-|-|-|-|
 234 |KeyStoreFile          | Path to java keystore                                   | etc/keystore                           | etc/keystore |
 235 |-|-|-|-|
 236 |KeyStorePassword      | Password for keystore                                   | changeit                               | <provided by Certificate Authority> |
 237 |-|-|-|-|
 238 |KeyPassword           | Password for private key in the https keystore          | changeit                               | <provided by Certificate Authority> |
 239 |-|-|-|-|
 240 |TrustStoreType        | Format of Trust Store file                              | jks                                    | jks |
 241 |-|-|-|-|
 242 |TrustStoreFile        | Path to Trust Store file                                |                                        | etc/org.onap.dmaap-bc.trust.jks |
 243 |-|-|-|-|
 244 |TrustStorePassword    | Password for Trust Store                                |                                        | <provided by Certificate Authority> |
 245 |-|-|-|-|
 246 |QuiesceFile           | Path to file which signals needs to queiesce            |                                        | etc/SHUTDOWN |
 247 |-|-|-|-|
 248
 249 ### Environment Variables
 250 The following environment variables can be set in the container environment to further effect behavior:
 251 - DMAAPBC_WAIT_TOEXIT=Y   when set this will attempt to keep the dmaap-bc container running.  Sometimes needed to get a better look at logs when the main proces is exiting for some reason.
 252
 253 - CONFIGMAP_ROOT defaults to /opt/app/config/conf  but can be overwritten if needed.  This value serves as the root to where the buscontroller.env file is found.
 254
 255 - CONFIGMAP_PROPS defaults to /opt/app/config/conf/dmaapbc.properties but can be overwritten if needed