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 Tomcat, Cassandra and Zookeeper they should also be installed here.
  36 ```bash
  37 /opt/app/music/apache-cassandra-n.n.n
  38 /opt/app/music/zookeeper-n.n.n
  39 /opt/app/music/apache-tomcat-n.n.n
  40 ```
  41 Its suggested you create links from install dirs to a common name ie:
  42 ```bash
  43 ln -s /opt/app/music/apache-cassandra-n.n.n cassandra
  44 ln -s /opt/app/music/zookeeper-n.n.n zookeeper
  45 ln -s /opt/app/music/apache-tomcat-n.n.n tomcat
  46 ```
  47
  48 Cassandra and Zookeeper have data dirs.
  49 ```bash
  50 # For cassandra it should be (This is the default)
  51 /opt/app/music/cassandra/data
  52 # For Zookeeper it should be
  53 /opt/app/music/var/zookeeper/
  54 ```
  55
  56 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
  57 does give issues).
  58
  59 <a name="local-install">
  60
  61 ## Local Installation
  62
  63 </a>
  64
  65 ### Instructions
  66
  67 - Create MUSIC Install dir /opt/app/music
  68 - 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.
  69 - Ensure you have java jdk 8 or above working on your machine.
  70 - 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
  71 - By the end of this you should have Cassandra working.
  72 - Download Apache Zookeeper 3.4.6, install into /opt/app/music and follow these instructions https://zookeeper.apache.org/doc/trunk/zookeeperStarted.html pertaining to the standalone operation. By the end of this you should have Zookeeper working.
  73 - Create a music.properties file and place it in /opt/app/music/etc/. Here is a sample of the file:
  74
  75 ```properties
  76 my.id=0
  77 all.ids=0
  78 my.public.ip=localhost
  79 all.public.ips=localhost
  80 #######################################
  81 # Optional current values are defaults
  82 #######################################
  83 #zookeeper.host=localhost
  84 #cassandra.host=localhost
  85 #music.ip=localhost
  86 #debug=true
  87 #music.rest.ip=localhost
  88 #lock.lease.period=6000
  89 cassandra.user=cassandra
  90 cassandra.password=cassandra
  91 aaf.endpoint.url=http://aafendpoint/proxy/authz/nss/
  92 ```
  93
  94 - Make a dir /opt/app/music/logs MUSIC dir with MUSIC logs will be created in this dir after MUSIC starts.
  95 - Download the latest Apache Tomcat and install it using these instructions http://tecadmin.net/install-tomcat-9-on-ubuntu/ (this is for version 9).
  96 - Build the MUSIC.war (or download it from https://github.com/att/music/blob/master/MUSIC.war) and place it within the webapps folder of the tomcat installation.
  97 - Authentications/AAF Setup For Authentication setup.
  98 - Start tomcat and you should now have MUSIC running.
  99
 100
 101 Extra Cassandra information for Authentication:
 102
 103 To create first user in Cassandra
 104
 105 Edit conf/Cassandra.yaml file
 106
 107 ```yaml
 108 authenticator: PasswordAuthenticator
 109 authorizer: CassandraAuthorizer
 110 ```
 111 Restart Cassandra
 112 Login to cqlsh with default credentials
 113
 114 ```bash
 115 cqlsh -u cassandra -p cassandra
 116 ```
 117
 118 To change default user create new user with the following command.
 119
 120 ```sql
 121 CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER;
 122 ```
 123 Change password for default user ‘Cassandra’ so that no one will be able to login
 124
 125 ```sql
 126 ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoOneWillThinkOf’;
 127 ```
 128 Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:
 129
 130 ```properties
 131 cassandra.user=<new_user>
 132 cassandra.password=<new_password>
 133 ```
 134
 135 To access keyspace through cqlsh, login with credentials that are passed to MUSIC while creating the keyspace.
 136
 137
 138
 139 <a name ="ms-install">
 140
 141 ## Multi-site Installation
 142
 143 </a>
 144
 145 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.
 146
 147 #### Cassandra:
 148 In the cassandra.yaml file which is present in the cassa_install/conf directory in each node, set the following parameters:
 149 cassandra.yaml
 150 ```yaml
 151 cluster_name: ‘name of cluster’
 152 num_tokens: 256
 153 seed_provider:
 154 class_name: org.apache.cassandra.locator.SimpleSeedProvider
 155 parameters:
 156 seeds:  "<public ip of first seed>, <public ip of second seed>, etc"
 157 listen_address: private ip of VM
 158 broadcast_address: public ip of VM
 159 endpoint_snitch: GossipingPropertyFileSnitch
 160 rpc_address: <private ip>
 161 phi_convict_threshold: 12
 162 authenticator: PasswordAuthenticator
 163 authorizer: CassandraAuthorizer
 164 ```
 165
 166
 167 In the cassandra-rackdc.properties file, assign data center and rack names as if required.
 168
 169 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
 170 ```bash
 171 ./cassandra
 172 ```
 173     In the cassandra bin folder, if you run the following it will tell you the state of the cluster.
 174 ```bash
 175 ./nodetool status
 176 ```
 177 To access cassandra, one any of the nodes you can run the following and then perform CQL queries.
 178 ```bash
 179 ./cqlsh <private ip>
 180 ```
 181
 182 To create first user in Cassandra
 183
 184     Restart Cassandra
 185     Login to cqlsh with default credentials
 186
 187 ```bash
 188 cqlsh -u cassandra -p cassandra
 189 ```
 190
 191 To change default user create new user with the following command.
 192
 193 ```sql
 194 CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER;
 195 ```
 196 Change password for default user ‘Cassandra’ so that no one will be able to login
 197
 198 ```sql
 199 ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoOneWillThinkOf’;
 200 ```
 201 Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:
 202
 203 ```properties
 204 cassandra.user=<new_user>
 205 cassandra.password=<new_password>
 206 ```
 207
 208 To access keyspace through cqlsh, login with credentials that are passed to MUSIC while creating the keyspace.
 209
 210 #### Zookeeper:
 211
 212 Once zookeeper has been installed on all the nodes, modify the  zk_install_location/conf/zoo.cfg on all the nodes with the following lines:
 213 ```properties
 214 tickTime=2000
 215 dataDir=/opt/app/music/var/zookeeper
 216 clientPort=2181
 217 initLimit=5
 218 syncLimit=2
 219 quorumListenOnAllIPs=true
 220 server.1=public IP of node 1:2888:3888
 221 server.2=public IP of node 2:2888:3888
 222 server.3=public IP of node 3:2888:3888
 223 ```
 224 In /opt/app/music/var/zookeeper in all the machines, create a file called myid that contains the id of the machine. The machine running node.i will contain just the number i in the file myid.
 225
 226 Start each of the nodes one by one from the zk_install_location/bin folder using the command:
 227 ```bash
 228 ./zkServer.sh start
 229 ```
 230 On each node check the file zookeeper.out in the  zk_install_location/ bin to make sure all the machines are talking to each other and there are no errors. Note that while the machines are yet to come up there maybe error messages saying that connection has not yet been established. Clearly, this is ok.
 231
 232 If there are no errors, then from zk_install_location/bin simply run the following to get command line access to zookeeper.   ./zkCli.sh
 233
 234 Run these commands on different machines to make sure the zk nodes are syncing.
 235 ```bash
 236 [zkshell] ls /
 237 [zookeeper]
 238 ```
 239 Next, create a new znode by running
 240 ```bash
 241 create /zk_test my_data.
 242 ```
 243 This creates a new znode and associates the string "my_data" with the node. You should see:
 244 ```bash
 245 [zkshell] create /zk_test my_data
 246 Created /zk_test
 247 ```
 248 Issue another ls / command to see what the directory looks like:
 249 ```bash
 250 [zkshell] ls /
 251 [zookeeper, zk_test]
 252 ```
 253
 254 #### MUSIC
 255
 256 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.
 257 ```properties
 258 my.id=0
 259 all.ids=0:1:2
 260 my.public.ip=public IP of node 0
 261 #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.
 262 all.public.ips=public IP of node 0:public IP of node 1:public IP of node 2
 263 #######################################
 264 # Optional current values are defaults
 265 #######################################
 266 #zookeeper.host=localhost
 267 #cassandra.host=localhost
 268 #music.ip=localhost
 269 #debug=true
 270 #music.rest.ip=localhost
 271 #lock.lease.period=6000
 272 cassandra.user=cassandra
 273 cassandra.password=cassandra
 274 aaf.endpoint.url=http://aafendpoint/proxy/authz/nss/
 275 ```
 276
 277 - Download the latest Apache Tomcat and install it using these instructions http://tecadmin.net/install-tomcat-9-on-ubuntu/ (this is for version 9).
 278 - Build the MUSIC.war and place it within the webapps folder of the tomcat installation.
 279 - Start tomcat and you should now have MUSIC running.
 280
 281 - 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.
 282  The application log is music.log and the others are debug.log and error.log.
 283
 284 <a name="jersey-mute">
 285
 286 ### Muting MUSIC jersey output
 287
 288 The jersey package that MUSIC uses to parse REST calls prints out the entire header and json body by
 289 default. To mute it (if it exists), remove the following lines from the web.xml in the WEB_INF foler:
 290
 291 ```xml
 292 <init-param>
 293   <param-name>com.sun.jersey.spi.container.ContainerResponseFilters</param-name>
 294   <param-value>com.sun.jersey.api.container.filter.LoggingFilter</param-value>
 295 </init-param>
 296 ```
 297
 298 <a name ="auth-setup">
 299
 300 ### Authentication Setup
 301
 302 MUSIC has been enhanced to support applications which are already authenticated using AAF and applications which are not authenticated using AAF.
 303 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.
 304 All the required params should be sent as headers.
 305
 306 - MUSIC has been enhanced to support applications which are already authenticated using AAF and applications which are not authenticated using AAF.
 307 - If an application has already been using AAF, it should have required namespace, mechId and password.
 308 - 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.
 309
 310 All the required params should be sent as headers.
 311
 312 Admin needs to create the following keyspace and table via cslsh.
 313
 314 In the cassandra bin dir run ./cqlsh -u <user> -p <password> and log in to db then:
 315
 316 If you want to save the following in a file you can then run ./cqlsh -f <file.cql>
 317 For Single install:
 318 ```sql
 319 //Create Admin Keyspace
 320
 321 CREATE KEYSPACE admin
 322   WITH REPLICATION = {
 323     'class' : 'SimpleStrategy',
 324     'replication_factor': 1
 325   }
 326   AND DURABLE_WRITES = true;
 327
 328 CREATE TABLE admin.keyspace_master (
 329   uuid uuid,
 330   keyspace_name text,
 331   application_name text,
 332   is_api boolean,
 333   password text,
 334   username text,
 335   is_aaf boolean,
 336   PRIMARY KEY (uuid)
 337 );
 338 ```
 339 Multi-Site Install:
 340 ```sql
 341 //Create Admin Keyspace
 342
 343 CREATE KEYSPACE admin
 344   WITH REPLICATION = {
 345     'class' : 'NetworkTopologyStrategy',
 346     'DC1':2,
 347     'DC2':2,
 348     'DC3':2
 349   }
 350   AND DURABLE_WRITES = true;
 351
 352 CREATE TABLE admin.keyspace_master (
 353   uuid uuid,
 354   keyspace_name text,
 355   application_name text,
 356   is_api boolean,
 357   password text,
 358   username text,
 359   is_aaf boolean,
 360   PRIMARY KEY (uuid)
 361 );
 362 ```
 363
 364 Headers:
 365 - For AAF applications all the 3 of the following headers are mandatory.
 366   - <b>ns</b>
 367   - <b>mechId</b>
 368   - <b>password</b>
 369 - For Non AAF applications if the header <b>aid</b> is not provided MUSIC creates new random unique UUID and returns to caller.
 370 - Caller application then need to save the UUID and need to pass the UUID to further modify/access the keyspace.
 371 - Make sure steps to set up Cassandra for authentication above in the cassandra.yaml were done.
 372
 373
 374 ### On Boarding app
 375 The following API is used to onboard the applications.
 376 /MUSIC/rest/v2/admin/onboardAppWithMusic
 377 This is a POST call and requires the following JSON:
 378 ```json
 379 {
 380 "appname": "<the Namespace for aaf or the Identifier for the specific app using AID access>",
 381 "userId" : "<userid>",
 382 "isAAF"  : true|false
 383 }
 384 ```
 385