Upgrading Stream Manager 1.0 to 2.0

This document assumes that you have already set up an autoscaling environment per Deploying Stream Manager and Autoscaling on Amazon Web Services or Deploying Stream Manager and Autoscaling on Google Cloud Compute.

Update Database

Due to significant changes in the autoscaling database schema and logic, it is not possible to simply upgrade the database in place. The best solution is to setup a separate database instance, parallel to the one which is live.

Follow your cloud database setup instructions to setup a new database for autoscaling. Use the same instance configuration and credentials as your live database instance.

IMPORTANT: Make a note of this new database IP address (for Google Cloud) or Endpoint url (for AWS). This will be used in red5-web.properties - config.dbHost property when configuring stream manager.

  • Configure the the new SQL instance to allow access from the stream manager IP (both public and private IP for AWS).

Create New Disk Image/AMI

You will need to use the latest Red5 Pro Server build to take advantage of the improvements in the Stream Manager API 2.0. Follow Upgrading Red5 Pro for Autoscaling Nodes and make a note of the disk image name to use in the launchconfig for the Stream Manager update.

Update Stream Manager

Per "How to Upgrade Red5 Pro Server," the cleanest way to upgrade the Stream Manager will be to:

  1. Download the latest Red5 Pro Server distribution and the latest Red5 Pro Autoscaling Library Extensions (for AWS or for Google Cloud) from https://account.red5pro.com/download to your local machine.
  2. Copy both files up to the Stream Manager.
  3. Copy and unzip the new distribution into the same directory where the original red5pro folder was (e.g. /usr/local/).
  4. Copy the cloud controller jar file to the webapps/streammanager/WEB-INF/lib/ directory of the new server distribution.
  5. Remove /conf/autoscale.xml and /plugins/red5pro-autoscale-plugin-1.1.0.jar from the new server distribution.
  6. Note the values in the previous {red5prohome}/webapps/streammanager/WEB-INF/red5-web.properties file and edit the new webapps/streammanager/WEB-INF/red5-web.properties per those values - with the exception of using the new database IP or Endpoint URL for the config.dbHost property. There are several new values in the latest red5-web.properties file, so you can't just copy this from the old build.
  7. Edit the Launch Config and Scaling Files as described for AWS, or for Google Cloud.

When you are ready to upgrade

  1. Rename your existing red5pro folder to bak.red5pro (sudo mv red5pro bak.red5pro).
  2. Rename the new server distribution directory to red5pro (sudo mv red5pro-server-* red5pro).
  3. Kill the Red5 Pro Service (ps aux | grep java to get the Red5 Pro PID, then sudo kill -9 <PID>).
  4. Start the Red5 Pro Service sudo /etc/init.d/red5pro start.
  5. Following the API Basics below, create a nodegroup to match the previous setup and add an origin server. Note that in the new version of autoscaling, a nodegroup can have multiple origin servers. In addition, you can specify different server types for origin and edge servers.

Adding Backwards Compatibility for Broadcast/Subscribe Clients

If you have existing streaming clients referencing the previous version of Stream Manager API, upgrading to the latest Stream Manager, running api 2.0, will make your streammanager api service inaccessible to them without adding in redirection support.

The process of changing a URL request endpoint dynamically at runtime on a server is known as URLRewriting. To ensure that our API 1.0 event-stream requests are automatically sent to the new API 2.0 request path we need to rewrite the /api/1.0 requests as /api/2.0 requests.

Red5 Pro runs on Tomcat engine, so we need to use a Tomcat supported solution for our URL-rewriting. The following solution uses UrlRewriteFilter, a popular URL-rewrite library for apache tomcat:

STEP 1: Download the url-rewrite library

Download the latest version of the UrlRewriteFilter library (jar) from here.

STEP 2: Copy the library into streammanager

Copy the downloaded jar into {red5prohome}/webapps/streammanager/WEB-INF/lib/

STEP 3: Register the library in streammanager to intercept and handle web requests

  • Edit {red5prohome}/webapps/streammanager/WEB-INF/web.xml with the editor of your choice, adding the UrlRewriteFilter filter xml snippet at the end (after the authFilter):-
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>

<init-param>
<param-name>statusEnabled</param-name>
<param-value>false</param-value>
</init-param>
</filter>

<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>

Your web.xml file will now look like this:-

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5">

<display-name>streammanager</display-name>

<context-param>
<param-name>webAppRootKey</param-name>
<param-value>/streammanager</param-value>
</context-param>

<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
</welcome-file-list>

<listener>
<listener-class>org.red5.logging.ContextLoggingListener</listener-class>
</listener>

<filter>
<filter-name>LoggerContextFilter</filter-name>
<filter-class>org.red5.logging.LoggerContextFilter</filter-class>
</filter>

