README.md

   1 ## MUSIC - Multi-site State Coordination Service
   2
   3 To truly achieve 5 9s of availability on 3 9s or lower software and infrastructure in a cost-effective manner, ONAP components need to work in a reliable, active-active manner across multiple sites (platform-maturity resiliency level 3). A fundamental aspect of this is  state management across geo-distributed sites in a reliable, scalable, highly available and efficient manner. This is an important and challenging problem because of three fundamental reasons:
   4
   5 * Current solutions for state-management of  ONAP components like MariaDB clustering, that work very effectively within a site, may not scale across geo-distributed sites (e.g., Beijing, Amsterdam and Irvine) or allow partitioned operation (thereby compromising availability). This is mainly because WAN latencies are much higher across sites and frequent network partitions can occur.
   6
   7 * ONAP components often have a diverse range of requirements in terms of state replication. While some components need to synchronously manage state across replicas, others may tolerate asynchronous replication. This diversity needs to be leveraged to provide better performance and higher availability across sites.
   8
   9 * ONAP components often need to partition state across different replicas, perform consistent operations on them and ensure that on failover, the new owner has access to the latest state. The distributed protocols to achieve such consistent ownership is complex and replete with corners cases, especially in the face of network partitions. Currently, each component is building its own handcrafted solution which is  wasteful and worse, can be erroneous.
  10
  11 In this project, we identify common state management concerns across ONAP components and provide a multi-site state coordination/management service (MUSIC) with a rich suite of recipes that each ONAP component can simply configure and use for their state-management needs.
  12
  13 ---
  14
  15 [Local Installation](#local-install)
  16
  17 [Multi-site Installation](#ms-install)
  18
  19 [Muting MUSIC jersey output](#jersey-mute)
  20
  21 [Authentications/AAF Setup](#auth-setup)
  22
  23
  24 Prerequisites
  25
  26 MUSIC is to be installed in a single Dir.
  27
  28 ```bash
  29 #The main MUSIC dir should be
  30 /opt/app/music
  31 # These also need to be set up
  32 /opt/app/music/etc
  33 /opt/app/music/logs
  34 ```
  35 When installing Cassandra it should also be installed here.
  36 ```bash
  37 /opt/app/music/apache-cassandra-n.n.n
  38 ```
  39 Its suggested you create links from install dirs to a common name ie:
  40 ```bash
  41 ln -s /opt/app/music/apache-cassandra-n.n.n cassandra
  42 ```
  43
  44 Cassandra has data dirs.
  45 ```bash
  46 # For cassandra it should be (This is the default)
  47 /opt/app/music/cassandra/data
  48 ```
  49
  50 If you are using a VM make sure it has at least 8 GB of RAM (It may work with 4 GB, but with 2 GB it
  51 does give issues).
  52
  53 <a name="local-install">
  54
  55 ## Local Installation
  56
  57 </a>
  58
  59 ### Instructions
  60
  61 - Create MUSIC Install dir /opt/app/music
  62 - Open /etc/hosts as sudo and enter the name of the vm alongside localhost in the line for 127.0.0.1. E.g. 127.0.0.1 localhost music-1. Some of the apt-get installation seem to require this.
  63 - Ensure you have java jdk 8 or above working on your machine.
  64 - Download apache Apache Cassandra 3.2, install into /opt/app/music and follow these instructions http://cassandra.apache.org/doc/latest/getting_started/installing.html till and including Step
  65 - By the end of this you should have Cassandra working.
  66 - Create a music.properties file and place it in /opt/app/music/etc/. Here is a sample of the file:
  67
  68 ```properties
  69 my.id=0
  70 all.ids=0
  71 my.public.ip=localhost
  72 all.public.ips=localhost
  73 #######################################
  74 # Optional current values are defaults
  75 #######################################
  76 #cassandra.host=localhost
  77 #music.ip=localhost
  78 #debug=true
  79 #music.rest.ip=localhost
  80 #lock.lease.period=6000
  81 cassandra.user=cassandra
  82 cassandra.password=cassandra
  83 aaf.endpoint.url=http://aafendpoint/proxy/authz/nss/
  84 ```
  85
  86 - Make a dir /opt/app/music/logs MUSIC dir with MUSIC logs will be created in this dir after MUSIC starts.
  87 - Authentications/AAF Setup For Authentication setup.
  88 - Start MUSIC using the jar built in distribution/music folder
  89 ```bash
  90 java -jar music.jar
  91 ```
  92
  93
  94 Extra Cassandra information for Authentication:
  95
  96 To create first user in Cassandra
  97
  98 Edit conf/Cassandra.yaml file
  99
 100 ```yaml
 101 authenticator: PasswordAuthenticator
 102 authorizer: CassandraAuthorizer
 103 ```
 104 Restart Cassandra
 105 Login to cqlsh with default credentials
 106
 107 ```bash
 108 cqlsh -u cassandra -p cassandra
 109 ```
 110
 111 To change default user create new user with the following command.
 112
 113 ```sql
 114 CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER;
 115 ```
 116 Change password for default user ‘Cassandra’ so that no one will be able to login
 117
 118 ```sql
 119 ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoOneWillThinkOf’;
 120 ```
 121 Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:
 122
 123 ```properties
 124 cassandra.user=<new_user>
 125 cassandra.password=<new_password>
 126 ```
 127
 128 To access keyspace through cqlsh, login with credentials that are passed to MUSIC while creating the keyspace.
 129
 130
 131
 132 <a name ="ms-install">
 133
 134 ## Multi-site Installation
 135
 136 </a>
 137
 138 Follow the instructions for local MUSIC installation on all the machines/VMs/hosts (referred to as a node) on which you want MUSIC installed. However, Cassandra and Zookeeper needs to be configured to run as multi-node installations (instructions below) before running them.
 139
 140 #### Cassandra:
 141 In the cassandra.yaml file which is present in the cassa_install/conf directory in each node, set the following parameters:
 142 cassandra.yaml
 143 ```yaml
 144 cluster_name: ‘name of cluster’
 145 num_tokens: 256
 146 seed_provider:
 147 class_name: org.apache.cassandra.locator.SimpleSeedProvider
 148 parameters:
 149 seeds:  "<public ip of first seed>, <public ip of second seed>, etc"
 150 listen_address: private ip of VM
 151 broadcast_address: public ip of VM
 152 endpoint_snitch: GossipingPropertyFileSnitch
 153 rpc_address: <private ip>
 154 phi_convict_threshold: 12
 155 authenticator: PasswordAuthenticator
 156 authorizer: CassandraAuthorizer
 157 ```
 158
 159
 160 In the cassandra-rackdc.properties file, assign data center and rack names as if required.
 161
 162 Once this is done on all three nodes, you can run cassandra on each of the nodes through the cassandra bin folder with this command
 163 ```bash
 164 ./cassandra
 165 ```
 166     In the cassandra bin folder, if you run the following it will tell you the state of the cluster.
 167 ```bash
 168 ./nodetool status
 169 ```
 170 To access cassandra, one any of the nodes you can run the following and then perform CQL queries.
 171 ```bash
 172 ./cqlsh <private ip>
 173 ```
 174
 175 To create first user in Cassandra
 176
 177     Restart Cassandra
 178     Login to cqlsh with default credentials
 179
 180 ```bash
 181 cqlsh -u cassandra -p cassandra
 182 ```
 183
 184 To change default user create new user with the following command.
 185
 186 ```sql
 187 CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER;
 188 ```
 189 Change password for default user ‘Cassandra’ so that no one will be able to login
 190
 191 ```sql
 192 ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoOneWillThinkOf’;
 193 ```
 194 Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:
 195
 196 ```properties
 197 cassandra.user=<new_user>
 198 cassandra.password=<new_password>
 199 ```
 200
 201 To access keyspace through cqlsh, login with credentials that are passed to MUSIC while creating the keyspace.
 202
 203 #### MUSIC
 204
 205 Create a music.properties file and place it in /opt/app/music/etc at each node. Here is a sample of the file: If this location is to be changed please update the file project.properties in the src/main/resources directory before compiling MUSIC to a war.
 206 ```properties
 207 my.id=0
 208 all.ids=0:1:2
 209 my.public.ip=public IP of node 0
 210 #For each node, a separate file needs to be created with its own id (between 0 and the number of nodes) and with information about its own public ip.
 211 all.public.ips=public IP of node 0:public IP of node 1:public IP of node 2
 212 #######################################
 213 # Optional current values are defaults
 214 #######################################
 215 #cassandra.host=localhost
 216 #music.ip=localhost
 217 #debug=true
 218 #music.rest.ip=localhost
 219 #lock.lease.period=6000
 220 cassandra.user=cassandra
 221 cassandra.password=cassandra
 222 aaf.endpoint.url=http://aafendpoint/proxy/authz/nss/
 223 ```
 224
 225 - Download the latest Apache Tomcat and install it using these instructions http://tecadmin.net/install-tomcat-9-on-ubuntu/ (this is for version 9).
 226 - Build the MUSIC.war and place it within the webapps folder of the tomcat installation.
 227 - Start tomcat and you should now have MUSIC running.
 228
 229 - For Logging create a dir /opt/app/music/logs. When MUSIC/Tomcat starts a dir opt/app/music/logsMUSIC with various logs will be created.
 230  The application log is music.log and the others are debug.log and error.log.
 231
 232 <a name="jersey-mute">
 233
 234 ### Muting MUSIC jersey output
 235
 236 The jersey package that MUSIC uses to parse REST calls prints out the entire header and json body by
 237 default. To mute it (if it exists), remove the following lines from the web.xml in the WEB_INF foler:
 238
 239 ```xml
 240 <init-param>
 241   <param-name>com.sun.jersey.spi.container.ContainerResponseFilters</param-name>
 242   <param-value>com.sun.jersey.api.container.filter.LoggingFilter</param-value>
 243 </init-param>
 244 ```
 245
 246 <a name ="auth-setup">
 247
 248 ### Authentication Setup
 249
 250 MUSIC has been enhanced to support applications which are already authenticated using AAF and applications which are not authenticated using AAF.
 251 If an application has already been using AAF, it should have required namespace, mechId and password. Non AAF applications will be provided with a random unique id. MUSIC will tag the keyspace with the UID and store internally and any calls to use/modify the keyspace will require the UID.
 252 All the required params should be sent as headers.
 253
 254 - MUSIC has been enhanced to support applications which are already authenticated using AAF and applications which are not authenticated using AAF.
 255 - If an application has already been using AAF, it should have required namespace, mechId and password.
 256 - Non AAF applications (AID) will be provided with a random unique id. MUSIC will tag the keyspace with the UID and store internally and any calls to use/modify the keyspace will require the UID.
 257
 258 All the required params should be sent as headers.
 259
 260 Admin needs to create the following keyspace and table via cslsh.
 261
 262 In the cassandra bin dir run ./cqlsh -u <user> -p <password> and log in to db then:
 263
 264 If you want to save the following in a file you can then run ./cqlsh -f <file.cql>
 265 For Single install:
 266 ```sql
 267 //Create Admin Keyspace
 268
 269 CREATE KEYSPACE admin
 270   WITH REPLICATION = {
 271     'class' : 'SimpleStrategy',
 272     'replication_factor': 1
 273   }
 274   AND DURABLE_WRITES = true;
 275
 276 CREATE TABLE admin.keyspace_master (
 277   uuid uuid,
 278   keyspace_name text,
 279   application_name text,
 280   is_api boolean,
 281   password text,
 282   username text,
 283   is_aaf boolean,
 284   PRIMARY KEY (uuid)
 285 );
 286 ```
 287 Multi-Site Install:
 288 ```sql
 289 //Create Admin Keyspace
 290
 291 CREATE KEYSPACE admin
 292   WITH REPLICATION = {
 293     'class' : 'NetworkTopologyStrategy',
 294     'DC1':2,
 295     'DC2':2,
 296     'DC3':2
 297   }
 298   AND DURABLE_WRITES = true;
 299
 300 CREATE TABLE admin.keyspace_master (
 301   uuid uuid,
 302   keyspace_name text,
 303   application_name text,
 304   is_api boolean,
 305   password text,
 306   username text,
 307   is_aaf boolean,
 308   PRIMARY KEY (uuid)
 309 );
 310 ```
 311
 312 Headers:
 313 - For AAF applications all the 3 of the following headers are mandatory.
 314   - <b>ns</b>
 315   - <b>mechId</b>
 316   - <b>password</b>
 317 - For Non AAF applications if the header <b>aid</b> is not provided MUSIC creates new random unique UUID and returns to caller.
 318 - Caller application then need to save the UUID and need to pass the UUID to further modify/access the keyspace.
 319 - Make sure steps to set up Cassandra for authentication above in the cassandra.yaml were done.
 320
 321
 322 ### On Boarding app
 323 The following API is used to onboard the applications.
 324 /MUSIC/rest/v2/admin/onboardAppWithMusic
 325 This is a POST call and requires the following JSON:
 326 ```json
 327 {
 328 "appname": "<the Namespace for aaf or the Identifier for the specific app using AID access>",
 329 "userId" : "<userid>",
 330 "isAAF"  : true|false
 331 }
 332 ```
 333