readme.md

   1 # OpenECOMP MSO
   2
   3 ---
   4 ---
   5
   6 # Introduction
   7
   8 OpenECOMP MSO is delivered with **2 Docker containers**, 1 hosting the **database** (MariaDB) and 1 hosting the **JBoss** application server running all OpenECOMP MSO code.
   9
  10 Both containers runs on the same machine and can be started with a **`docker-compose`**.
  11
  12 # Compiling MSO
  13
  14 MSO can be compiled easily with a `mvn clean install`. Integration tests are started with the following profile
  15 `-P with-integration-tests`
  16
  17 **to be edited for rrelease**
  18 Docker containers are build with the following profile
  19 `-P docker -Ddocker.buildArg.chef_repo_branch_name=bugfix/external_adress -Ddocker.buildArg.chef_repo_git_username=git -Ddocker.buildArg.chef_repo_address=23.253.149.175/mso -Ddocker.buildArg.chef_repo_git_name=chef-repo`
  20
  21 # Getting the containers
  22
  23 ***to be changed for rrelease*** OpenECOMP MSO containers are stored on the Rackspace Nexus Docker Registry
  24
  25 The following Docker images are the actual deployment images used for running MSO
  26
  27 | Name            | Tag     | Description                                                                                                                   |
  28 |-----------------|---------|-------------------------------------------------------------------------------------------------------------------------------|
  29 | ecomp/mso       | 1.0.0   | Contains **JBoss** + **OpenJDK** + **MSO** components (BPMN engine and MSO API handlers and adapters)                         |
  30 | library/mariadb | 10.1.11 | **MariaDB** image from Docker.io, this image hosts the database and is preloaded with MSO schema and configuration at startup |
  31
  32 # Starting MSO
  33
  34 There are several ways to start OpenECOMP MSO :
  35
  36 ### Trough the sample Jenkins Job on the Deployment Jenkins host ***to be changed for rrelease***
  37
  38 A Jenkins instance is available at [Deployment-Jenkins](http://162.242.237.52:8080/login?from=%2F). It provides **job that can run** the containers on a sample host. ***add job link for rrelease**
  39
  40 *** for rrelease all this should go in the job description***
  41 ```
  42 The VM is running a Docker Engine (1.12) and has the Nexus repository certificate imported, Jenkins will use this host to deploy and run the containers.
  43
  44 It will first **clone** the configuration repository to its local workspace, **transfer needed configuration files**, mount a specific **docker volume** with these files and start up the containers (attached to this volume) so that they can run the startup scripts that is embedded and run openecomp MSO and its database container.
  45
  46 It is important to understand that the Docker containers are using a configuration file (JSON) in order to provision MSO basic configuration, in the above Jenkins Job, Jenkins pulls that JSON file from the MSO repository, any other mean to provide that JSON file (for specific environments) would also work. ***add link on rrelease***more information about configuring MSO.
  47 Note : the above is just an automation of the container deployment on a sample host, it is perfectly possible to do exactly the same on any host (be it your laptop or any other host that can run Docker 1.12 and reach the Nexus repository, and optionally the MSO gitlab repo to download other configurations)
  48 ```
  49
  50 The database is preloaded with all the basic configuration, it is possible to change the configuration without deploying the containers again (or rebuilding them)
  51
  52 ***provide a link on rrelease***
  53 To get a feel of how the deployment is actually performed, it is best to review the Docker Strategy of MSO and look at the actual Jenkins Job
  54
  55 ### Trough the use of `docker-compose` ***to be changed for rrelease***
  56
  57 `docker-compose` can be used to start MSO. The files can be downloaded from the Nexus repository <add-link-to-Docker-Compose>
  58
  59 ***to be changed for rrelease**
  60
  61 This job ***add link*** has been created to run the compose file.
  62
  63 ***this info will go in the job description ?***
  64 ```
  65 It job uses the Sample Docker Host described above as a Jenkins Slave (so when the build is triggered on Jenkins, it runs locally on the remote Docker Host). It pulls the needed information from MSO Git lab repository (deploy.sh and `docker-compose` file)
  66 ```
  67
  68 ### Heat template
  69
  70 a Heat template that can be used on RackSpace to spin up the MSO Host VM and run docker-compose is currently being built by the Demo Team.
  71
  72 # Accessing MSO
  73
  74 MSO UIs are not really used for operating MSO, but they provide information on what is currently happening and get an insight on the components.
  75
  76 ### MSO JBoss console
  77
  78 JBoss Wildly provides administrative functions through the application [server console](https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-Accessingthewebconsole].
  79
  80 Said console can be used to have a look at the status of MSO. It is providing details on deployed artifacts and gives a remote access to the main server log file
  81
  82 ***to be changed for the rrelease*** The UI can be accessed trough http://containerHostName:9990/ or on the sample host below : http://104.130.172.123:52090 (the sample host has port 9990 remapped to 52090 on the Rackspace VM)
  83
  84 The configuration preloads a default user (admin) with the standard OpenECOMP UI password ***provide link on rrelease***.
  85
  86 The configuration of JBoss should not be touched. But it is possible to look at the two following sections for insights on the MSO health :
  87
  88 ![deployments or runtime](http://img11.hostingpics.net/pics/332403image2016112412225.png)
  89
  90 Deployments shows what is deployed and running on the application server, you should see the following once MSO is up and running (Actual names of the War files may differ but their numbers and general format should be the same)
  91
  92 ***to be upload when rrelease***
  93
  94 Runtime can be used to have a look a the main server log files, see JVM status and parameters, environment settings etc,...
  95
  96 ![runtime monitor](http://img11.hostingpics.net/pics/244948image20161124123216.png)
  97
  98 See the logging section below for more details about other logfiles (EELF framework)
  99
 100 ### MSO Camunda Cockpit console
 101
 102 MSO orchestration processes can be monitored with the [Camunda Engine cockpit UI](https://camunda.org/features/cockpit/). It gives an insight about the available processes, allows to trigger them manually and provides monitoring of the currently running processes
 103
 104 **IMPORTANT NOTE** : since OpenECOMP MSO only uses Camunda Community version it is not possible to see history of running process as this is an Enterprise feature only.
 105
 106 #### Accessing the Cockpit
 107
 108 ***to be changed for the rrelease*** The cockpit is available at the following address : http://containerHostname:8080/cockpit or on the Sample host below http://104.130.172.123:52080/cockpit (the sample host has port 8080 remapped to 52080 on the Rackspace VM)
 109
 110 When the container is started, as it starts up from a fresh instance, it will create a default admin user (admin) with the default OpenECOMP password for UI***provide link on rrelease***
 111
 112 The cockpit gives an overview of the available BPMN (orchestration) processes (with a visual representation), it is also possible to trigger them from the UI if you know the parameters that are needed.
 113
 114 ***screenshots to be uploaded when rrelease***
 115
 116 ### MSO APIs
 117
 118 Most of the MSO features within OpenECOMP are triggered by using **RESTful interfaces**. MSO supports both **HTTP** and **HTTPS**, but is configured on this release with HTTP only using Basic Authentification.
 119
 120 The MSO APIs are configured to accept requests having a **basic auth. header** set with various **username and password** depending on which API is being triggered.
 121
 122 All API endpoints are exposed on port **8080**, it is possible to reach all MSO subsystems directly with the proper query (see more information below on how to test MSO functions)
 123
 124 ##### Main API endpoints in the first open source release
 125
 126 - ***to be completed*** APIHandler health checks
 127 - ***to be completed*** VID API
 128
 129 VID endpoint : http://vm1.mso.simpledemo.openecomp.org:8080/ecomp/mso/infra/serviceInstances/v2
 130
 131 The typical easy way to trigger these endpoints is to use a RESTful client or automation framework.
 132
 133 # Configuration of MSO
 134
 135 It is important to understand that the Docker containers are using a configuration file (JSON) in order to provision MSO basic configuration, in the above Jenkins Job, Jenkins pulls that JSON file from the MSO repository, any other mean to provide that JSON file (for specific environments) would also work.
 136
 137 Once the deployment of the docker images is done, you will need to configure your installation to be able to interact with all the components that MSO needs.
 138
 139 Change the environment file located here : **/shared/mso-docker.json** then run the following command `chef-solo -c /var/berks-cookbooks/chef-repo/solo.rb -o recipe[mso-config::apih],recipe[mso-config::bpmn],recipe[mso-config::jra]`
 140
 141 **Important note:** The host mso is mapped automatically to c1.vm1.mso.simpledemo.openecomp.org in /etc/host of the docker image so you can keep mso:8080 when you want to mention the APIH, JRA or Camunda host.
 142
 143 Here are the main parameters you could change:
 144
 145 - mso_config_path: define the path where the configuration files for APIH, JRA and Camunda will be deployed. This parameter should not be changed.
 146 - In the section mso-bpmn-urn-config, adaptersDbEndpoint: This configuration must point to the APIH hostname. It should have this form: http://mso:8080/dbadapters/RequestsDbAdapter Do not change it if you are not sure.
 147 - In the section mso-bpmn-urn-config, aaiEndpoint: This parameter should point to the A&AI component. It should be something like: https://c1.vm1.aai.simpledemo.openecomp.org:8443
 148 - In the section mso-bpmn-urn-config, aaiAuth: This parameter is the encrypted value of login:password to access the A&AI server. The key used to encrypt is defined in the parameter msoKey.
 149 - In the section asdc-connection, asdcAddresss: Change the values with the value provided by the ASDC team. Possible value: https://c2.vm1.asdc.simpledemo.openecomp.org:8443 The password field may be changed as well.
 150 - In the section mso-sdnc-adapter-config, sdncurls: Change all the values with the value provided by the SDNC team. Possible value: https://c1.vm1.sdnc.simpledemo.openecomp.org:8443/... ? The sdncauth field may be changed as well.
 151 - In the section mso-appc-adapter-config, appc_url: Change the value with the value provided by the APPC team. Possible value: http://c1.vm1.appc.simpledemo.openecomp.org:8080 ? The appc_auth field may be changed as well.
 152 - In the section mso-po-adapter-config, identity_url: Change the values with the value provided by the PO team. Possible value: https://identity.api.rackspacecloud.com/v2.0 ?
 153
 154 The credentials are defined in 2 places:
 155
 156 - JBoss users credentials are defined in /opt/jboss/standalone/configuration/application-users.properties and are associated to the corresponding role in application-roles.properties (you should not change this file except if you add a new user)
 157 - In the environment. Replace the authorisation key in the file /shared/mso-docker.json and run the command to apply the configuration as explained above.
 158
 159 You can encrypt the JBoss user with the following command `echo -n 'LOGIN:ApplicationRealm:PASSWORD' |openssl dgst -md5` and replace the line corresponding to this user in /opt/jboss/standalone/configuration/application-users.properties
 160
 161 You can replace the authentication in the environment by the value returned by the following API `GET on http://c1.vm1.mso.simpledemo.openecomp.org:8080/asdc/properties/encrypt/{value}/{cryptKey}` where {value} is the string login:password and cryptKey (also defined in the environment) is the key to use to encrypt the credentials
 162
 163 Exemple of credentials you could change:
 164 - BPELClient: if you change this credentials, you have to change it in JBoss users AND environment file (+ apply the new config) and be careful to set the same password. In the environment it is the parameter "adaptersPoAuth" under the section "mso-bpmn-urn-config". The cryptKey to use is 07a7159d3bf51a0e53be7a8f89699be7
 165 - BPMNClient: if you change this credentials, you have to change it in JBoss users AND environment file (+ apply the new config) and be careful to set the same password. In the environment it is the parameter "camundaAuth" under the sections "mso-api-handler-config" AND "mso-api-handler-infra-config". The cryptKey to use is
 166 aa3871669d893c7fb8abbcda31b88b4f
 167
 168 # Logging
 169
 170 ### JBoss
 171
 172 MSO log files are located the [JBoss log](https://docs.jboss.org/author/display/WFLY8/Logging+Configuration) folder in the container.
 173
 174 ### EELF
 175
 176 EELF framework is used for **specific logs** (audit, metric and error logs). They are tracking inter component logs (request and response) and allow to follow a complete flow through the MSO subsystem
 177
 178 EELF logs are located at the following location on the MSO JBoss container :
 179
 180 - /var/log/ecomp/MSO (each module has its own folder)
 181
 182 The DEBUG mode is enabled by module and has to be re-enabled if the application restart.
 183
 184 It can be enabled with a GET on the following APIs:
 185 - Camunda (no authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/mso/logging/debug
 186 - APIH Infra (use any jboss user with role InfraPortal-Client for authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/ecomp/mso/infra/logging/debug
 187 - ASDC (no authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/asdc/logging/debug
 188 - DBAdapter (no authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/dbadapters/logging/debug
 189 - Network adapter (no authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/networks/rest/logging/debug
 190 - SDNC adapter (use any jboss user with role MSO-Client for authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/adapters/rest/logging/debug
 191 - VNF adapter (no authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/vnfs/rest/logging/debug
 192 - Tenant adapter (no authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/tenants/rest/logging/debug
 193 - APPC adapter (no authentication): http://c1.vm1.mso.simpledemo.openecomp.org:8080/appc/rest/logging/debug
 194
 195 Default JBoss users:
 196 - with role CSI-Client: CSIClient/password1$
 197 - with role CSI-Client: InfraPortalClient/password1$
 198 - with role CSI-Client: MSOClient/password1$
 199
 200 Note that these default users should be changed.
 201
 202 # Testing MSO Functionalities
 203
 204 For this first release of MSO, the queries to start the various VNFs should come first through API Handler.
 205
 206 To help with the testing we are providing here a sample [SoapUI](https://www.soapui.org/) project [file](add link when rrealease) with the main queries that VID should send to MSO
 207
 208 ### To simulate Loading of Artifacts & models (bypass ASDC)i
 209
 210 The MariaDB container can load up special SQL scripts that simulates the loading of ASDC components (as if they were received through the ASDC client)
 211
 212 Simply use the load ability embedded to run the 'preload SQL' script for vFirewall or vDNS
 213
 214 ### Once the HEAT artifacts are loaded into MSO
 215
 216 It is also possible to simulate queries to the PO (platform orchestrator) adapter of MSO (thus bypassing BPMN flows and API handler) to verify MSO interaction with Rackspace and verify the behavior of the Adapter (so that it loads HEAT and connect to Rackspace and instantiate elements)
 217
 218 Below is a query used from FireFox RESTClient plugin to trigger MSO adapter directly (replace values accordingly)
 219
 220 ```
 221  POST http://<containername>:8080/vnfs/rest/v1/vnfs/5259ba4a-cf0d-4791-9c60-9117faa5cdea/vf-modules
 222 Header: content-type: application/json
 223 +Authorization
 224 login/password BPELClient/password1$F
 225
 226  {"createVfModuleRequest":{"messageId":"ec9537bb-c837-477f-86a5-21c717be96f1-1479156376597","skipAAI":true,"notificationUrl":"http://msobpel-app-st.ecomp.cci.att.com:8080/mso/vnfAdapterRestNotify","cloudSiteId":"RACKSPACE","tenantId":"1015548","vnfId":"5259ba4a-cf0d-4791-9c60-9117faa5cdea","vnfType":"vfw-service/VFWResource-1","vnfVersion":"1.0","vfModuleId":"7d8412bb-b288-44ff-92ef-723018f940fc","vfModuleName":"MSO_VFW_TEST","vfModuleType":"VF_RI1_VFW::module-1","volumeGroupId":"","volumeGroupStackId":"","baseVfModuleId":"","baseVfModuleStackId":"","requestType":"","failIfExists":true,"backout":true,"vfModuleParams":{"vf_module_name":"MSO_VFW_TEST","vnf_name":"vfw-service/VFWResource-1","vnf_id":"5259ba4a-cf0d-4791-9c60-9117faa5cdea","vf_module_id":"7d8412bb-b288-44ff-92ef-723018f940fc"},"msoRequest":{"requestId":"ec9537bb-c837-477f-86a5-21c717be96f1","serviceInstanceId":"369cdf85-1b61-41ff-b637-c6b7dd020326"},"synchronous":false}}
 227 ```
 228
 229 # Getting Help
 230
 231 *** to be completed on rrelease ***
 232
 233 mso@lists.openecomp.org
 234
 235 MSO Javadoc and Maven site
 236
 237 *** to be completed on rrelease ***
 238