Skip to main content

Automated Deployment

Start a match or deploy an app#

To automate your game server’s deployment, you have to send an API call through your matchmaker. You have to generate a POST request to Arbitrium (to the following path) with a payload as follows:

POST request URL:
Development
Production
https://api.edgegap.com/v1/deploy
Staging
https://staging-api.edgegap.com/v1/deploy

Include your API Token in your Headers like this:

{
"Content-Type": "application/json",
"Authorization": "token super_secret_token_1234"
}

REST payload example:

{
"app_name": "speedtest",
"version_name": "v1",
"ip_list": ["162.254.148.29", "198.12.116.4", "4.91.11.18", "5.10.64.8"],
"env_vars": [
{
"key": "message_of_the_day",
"value": "Welcome to our new CSGO server"
},
{
"key": "STEAM_KEY",
"value": "XXXXXXXXXXXXXXXXX",
"is_hidden": "true"
}
],
"tags": ["example", "demo"]
}

In the example above, you can see that we have the following elements:

app_name: Represents the name of your game, as configured in our dashboard.

version_name: Represent the name of the version you want to deploy associated with the game.

ip_list: This list can have up to 200 IPs for each player involved in this specific match. You must have at least one IP.

env_vars: A list of environment variables to pass to the deployment. They will overwrite your application environment variables with the same key or add themselves to the deployment otherwise.

is_hidden: The field is not required, but we will encrypt the value in the case of sensitive information.

tags: Optional list of tags. They must be strings.

Provided Latitude / Longitude#

Alternatively, you can send your player’s location directly in the request if you have it. Instead of sending us the "ip_list", you need to send us the "geo_ip_list" like this:

Note that if you send an invalid latitude or longitude, Arbitrium will resolve the location for this IP as 0,0.

{
"app_name": "speedtest",
"version_name": "v1",
"geo_ip_list": [
{
"ip": "162.254.148.29",
"latitude": 45.50169,
"longitude": -73.567253
},
{
"ip": "198.12.116.4",
"latitude": 41.878113,
"longitude": -87.629799
},
{
"ip": "4.91.11.18",
"latitude": 40.712776,
"longitude": -74.005974
},
{
"ip": "5.10.64.8",
"latitude": 43.653225,
"longitude": -79.383186
}
]
}

You can test an API call through tools like Postman or simply using a Linux shell command line:

curl --location --request POST 'https://********/v1/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: token super_secret_token_1234' \
--data-raw '{
"app_name": "speedtest",
"version_name": "v1",
"ip_list": [
"162.254.148.29",
"198.12.116.4",
"4.91.11.18",
"5.10.64.8"
]
}'

The response will follow this format:

{
"request_id": "b042e7c3ee5a",
"request_dns": "speedtest.b042e7c3ee5a.edgelab.io",
"request_app": "speedtest",
"request_version": "v1",
"request_user_count": 4
}

request_id is your unique identifier to keep track of your request across the Arbitrium ecosystem.
request_dns is your unique FQDN where it will host the application instance.
request_app is a confirmation of the application selected.

request_version is a confirmation of the version selected.
request_user_countconfirms the user count provided with ip_list.

It will take a few seconds between when a request is received to the time when the game server (or component) is up and running. During those few seconds, you can request status if you want using the following API request (replace the unique id at the end of the request with the match unique id received in the API response) :

curl --location --request GET 'https://********/v1/status/b042e7c3ee5a' \
--header 'authorization: token super_secret_token_1234'

The response during deployment will follow this format:

Note that if the deployment is not Ready, Arbitrium might not have done the port mapping, and you may see that the location information isn’t present or final.

{
"request_id": "b042e7c3ee5a",
"fqdn": "speedtest.b042e7c3ee5a.edgelab.io:32487",
"app_name": "speedtest",
"app_version": "v1",
"current_status": "Status.READY",
"running": true,
"start_time": "2020-08-28 15:31:49.062249",
"elapsed_time": 412,
"error": false,
"last_status": "Status.DEPLOYING",
"ports": {
"80": {
"external": 11111,
"internal": 80,
"protocol": "TCP"
}
},
"tags": ["example", "production"]
}

You now have a game server running and ready for your players.

Filtering a deployment’s location#

You can have better control over the chosen location for your deployment by adding filters to the deployment request. For example, you can exclude specific cities from potential locations or require that the location is within a particular country.

This filter is implemented through the filters parameter in the request.

A filter entry has the following structure:

  • A field: The field where the filter is applied.
  • the values: A list of the values to use when filtering.
  • A filter_type: The logic operator to use when filtering.

For example, if you want to deploy in the Canada or USA, but not in Montreal, you would use the following filters:

{
[...]
filters: [
{
"field": "country",
"values": ["Canada", "United States"],
"filter_type": "any",
},
{
"field": "city",
"values": ["Montreal"],
"filter_type": "not",
}
]
[...]
}

You can refer to the API documentation on creating a deployment for more information.