<filter-mapping>
<filter-name>LoggerContextFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

<servlet>
<servlet-name>dispatcher</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>dispatcher</servlet-name>
<url-pattern>/api/2.0/*</url-pattern>
</servlet-mapping>

<servlet>
<servlet-name>cloudwatch</servlet-name>
<servlet-class>com.red5pro.services.streammanager.servlet.CloudWatch</servlet-class>
<load-on-startup>-1</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>cloudwatch</servlet-name>
<url-pattern>/cloudwatch/*</url-pattern>
</servlet-mapping>

<filter>
<filter-name>authFilter</filter-name>
<filter-class>
org.springframework.web.filter.DelegatingFilterProxy
</filter-class>
</filter>

<filter-mapping>
<filter-name>authFilter</filter-name>
<url-pattern>/api/2.0/admin/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>

<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>

<init-param>
<param-name>statusEnabled</param-name>
<param-value>false</param-value>
</init-param>
</filter>

<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>

</web-app>

STEP 4: Activate URLRewriting for event broadcast & subscribe requests

  • Create a file named urlrewrite.xml in {red5prohome}/webapps/streammanager/WEB-INF/, with the following code:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
"http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">

<urlrewrite use-context="true" use-query-string="true">

<rule match-type="regex">
<from>/api/1.0/event/(.*)$</from>
<to type="redirect">/api/2.0/event/$1</to>
</rule>

</urlrewrite>

This file contains the re-writing rule which is used by UrlRewriteFilter to decide when to and how to redirect URL request paths.

STEP 5: Restart server

Once all of the above steps are done, you need to restart the Red5 Pro service on the Stream Manager for changes to take effect.


VERIFYING

Once your deployment is active, you can test the UrlRewriteFilter by making a simple GET request at the old api 1.0 endpoint from the browser.

Example: (This is a test endpoint)

REQIUEST

Url

http://{host}:5080/streammanager/api/1.0/event/test?action=broadcast

Method : GET

RESPONSE

Success: HTTP CODE 200

DATA

welcome to stream manager event route

Once you enter the URL in the browser and hit "Enter", you should see your URL automatically changing to http://{host}:5080/streammanager/api/2.0/event/test?action=broadcast in the browser's address bar.


API Basics, to get you started

(for full API, see Red5 Pro Stream Manager API)

Verify Stream Manager is Using the Correct Controller

GET call: http://<streammanager_IP>:5080/streammanager/api/2.0/admin/debug/cloudcontroller?accessToken=<rest.administratorToken from red5-web.properties file>

should return: Google Compute for Google Cloud or Amazon Web Services for AWS.

Create a New Node Group (POST)

Using a tool like Postman, create a new node group via the API. baseCapacity is the Minimum subscriber connections that this group should support. (This parameter helps the scale-in process decide when to scale down an edge).

POST call: http://<streammanager_IP>:5080/streammanager/api/2.0/admin/nodegroup?accessToken=<rest.administratorToken from red5-web.properties file>

Data (make sure to select JSON as the body type):

{
 "regions": [
   "<google region, e.g.: us-east1; or aws region, e.g. us-east-1>"
 ],
 "launchConfig": "default-v2",
 "scalePolicy": "default-v2"
}

Note the cluster “name” that is returned by the above call. It will be used to create a new Origin server.

Launch New Origin (POST)

After you create a node group, create the origin server. Creating an origin server will also generate at least one edge, per scaling policy min limit.

http://<streammanager_IP>:5080/streammanager/api/2.0/admin/nodegroup/<cluster-name>/node/origin?accessToken=<rest.administratorToken from red5-web.properties file>

NOTE: If you wish to launch more than one origin, you can repeat the call. The maximum origins allowed will depend on the maxLimit attribute of the 'origin' object described in scale policy. If 'origin' is omitted from the scale policy then the default value for maximum origins is 1.

Set Alarm Threshold (POST)

By default, the alarm threshold (the capacity percentage at which the cluster will scale up) is set to 55%. To modify this, POST the following:

FOR EDGE:

http://<streammanager_IP>:5080/streammanager/api/2.0/admin/alarm/scaleout/default?type=edge&threshold=<threshold>&accessToken=<rest.administratorToken from red5-web.properties file>

FOR ORIGIN:

http://<streammanager_IP>:5080/streammanager/api/2.0/admin/alarm/scaleout/default?type=origin&threshold=<threshold>&accessToken=<rest.administratorToken from red5-web.properties file>

LIST GROUPS (GET)

http://<streammanager_IP>:5080/streammanager/api/2.0/admin/nodegroup?accessToken=<rest.administratorToken from red5-web.properties file>