Migrate from Armada to AMS

Last updated on March 13, 2024

Introduction

AccelByte Multiplayer Servers (AMS) is the next generation dedicated server management system from AccelByte Gaming Services (AGS). It is built with the experience learned from years of managing dedicated servers and designed to minimize migration efforts from the previous version of the AGS dedicated server management system, Armada. This migration guide will help you migrate from Armada to AMS.

Prerequisites

• You have a familiarity with AMS.
• You have AMS activated.
  • If you are an AGS Starter user, you can activate AMS by logging in to your AGS Admin Portal and going to AccelByte Multiplayer Servers > Setup AMS Account.
  • If you have your own dedicated AGS environment, contact your AccelByte account manager to add AMS to your existing contract and have it enabled for your environment.

Armada and AMS key differences

This section helps you mentally map the Armada concepts and configuration to their equivalents in AMS.

Configuration

The primary configuration entity in AMS is the Fleet. A Fleet represents a collection of dedicated game servers (active or idle), all running the same dedicated server image, serving game sessions to your players. You can use different Fleets to manage different game modes, deploy a new version of a dedicated server without disrupting play, and more.

AMS Fleets replace your Armada Server Configurations. Unlike Armada Server Configurations, each Fleet is configured with a single dedicated server image and represents a single deployment configuration (e.g., min dedicated server count, max dedicated server count, buffer dedicated server count, dedicated server timeouts, and one or more regions). Instead of having to estimate your dedicated server resource requirements and letting Armada pick the instance type and dedicated server packing, AMS Fleets allows you to pick the instance type for your dedicated server and how many dedicated servers you want AMS to pack onto each instance.

Dedicated server images are a first-class entity in AMS. You upload and manage them independently, and can associate them with one or more Fleets as needed.

Dedicated server runtime

While both Armada and AMS let you test and debug your dedicated servers on your local workstation, AMS also provides the AMS Simulator that lets you test and verify how your dedicated server reacts to the events that originate from AMS. Getting all of your basic testing and validation done using amssim and a local dedicated server is a great way to use AMS before you start deploying your dedicated server fleets.

Both Armada and AMS use container technology to run the dedicated server, but AMS runs all dedicated servers as processes in a container with the AMS Watchdog as the root process. The AMS Watchdog manages the lifecycle of the dedicated servers running on a given AMS instance, and requires every dedicated server to connect back to it via a WebSocket. For example, when a dedicated server terminates, the Watchdog will start a new dedicated server to replenish the dedicated server count.

The AMS Watchdog also acts as a proxy for AGS and will send any control signals from AGS to the running dedicated servers. The Watchdog provides unique configuration to each dedicated server via command line arguments, including unique socket ports for networking and a unique file directory for writing any artifacts for that particular invocation of a dedicated server.

Set up an AMS account

An AMS account lets you share resources like dedicated server images, performance metrics, and billing information across multiple AGS namespaces and environments. Read more about resource sharing and plan how you want to use AMS accounts to manage resource sharing across your AGS namespaces and environments.

For example, a common pattern is to create and manage a separate AMS account for each game you are developing. This allows you to share your dedicated server images across your AGS Dev, Staging, and Production environments, making it easy to support a dedicated server image build, test, and promotion pipeline.

Once you have a plan, follow our How-to guides for creating or linking AMS accounts as needed.

Update your dedicated server code

You will need to update your dedicated server code and configuration to integrate with AMS. If you are using Unreal Engine, we strongly recommend you use the AGS Online Services Subsystem (OSS) SDK to make it easier to integrate your dedicated servers with AMS.

1. Set up your development environment for your dedicated servers to use AMS.
2. Update the code to register a dedicated server to AMS.
   • You will notice that compared to when you registered your dedicated server to Armada, the Ready API no longer requires you to handle the response and potentially retry the call. This is because on AMS, the Ready signal is sent to the AMS Watchdog on the local instance instead of a remote service, and the watchdog handles the retries with the remote service on the dedicated server's behalf.
   • You will also notice that there is no SendShutdownToDSM() API for AMS. Instead, the AMS Watchdog is able to automatically detect when your dedicated server has exited and make the corresponding update to the AMS control plane.
3. Program your dedicated servers to listen to the drain signal; skipping this means you are spending more money on dedicated servers than you need to.
4. Test and debug your dedicated servers locally using the AMS Simulator before you upload your dedicated server image to AMS.

Upload dedicated server images to AMS

Now you need to upload the dedicated server images you want to use to AMS using the AMS CLI.

1. Download CLI Tools from the Admin Portal.

2. Upload a dedicated server build using the AMS CLI. You must create an IAM Client for uploading your dedicated servers. Your IAM Client should look like this:

   

Configure quality of service regions

AMS lets you configure the regions you want to include in your players' quality of service (QoS) evaluation. Enabling QoS for a region will include that region in the available regions that your game client will ping to choose the region with the best latency for each player via our SDK. To configure the QoS regions for your namespace, visit the AMS Fleets page in the AGS Admin Portal and toggle them to Enable/Disable for each region in the Region List:

note

The QoS region configuration applies to the whole namespace.

Create AMS Fleets

You will need to create an AMS Fleet for each active Deployment you want to carry over from Armada. Most of the Fleet configuration settings will look familiar, with a few notable exceptions:

• You will select only one dedicated server image for each Fleet from the global list of dedicated server images you have uploaded to your AMS account.
• You will specify the type of instance AMS will use to run your dedicated servers for each Fleet.
• Instead of configuring the size of the pod needed to run your dedicated server, you will specify the number of dedicated servers that you want AMS to run on each virtual machine (VM) in the Fleet.

You can look at the list of dedicated servers for any fleet by clicking on the fleet name in the Fleet List. The fleet details page allows you to view or edit your fleet's configuration, and also provides a history of dedicated servers for this fleet for the last 30 days.

Configure session templates to use AMS dedicated servers

Claim keys are introduced in AMS that let you configure your game sessions to claim dedicated servers from one or more AMS Fleets. Claim keys make it easy to support special dedicated server deployment workflows such as blue-green deployments or canary fleet deployments. Read Dedicated server claim flow for more details.

To use claim keys, you need to:

1. Assign claim keys to a fleet
2. Use AMS with the session service

What's next?

• Check out our Byte Wars tutorials (for Unreal or Unity) to learn how to integrate AGS and AMS into a sample game.
• Learn more about the Lifecycle of a dedicated server under AMS.
• Check out an Example use of claim keys to see how they help you manage new dedicated server version rollouts and canary deployments.
• Once you have everything working and your players are getting dedicated servers from AMS, don't forget to deactivate your Armada deployments to save money.
• Contact your AccelByte Account Manager or Technical Producer and let them know when you've completed the migration so we can remove Armada from your environment.