Stop a deployment#

To stop a deployment, you have to send an API call with your matchmaker or any tool at your disposal.

From the previous example we got a "request_id": "b042e7c3ee5a". You have to generate a DELETE request to Arbitrium (to the following path) with a payload, like the following example:

Include your API Token in your Headers like this:

{
"Content-Type": "application/json",
"Authorization": "token super_secret_token_1234"
}

REST example:

curl --location --request DELETE 'https://*********/v1/stop/b042e7c3ee5a' \
--header 'authorization: token super_secret_token_1234'

Based on the delete deployment request call flow, the response will follow one of these formats:

{
"message": "b042e7c3ee5a - Deleting deployment"
}
{
"message": "b042e7c3ee5a - Delete request will be processed soon"
}

Graceful termination#

A SIGTERM signal is sent to your application container when a deployment is stopped. It is not mandatory to handle it, but if you do so, you can choose the amount of time needed to do stuff before the container is killed. You can set it with the termination_grace_period_seconds parameter in your application version (see API Doc).

When this amount of time is reached, or the handling has been done, a SIGKILL signal is sent and the container is killed and no longer accessible.

Here is a small example with a Python application. Before serving our app, we init a handler that will call a POST URL coming from the ENV variable. Once the call is done, we consider that our app can be terminated safely.

if __name__ == '__main__':
def sigterm_handler(*args):
try:
print("SIGTERM received, server will shut down soon.")
post_url = os.environ.get('ARBITRIUM_SIGTERM_POST_URL')
request_id = os.environ.get('ARBITRIUM_REQUEST_ID')
# Do some logic, send webhook, save data, etc
if isinstance(post_url, (str, bytes)):
requests.post(post_url, json={'request_id': request_id})
except Exception as e:
print(e)
print("Init SIGTERM handler")
signal.signal(signal.SIGTERM, sigterm_handler)
serve(app, host='0.0.0.0', port=5000)

You can try yourself by using our Tutorial application with a Docker tag >=0.2.22 and adding the ARBITRIUM_SIGTERM_POST_URL in the application ENV. When you will delete your deployment, it will make a POST on this URL, and you will be able to see the request ID of your deployment in the body of the request.

Deployment Possible Status#

When you get your Deployment context, the possible statuses are these:

INITIALIZING - Arbitrium is creating the deployment.

SEEKING - Arbitrium is fetching information about the IP list provided.

SEEKED - Arbitrium has finished fetching information.

SCANNING - Arbitrium is scanning for the best and fastest location available for all players ready for a match.

DEPLOYING - Arbitrium deploys the application or game server on a location access point.

READY - The game is deployed, and the match has started. Let’s play!

TERMINATED - The deployment is finished, and the server is no longer on our access point.

ERROR - Something went wrong with the request. The server may be running and operational, but don’t take it for granted.

All statuses are safe to make a delete request. However, they will not be processed the same by Arbitrium. You can check the delete deployment call flow for further explanation.

Get Deployment Context from a Running Deployment#

When you create an App Version, you can specify the Inject Context Option from the Dashboard or put the "inject_context_env": true in the Body of the API Call.

This option will inject environment variables inside your deployment to get external context information of your running deployments like Port Mapping and External IP.

ARBITRIUM_CONTEXT_URL \= “The URL to make the GET request.”

ARBITRIUM_CONTEXT_TOKEN \= “The Token Generated to put in Authorization Header.”

Here is an example that you can run from inside your deployment.

curl --location --request GET "$ARBITRIUM_CONTEXT_URL" --header "authorization: $ARBITRIUM_CONTEXT_TOKEN"

The response will be under this format.

{
"request_id": "abc123",
"public_ip": "100.10.0.85",
"status": "Status.READY",
"ready": true,
"fqdn": "abc123.test.edgegap.com",
"ports": {
"80": {
"external": 11111,
"internal": 80,
"protocol": "TCP"
}
},
"location": {
"city": "Montreal",
"country": "Canada",
"continent": "North America",
"administrative_division": "Quebec",
"timezone": "Eastern Time",
"latitude": 45.508888,
"longitude": -73.561668
},
"tags": ["example", "production"]
}

Stop a Deployment from a Running Deployment#

Every deployment done by Arbitrium has environment variables injected during the boot up that allow the running instance the possibility to stop itself with a specific unique URL and Token generated for his deployment.

ARBITRIUM_DELETE_URL \= “Custom URL to do the DELETE Request. “

ARBITRIUM_DELETE_TOKEN \= “Token Generate for the Deployment to be put in the Authorization Header.”

Here is an example that you can run from inside your deployment.

curl --location --request DELETE "$ARBITRIUM_DELETE_URL" --header "authorization: $ARBITRIUM_DELETE_TOKEN"

If successful, the response will be under this format with a 200 Status Code.

{
"message": "Instance 93924761ccde will be deleted"
}

You can check this section to learn about the graceful termination of your deployment.