Armada

Overview

Armada is a dynamic game server manager that can balance low hosting cost with high performance. With Armada you can have different fleets of servers for different regions, and each fleet can be made up of a mix of cloud, bare metal, and local servers. These fleets can be used to maximize your global reach while only paying for the hosting you need.

Armada offers several advantages for game developers, including:

  • Link multiple server providers to give your game both the high availability of cloud hosting and the reduced cost of bare metal machines. This also allows you to shop around for the best price, without being tied to only one hosting provider.

  • Cost-aware scaling ensures that hosting costs are taken into account when scaling up or down. When scaling up, Armada ensures the bare metal machines are filled before bursting into the cloud. And when scaling down, Armada looks for opportunities to reduce the load on the cloud machines without impacting performance or player experience.

  • Multi-region hosting for greater global coverage and better game performance across more regions. With Armada you aren’t tied to one hosting solution, which means you can make sure that your hosting providers cover each other’s blind spots.

  • Integrated Matchmaking and Lobby services provide geolocation support, so that you can match players in the same region for optimal player experience. But if you have a matchmaking and lobby service you already love, we can help you integrate Armada with that instead of using ours.

Armada consists of a Dedicated Server Manager (DSM) and Dedicated Server Manager Controller (DSMC). Our DSM uses Agones to manage dedicated servers, which are tracked by our DSMC.

How It Works

The Basics of Server Management

Armada works by connecting servers from different providers, as seen in the diagram below:

armada

How Our Matchmaking Service Uses Armada

Below is a diagram of how Armada can work with our Matchmaking service.

armada

  1. The player connects to the Lobby service through a websocket connection.
  2. The player sends a matchmaking request to the Lobby service.
  3. The Lobby service will act as a proxy and forward the incoming message to the Matchmaking service.
  4. When a match is found, the Matchmaking service will notify the Lobby service.
  5. The Lobby service will send a request to the DSM to create a new game session with the match details.
  6. The DSM will check whether a DS pod is available.
  7. If there’s an idle pod available, the DSM will send a claim request to the DS Fleet (Agones).
  8. If there are no idle pods available, the DS Fleet (Agones) will spawn a new DS pod.
  9. The Agones controller claims the pod and assigns the game session to it.
  10. After the process is complete, the DSM notifies the Lobby service that the session has been created, and sends the DS details.
  11. The Lobby service forwards the DS details to the game client.

Enable Per-Version Deployment Override

Enable per-version deployment override is a feature for a game developer to be able to override an existing deployment’s configurations based on the game version. See the diagram below to know how it works.

armada

Based on the diagram above, the override will be activated depending on the version requested by the client.

  • Default Deployment will be used when the client is not specifying the version or the same version as the one in the deployment.
  • Override with specified Deployment will be used when the client requests a version that’s already configured in the override section.
  • Override with Default Deployment will be used when the client requests a version that’s not in the configuration or in any of the overrides. But the version is overridden since the logic still depends on whether the allowed version override is ticked or not.

Tutorials

Upload a New Server with DS Uploader

You can upload a new server using our DS Uploader, which you can download from our Nexus repository. Follow the directions below to download the DS Uploader and upload a new server image.

Download DS Uploader

  1. DS Uploader can be downloaded from our Nexus repository. To make it easy to find, run a search using ds-uploader-prod/ as the keyword.

  2. Browse the list of search results that appears until you find the latest version of the uploader. There are three files you need to download to run DS Uploader, as seen in the image below:

    armada

  3. After downloading these files, open the CLI in the folder that contains ds-uploader and the game server, and run the following command:

    windows-amd64.exe syncFolder --hostname=https://demo.accelbyte.io --namespace=lightfantastic --id=d197386e4be142cd819e4347bde08e17 --version=0.0.6b --command=LOCALDS.sh -p lightfantastic -b "justice-ds-upload-service-demo" -d s3FauzanLightfantastic

    Here’s a description of each flag you’ll find in the command:

    Flag

    Description

    --hostname

    Hostname (e.g. https://demo.accelbyte.io)

    --namespace

    Namespace where the config belongs

    --id

    DS Uploader Client ID (e.g. d197386e4be142cd819e4347bde08e17) Note: Input the Client Secret if the Client ID isn't public

    --version

    Game Server Version (e.g. 0.0.6b)

    --command

    Game Server Command (e.g. LOCALDS.sh) This can be found inside the game server directory

    -p

    Game Server Local Path (e.g. lightfantastic) You can use either a relative or absolute path) 

    -b

    S3 bucketname (e.g. justice-ds-upload-service-demo)

    -d

    S3 directory (e.g. s3FauzanLightfantastic)

