API Basics
(for full API, see Red5 Pro Stream Manager API)
For the POST calls, we recommend using a tool like Postman.
Verify Stream Manager is Using the Correct Controller
GET call:
https://<streammanager_URL>/streammanager/api/4.0/admin/debug/cloudcontroller?accessToken=<rest.administratorToken>
should return: Google Compute
Create a Scale Policy (post)
- Make sure to include a
role
section for each node type you want to include (origin, edge, relay, transcoder):
POST call:
https://<streammanager_URL>/streammanager/api/4.0/admin/configurations/scalepolicy?accessToken=<rest.administratorToken>
Data (make sure to select JSON as the body type):
{
"policy": {
"name": "<policy-name>",
"description": "<policy-description>>",
"type": "<policy-type>",
"version": "<policy-version>",
"targets": {
"region": [
{
"name": "default",
"target": [
{
"role": "<role>",
"minLimit": "<min-node-count>",
"maxLimit": "<max-node-count>",
"scaleAdjustment": "<node-scale-adjustment>"
}
]
}
}}
Create a Launch Policy (post)
For ease of administration, we recommend naming the policy something easily identifiable and descriptive, such as <imagename>-<nodetypes>
(e.g., red5pro6.4.0-allnodetypes
)
POST call:
https://<streammanager_URL>/streammanager/api/4.0/admin/configurations/launchconfig?accessToken=<rest.administratorToken>
Data (make sure to select JSON as the body type):
{
"launchconfig": {
"name": "<configuration-name>",
"description": "<configuration-descrption>",
"image": "<red5pro-image>",
"version": "0.0.3",
"targets": {
"target": [
{
"role": "<role>",
"instanceType": "<instance-type>",
"connectionCapacity": "<instance-capacity>"
}
]
},
"properties": {
"property": [
{
"name": "<property-name>",
"value": "<property-value>"
}
]
},
"metadata": {
"meta": [
{
"key": "<meta-name>",
"value": "<meta-value>"
}
]
}
}}
Create a New Node Group (post)
POST call:
https://<streammanager_URL>/streammanager/api/4.0/admin/nodegroup?accessToken=<rest.administratorToken>
Data (make sure to select JSON as the body type):
{
"regions": [
"<region, eg: us-west2>"
],
"launchConfig": "<launchconfig-created-above>",
"scalePolicy": "<scaleconfig-created-above>"
}
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.
https://<streammanager_URL>/streammanager/api/4.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 the 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 any given node type) is set to 60%. To modify this, POST the following:
FOR EDGE:
FOR ORIGIN:
https://<streammanager_URL>/streammanager/api/4.0/admin/alarm/scaleout/default?type=origin&threshold=<threshold>&accessToken=<rest.administratorToken>
FOR RELAY:
https://<streammanager_URL>/streammanager/api/4.0/admin/alarm/scaleout/default?type=relay&threshold=<threshold>&accessToken=<rest.administratorToken>
FOR TRANSCODER:
https://<streammanager_URL>/streammanager/api/4.0/admin/alarm/scaleout/default?type=transcoder&threshold=<threshold>&accessToken=<rest.administratorToken>
LIST GROUPS (get)
https://<streammanager_URL>/streammanager/api/4.0/admin/nodegroup?accessToken=<rest.administratorToken from red5-web.properties file>
Stream Manager Publish and Subscribe Examples
Stream Manager Proxy Publish and Subscribe Examples
With the latest release, the live
web app includes two examples: proxy-publisher.html
and proxy-subscriber.html
. These examples will take the following query parameters:
Name | Description | Default Value |
---|---|---|
host | hostname or IP | window.location.hostname |
protocol | protocol which Stream Manager is served over (HTTP or HTTPS) | window.location.protocol |
port | port number that Stream Manager is served on | window.location.port |
app | webapp name to stream to on the server | live |
streamName | The unique stream name to broadcast with or subscribe to | None. Required |
verbose | Flag to enable verbose logging in Dev Console | None. optional |
view | Target broadcast or subscribe tech (RTC, RTMP, HLS) | None. Optional |
Example URI:
https://streammanager.test.com/live/proxy-publisher.html?streamName=stream1&verbose=1
Red5 Pro HTML5 SDK Examples:
Note: the streaming-html5
examples testbed is included with the Red5 Pro server distribution, and can be accessed via your stream manager at https://your.server.url/webrtcexamples/
.
Red5 Pro iOS SDK Examples:
Red5 Pro Android SDK Examples:
Compute VM Startup Scripts for Automation
Google compute allows the provisioning of shell scripts that can be executed on a VM as soon as it is initialized. This can be very useful in automating configuration tasks for dynamically scaled compute instances.
Sample Use Cases:
- Use a shell script to update the cloudwatch URL property in the
autoscale.xml
during instance launch. - Use a shell script to configure the various Red5 Pro attributes on the fly dynamically as the instance is being started.
- Install NFS, mount your file share, and set access permissions on an autoscaled node.
While these are just samples of use cases, you can have your shell script do almost any kind of change on the instance.
Providing Startup Script to Autoscaled Nodes
Since the Stream Manager is responsible for launching Red5 Pro instances on the GCP, we need to configure Stream Manager to initialize Startup Script
on nodes.
The way this is done is by using the launch configuration schema. The launch configuration allows us to specify a list of MetaData
items. These items are added to the instance as a part of its metadata. Google cloud compute, uses special metadata by the name startup-script-url
to attach a shell script to the VM.
The URL points to a publically accessible shell script resource. During the VM startup, the script will be downloaded from the location and run on the instance. A common usage pattern is to place the script in your Google storage bucket by your project ID. Example: gs://" + PROJECT_ID + "/vm-startup.sh
.
For more information on startup scripts check out the official GCP documentation.