Node Removals

How to request removal of a SaladCloud Node from your SGS server

When to request a node removal

SaladCloud goes to extreme lengths to filter the nodes available on SGS to maximize speed, reliability, uptime, IP quality, and other performance metrics. In addition, SGS constantly monitors node performance characteristics and automatically removes underperforming SaladCloud nodes. However, in the event that a SaladCloud node becomes blocked by a content provider, or for any other reason fails to meet your requirements, you can request that it be removed from the list of available IPs and replaced with a fresh node. You can do this by requesting a node removal.

At the time that the node removal request is received, the node which is connected to the session ID in the request body will be removed.

If a node becomes unavailable for any reason, the pool of nodes connected to the SGS server will automatically be ‘topped up’ with a fresh node on a best-effort basis. Any streaming sessions with were routed over the unavailable node will be transferred to other nodes.

How to request a node removal

Submit a node removal request by sending a POST request to the following endpoint: https://app-api.salad.com/api/v2/sgs/$SGS_ID/removals

The SGS_ID will be shared with you before the trial period begins.

Set the Authorization header as below: Authorization: Bearer $SALAD_JWT

The SALAD_JWT will be shared with you before the trial period begins.

Cautionary notes regarding node removals

A node removal completely boots a node from your SGS server. If the node failed to connect to a single service, it may still be viable for other services - or exhibited a transient error. Node removals should therefore be thought of as a last resort. If you find that multiple nodes are failing to connect to a specific service it is preferable to reach out to your Account Manager first to discuss implementing a Smart Routing filter. If, however, you find a node which is consistently underperforming - either exhibiting high latency or poor connectivity to target services - then a node removal might make sense. Keep in mind that, in countries with a limited number of available nodes, use of the node removal feature may result in removed nodes not being replaced immediately. Overuse of the feature could temporarily deplete your node pool to the point that throughput levels are impacted, resulting in buffering and other poor experiences for your customers.

When you submit a node removal request, SaladCloud marks a node for removal based on which node is currently mapped to the sessionID that you provide in your node removal request. If the sessionID has since been mapped to a new node - for instance, if the unhealthy node was already removed by SGS or went offline for any reason - your node removal request will cause the removal of the new, healthy node. For this reason, we recommend that you submit the node removal request as soon as possible after detecting an underperforming node to avoid inadvertently removing a healthy node which may now be assigned that sessionID.

Response codes

202 Accepted

The removal request has been accepted.

400 Bad Request

The request is malformed or missing required fields. Please double-check your request.

409 Conflict

A removal has already been recently performed on this sessionID. This prevents multiple requests from inadvertently removing healthy nodes following a successful node removal.

Node removal requests should be in the format application/json. The removalReason and service fields help SaladCloud diagnose root causes of node underperformance and improve our filters.

Example request

curl -v -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $SALAD_JWT" -d '{"sessionId": "$SESSION_ID","timeDetectedAt": $TIME,"removalReason": "$REMOVAL_REASON","service": "$SERVICE"}' https://app-api.salad.com/api/v2/sgs/$SGS_ID/removals

node_removal.json

{
// A required string representing the session identifier.
"sessionId": "eb40cca0-c17b-4de8-a850-ac510bc29c6c",
// An optional Unix timestamp (seconds) indicating when it was detected as bad.
"timeDetectedAt": 1657639946,
// A required string with the reason for removal.
"removalReason": "Reason for removal request",
// A required string describing the specific service that was failing.
"service": "Example_Service"
}