Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated node removals docs for clarity and correctness, overuse warning #106

Merged
merged 3 commits into from
Nov 11, 2024
Merged

Updated node removals docs for clarity and correctness, overuse warning #106

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fe8e918
Updated node removals docs for clarity and correctness, added warning…
eric-solie Nov 8, 2024
71194ed
fixed code block syntax highlighting
eric-solie Nov 10, 2024
b2415ac
updated dictionary
eric-solie Nov 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 45 additions & 18 deletions products/sgs/node-removals.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,50 @@ description: 'How to request removal of a SaladCloud Node from your SGS server'

## When to request a node removal

SaladCloud makes a best effort to identify and remove 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. At the time that the request
is received, the node which is connected to the session ID in the request body will be removed.
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**.

If a node becomes unavailable, it will automatically be replaced with a fresh 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 fresh node which may have already replaced the underperforming node.
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://matrix-rest-api.salad.com/api/v2/sgs/$SGS_ID/removals`
`https://app-api.salad.io/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 saladProvidedJwt`
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

The JWT will be shared with you before the trial period begins.
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](/products/sgs/smart-routing). 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.

## Response Codes
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

<AccordionGroup>
<Accordion title="202 Accepted">
Expand All @@ -39,26 +62,30 @@ The JWT will be shared with you before the trial period begins.
</Accordion>

<Accordion title="409 Conflict">
A removal has already been performed on this sessionID.
A removal has already been recently performed on this sessionID. This prevents multiple requests from inadvertently removing healthy nodes following a successful node removal.
</Accordion>
</AccordionGroup>

<Note>
This should be in the format application/json. Fields marked as optional are useful for SaladCloud in preventing the
use of nodes that may trigger a node removal request in the future.
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.
</Note>

## Example Request
## Example request

```Curl.sh
shawnrushefsky marked this conversation as resolved.
Show resolved Hide resolved
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.io/api/v2/sgs/$SGS_ID/removals
```

```JSON 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 string with the reason for removal.
"removalReason": "Reason for removal request.",
// A string describing the specific service that was failing.
// 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"
}
```