Add a Dedicated Server Configuration

After you upload a new server image, you can configure that server and its deployment in the Admin Portal.

Configure the Dedicated Server

  1. In the Admin Portal, choose the namespace for the game for which you want to create the configuration.

    armada

  2. Go to the Dedicated Server Management section and open the Configurations menu.

    armada

  3. In the Server Configurations menu, click Add Configuration.

    armada

  4. After the Add Configuration form appears, click the Add button next to Image Versions. Then fill in the form with the required information:

    • Input the Version field with the version of your dedicated server build with the appropriate format, as seen in the image below.
    • Input the Image field with the dedicated server image you received after uploading your build. This also needs to follow the formatting rules shown in the image.

    armada

    Click the Add button to add the image version. Then, continue to fill in the Configuration Form with the required information.

    • Input the Port where your DS listens for a connection.
    • Input the minimum number of DS allowed to spawn, whether active or idle, in the Min. Count field.
    • Input maximum number of DS allowed to spawn in the Max. Count field.
    • Input the default number of ready DS in the Buffer Count field. The DSM will spawn idle DS according to the buffer count. This ensures that there will always be a DS ready for players to use during matchmaking.
    • Input the minimum number of cores needed by the dedicated server with the appropriate format in the CPU Request field.
    • Input the minimum amount of memory needed by the dedicated server in the Memory Request field.
    • Input the CPU Limit field with the maximum number of cores that can be used by the dedicated server.
    • Input the Memory Limit field with the maximum amount of memory that can be used by the dedicated server.

    The following fields are optional:

    • Input the Creation Timeout field with the time limit for the dedicated server to register itself to the Lobby service after being spawned. If the time limit is exceeded, the DSM will remove the DS.
    • Input the Claim Timeout field with the time limit for the Lobby service to claim a DS after being requested. The DSM will remove the DS if the time limit is exceeded.
    • Input the Session-Timeout field with the time limit for an active session to finish. The DSM will remove the DS if the time limit is exceeded.
    • Input the Heartbeat Timeout field with the time limit for a registered DS to call the heartbeat endpoint as an indicator that the DS is active. If the DS is unreachable it will be marked as such by the DSM.
    • Input the Unreachable Timeout field with the time limit for an unreachable dedicated server to call the heartbeat endpoint. If the time limit is exceeded, the DSM will remove the DS.

    Note:

    • The Max. Count value should not be less than Min. Count value.

    • The values for CPU Request, Memory Request, CPU Limit, and Memory Limit must be formatted in Kubernetes, e.g. CPU of 1000m is equal to 1 core and Memory of 512Mi is equal to 512MB.

      armada

  5. Click Add to complete the configuration.

Configure the Server Deployment

You can add another deployment with a different pod, version, and server region. Follow the steps below to add a new pod configuration.

  1. In the Configuration Details window of the Admin Portal, go to the Deployments tab and click Add.

  2. After the configuration form appears, fill in the fields using the appropriate format.

    • Input the Name of the deployment configuration. You should use a descriptive and readable name.
    • Select the Version of the image you want to deploy.
    • Select the Pod Configuration you want to use for this deployment.
    • Choose the Region where the DS will be deployed.
    • Input the Min. Count with the minimum number of DS allowed to spawn, whether active or idle.
    • Input the Max. Count with the maximum number of the DS allowed to spawn.
    • Input the default number of ready DS in the Buffer Count field. The DSM will spawn idle DS according to the buffer count. This ensures that there will always be a DS ready for players to use during matchmaking. Note: The Max. Count value should not be less than Min. Count value.

    armada

  3. Click Add to complete the configuration.

    armada

Verify the Dedicated Server Configuration

After you create a Dedicated Server Configuration, you should verify that the server has spawned correctly. In the Admin Portal, go to Dedicated Server Management and choose Servers.

armada

On the Servers page you’ll see the elements listed below:

  • Local Server shows the number of dedicated servers that run on your local computer. This type of dedicated server is used to perform testing before a game is published.

  • Server Overview shows the number of dedicated servers you have configured, from both AWS and GCP hosting providers. You can see the details of each server by clicking on the three dots next to the desired server and selecting View.

    armada
    armada
    armada

  • Available Regions shows the number of registered regions that you can run servers in. On this page you can see the status of each region.

    armada

  • Total Sessions shows the number of player sessions currently active. On this page you can see a list of players currently playing and the servers they’re using.

    armada

  • You can see detailed information about the servers and players by clicking on the three dots next to the desired session and selecting View.

    armada

Reserving a Server Using the API

When you use our Lobby service with Armada, it will create sessions and reserve servers for those sessions for you. If you prefer to use your own lobby, you can communicate with Armada via REST API to create a session and then reserve a server for that session. To do so, follow the steps below.

