Last Updated: 7/23/2021, 7:33:01 AM

# Armada

# Overview

# What is Armada?

Armada is a dynamic game server manager that utilizes a mixture of bare metal and cloud services to help reduce hosting costs for you, while still maintaining the best performance and experience for your players. Armada allows you to have multiple fleets of servers, which can be spread across different regions, providers, or infrastructure types.

armada

# Advantages of Armada

Armada allows you to take advantage of several features designed to ensure your players have the best gaming experience possible.

Provider-agnostic approach - Armada allows you to choose between multiple providers, depending on your hardware requirements. You can decide to have 100% of your servers in AWS cloud if you have free credits, or you can choose to have 90% of your game servers hosted using dedicated bare metal with the last 10% being scaled into cloud if you wish to bring your costs down. Armada allows you to pick and choose exactly what hardware you want, from whoever you want without any limitations!

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

Multi-region hosting - Armada has been designed 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. Mix and match providers, hardware types, and regions based on your player demands.

Integrated matchmaking and lobby - Armada connects directly with AccelByte’s Matchmaking and Lobby services to provide geolocation support, so that you can match players in the same region for optimal player experience. If you already have a matchmaking and lobby service you prefer, we can help you integrate Armada with that instead of using AccelByte’s.

Unsure what hardware to use? - If you are unsure what dedicated bare metal provider to use, what regions you want or you have only ever used cloud, the Armada team is here to help! We can advise on everything from specific hardware types to use, how your game servers will perform, and which regions will be best to support all your players. We have partnered with a number of dedicated hardware providers who already cover the majority of popular regions across the globe.

# Get Started with Armada

Before we can get you set up with Armada, our team will need some information about your game and players. This will help us accurately price out the hardware you’ll need, as well as make sure your hosting covers the right locations to give your players the best experience possible.

Player counts - For us to provide the best experience possible, we need to know some information about your players. First, we need to know the maximum number of players that can connect to your game server. We also need to know what your estimated average number of players will be over the course of a month, as well as the estimated peak number of players. With these player numbers, we can ensure that you have enough bare metal to cover the average player count, as well as ensuring that you can scale effectively into cloud to meet peak demand when things get busy.

Player locations - With Armada, you can host your game server sessions pretty much anywhere in the world. While this is a great achievement, we are also aware that some games are more popular in different parts of the world than they are elsewhere. It is important for us to know where the majority of your players are based, so that we can deploy bare metal and cloud instances as close to them as possible. The closer the hardware, the better the performance. Your players deserve the best possible experience every time they play your game!

Game server resource requirements - Every game server that you deploy will have some form of CPU and RAM usage. In order to provide the best possible performance for your players, Armada needs to know what the worst case scenario is in terms of resource usage requirements. To do this, you will need to run a session with the maximum number of players connected, using the most resource intensive map and game mode possible. During this session, you should record the CPU, RAM and network usage over a full match.

Once you have this data, the Armada team can then run it through our calculator. This will tell us exactly how many game server sessions we can safely fit on your bare metal and cloud server instances without impacting the game server performance. More importantly, it will also allow us to calculate the best distribution of bare metal and cloud to ensure you always have capacity for your players as well as lowering the cost for hosting.

# How It Works

# The Basics of Server Management

For each multiplayer game that you wish to host using Armada, you will need a fleet of bare metal servers as well as access to some virtual cloud instances. This will ensure that you have the capacity needed to service your players.

As Armada is completely provider agnostic, you can source hardware from different providers depending on your needs, as well as utilize any and all cloud providers. What’s more, if you are unsure what providers to use or do not have the ability to organize your own hardware, the Armada team can source and deploy this for you using our recommended providers.

Each bare metal server and virtual cloud instance will have your multiplayer game server deployed to it so that when players make a matchmaking request, Armada will be able to start an instance based on the required location and instance priority.

Armada has a powerful priority system that allows you to specify what hardware or instance types should be used first to service your players. You may have a large fleet of bare metal servers, and also a bunch of credits provided to you from one of the many cloud providers. With Armada you can choose if you want to burn through your credits first, or place your players on the bare metal capacity until the point where they are completely full and then burst into the cloud. The choice is entirely yours!

Armada works by connecting dedicated servers from different providers. The diagram below shows the flow and different services involved in connecting these servers. Any dedicated servers required are hosted directly on bare metal or cloud infrastructure that is specific to your game.

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

  1. 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

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

armada

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

armada

  1. 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

  2. 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

  1. 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

# Set the Priority for Server Types

Armada is able to utilize multiple bare metal providers as well as cloud. For this to work, each provider you use must be given a priority value, which can be changed anytime from the Admin Portal. These priority values determine which servers Armada fills up first before moving to other providers.

  1. In the Admin Portal, scroll down to Dedicated Server Management and click on Configurations.

    armada

  2. On the Configurations page, scroll down to the Providers section. From here you will see your currently configured providers and their priority. Setting the priority value lower than other providers will result in Armada using them first. In the example below, AWS will be utilized before Nitrado.

    armada

  3. To change the priority of your providers, click and drag to rearrange the providers into the desired priority order. If a provider has the priority of 0, it will be used before a provider with the priority of 1, and so on.

# Reserve 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 (opens new window) 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} (opens new window) endpoint.

# Claim a Server

  1. Use the POST ​/dsmcontroller​/namespaces​/{namespace}​/sessions​/claim (opens new window) 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

  • 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 (opens new window) for Armada.
  • Check out our Matchmaking tutorial to learn more about our matchmaking service.