Create a Session

  1. Use the POST ​/dsmcontroller​/namespaces​/{namespace}​/sessions endpoint to create a session.
  2. Input the Namespace field with the game namespace.
  3. Fill out the Request Body.
    • Input the Game Mode taken from the matchmaking rules, e.g. 1v1, 3v3.
    • Input the Party ID with the ID of the party the session is for, in UUID format.
    • Input the Party Members with the user IDs of the players in the party. The user IDs should be in UUID format.
    • Input the game namespace into the Namespace field.
    • Input a Session ID using UUID format.
    • Input the game client version in the Client Version field.
    • Input the server configuration needed for the session in the Configuration field. If left empty, the default server configuration will be used.
    • Input the Pod Name. This field is only used for local servers, for other servers leave this blank.
    • Input the Region of the DSM.

Upon successful request, a new session will be created.

You can then check on the status of your session using the GET ​/dsmcontroller​/namespaces​/{namespace}​/sessions​/{sessionID} endpoint.

Claim a Server

  1. Use the POST ​/dsmcontroller​/namespaces​/{namespace}​/sessions​/claim endpoint to claim a server for your newly created session.
  2. Input the Namespace field with the game namespace.
  3. Fill out the Request Body.
    • Input the session’s Session ID.

Upon successful request, the DS will be claimed by your session.

Enable Per-Version Deployment Override

Override Deployment in the Default Deployment

  1. In the Admin Portal, go to Dedicated Server Management in the sidebar and open the Configurations menu.

    armada

  2. In the Server Configuration, choose the Server Configuration that you want to see the deployment and click View.

    armada

  3. On your server configuration, scroll down and switch to the Deployment tab.

    armada

  4. Choose one of the Deployments by clicking the three-dots button and click View.

    armada

  5. In the Deployment Details, there will be an option to enable or disable the Overriding Session.

    armada

    • If the enable overriding is ticked, it means that the client requests the version that isn’t listed in the override deployment list. The override will use the root deployment but the version will follow the version requested by the client.
    • If the enable overriding version is not ticked, if the client specifies a version that is not listed in the override deployment then it will be used as the root deployment and ignoring the version that the client requested.

    Note that in the Default Deployment, you will not be able to edit or update the region.

Override Deployment in a Specific Deployment

  1. In the Admin Portal, go to Dedicated Server Management in the sidebar and open the Configurations menu.

    armada

  2. In the Server Configuration, choose the Server Configuration that you want to see the deployment and click View.

    armada

  3. On your server configuration, scroll down and switch to the Deployment tab.

    armada

  4. Choose one of the Overridden Deployment and click the three-dots button.

    armada

  5. In the Deployment Details, you can enable or disable the overriding version.

    armada

  6. To add more specific deployment, go to the Override Deployment section click the Add button.

    armada

  7. A form will appear and you need to fill in the specific deployment details.

    armada

    • Select the Deployment Version

    • Select the Pod Configuration

    • Select the Region of the deployment

      For the Min Count, Max Count, and Buffer, be sure to input the accurate value based on your server capabilities. If you submit a value that is too large, your server might crash.

    • Input the minimum number of DS allowed to spawn, whether active or idle, in the Min. Count field.

    • Input maximum number of DS allowed to be spawned in the Max. Count field.

    • Input the default number of ready DS in the Buffer Count field. The DSM will spawn idle DS according to the buffer count. This ensures that there will always be a DS ready for players to use during matchmaking.

      When you’ve done, click Add and your override deployment will be added to the list.

Historical Logs

In the historical log, you can download the DS log even when the server has been terminated. That way, you can still debug the DS when it gets terminated. After the DS is terminated, you just need to wait around 5 minutes or less before it appears on the Historical Log then, you can download them as TXT files.

Download Historical Logs

  1. In the Admin Portal, go to Dedicated Server Management in the sidebar and open the Historical Logs menu.

    armada

  2. If you’re logged into the Publisher Namespace, you can see all of the DS Log from all namespaces. Currently, it’s only limited to the searching and deployment filter, we will do the namespace filter in the upcoming update. Choose the log you want to download and click View.

    armada

    If you’re logged into Game Namespace, you can only see the DS of your Game Namespace. Choose the log you want to download and click View.

    armada

  3. The Historical Log Details appear. Click the Download Logs button to download the server log.

    armada

Related Concepts

  • If you’re interested in Early Access to Armada, we’d love to talk to you. Shoot us an email about your project to get started.
  • Take a look at the API Docs for Armada.
  • Check out our Matchmaking tutorial to learn more about our matchmaking service.