How containers work in Amazon GameLift

This documentation is for a feature that is in public preview release. It is subject to change.

Amazon GameLift container fleets are designed to provide flexibility in how you deploy and scale your containerized applications. It uses the Amazon Elastic Container Service (Amazon ECS) to manage task deployment and execution for your Amazon GameLift fleets. This topic describes the basic structural elements for running containers on an Amazon GameLift managed fleet, illustrates common architectures, and outlines some core concepts.

Container fleet components

Fleet

A container fleet is a collection of Amazon EC2 instances, managed by Amazon GameLift, that run your containerized game servers. When you create a fleet, you configure how your container architecture and game server software is deployed to each fleet instance. You can deploy a container fleet to a single AWS Region or to multiple geographic locations. You can use Amazon GameLift manual or automatic scaling tools to scale a container fleet's capacity to host game sessions and players.

Instance

An Amazon EC2 instance is the virtual server that provides compute capacity for your game hosting. With Amazon GameLift, you can choose from a variety of instance types. Each instance type offers a different combination of CPU, memory, storage, and networking capacity.

When you create a container fleet, Amazon GameLift deploys instances based on the instance type you choose and your fleet configuration. Each deployed fleet instance is identical and runs your containerized game server software in the same way. The number of instances in a fleet determines the fleet's size and game hosting capacity.

Container group

Amazon GameLift uses the concept of a container group to describe and manage a set of containers. A container group is similar to a container "task" or "pod". Within each container group, you can define how containers share available CPU and memory resources. You can also set up dependencies between containers and manage the container group's life cycle.

Container groups can replicate across each fleet instance to optimize resource uses. You can manage replication by setting a container group's scheduling strategy, as follows:

• Replica container groups manage the containers that run your game server application and supporting software. All container fleets must define a replica container group. A replica group might have multiple copies on each fleet instance, depending on the container group's requirements and the resources of the instance type in use. All containers in the replica group automatically scale together across an instance.

• Daemon container groups, which are optional, might be useful for running background services or utility programs, such as for monitoring. You game server software doesn't directly depend on processes in a daemon group. Daemon container groups aren't replicated--each fleet instance has at most one copy of the daemon group. This means that containers in a daemon group don't scale across a fleet instance along with containers in a replica group.

A container fleet must have one replica container group and can optionally have one daemon group.

Container

The container is the most basic element of a container-based architecture. It consists of a container image with software executables and dependent files. When you define a container to use with Amazon GameLift, you configure how the software runs in the container.

Each container group in a container fleet must have one container that's designated "essential". An essential container drives the lifecycle of a container group. If the essential container fails, the entire container group restarts.

Container types include:

• Essential replica container includes everything you need to run your game server processes and host game sessions for players. It includes your game server build, which is integrated with the Amazon GameLift server SDK, and dependent software. It also includes the Amazon GameLift Agent, which manages the lifecycle of your game server processes. A fleet's replica container group has exactly one essential replica container.

• Non-essential replica containers, also called "sidecar" containers, run software to support your game server application. Using a sidecar container lets you run and scale supporting software alongside your game servers but manage as separate containers. If this type of container fails, only the container itself restarts; the container group isn't impacted.

• Daemon containers run a daemon service to manage background processes. A common use for a daemon container is to run an Amazon CloudWatch (CloudWatch) agent to collect metrics, logs, and traces for your containers. Daemon containers can be essential or non-essential depending on when a container failure must result in a container group restart.

Compute

A compute is a fleet hosting resource that's registered with the Amazon GameLift service and is able to communicate with the service. In a container fleet, a compute is a container with a process that manages the compute registration process. In a container fleet's essential replica container, the Amazon GameLift Agent automatically registers this container as a compute.

Common architectures

The following diagram illustrates the simplest container fleet structure. In this structure, each instance in the fleet maintains one copy of the replica container group. The container group has a single essential container that runs the Amazon GameLift Agent, the game server application, and all supporting software for hosting game sessions. The Agent implements fleet-specific instructions to run three server processes concurrently. Because there's one replica container group per instance, each fleet instance runs three server processes concurrently.

This second example illustrates a more complex container fleet design. In this example, the fleet has a replica container group with multiple containers and a daemon container group with one container. The fleet configuration puts three copies of the replica container group on each fleet instance. The daemon container group is never replicated.

Each set of replica group containers in the have three copies on each instance. In each essential replica container, the Agent is instructed to run two server processes concurrently. As a result, each fleet instance runs six server processes concurrently (two processes in each of the three essential replica containers).

Core concepts

This section summarizes how Amazon GameLift implements some basic container concepts. For instructions on how to work with container fleets, see the relevant topics in this guide.

Container group packing

When developing your container structure for deployment in a container fleet, a common goal is to optimize your use of available computing power. To achieve this goal, find the highest number of replica container groups you can place on a fleet instance without impacting game server performance.

Amazon GameLift can help you do this. It calculates a maximum number of replica groups per instance, based on the following information:

• The fleet's instance type and the CPU and memory resources available.

• The CPU and memory requirements that you set for all containers in your replica group.

  The CPU and memory requirements that you set for all containers in a daemon group, if there is one.

• Resources reserved to manage containers and other critical applications on each instance.

When you create a container fleet, you can choose to use the calculated maximum number or you can override the calculated number by specifying a desired number. As a best practice, experiment with your containerized game server software to determine accurate resource requirements. Use this data to find an optimal packing strategy for game server performance.

Game servers and the Amazon GameLift Agent

When you build your essential replica container, you package your game server software and the Amazon GameLift Agent together in the same container image. This on-compute agent controls the lifecycle of game servers in the container. In each replica container group, the essential replica container runs the Agent and all game server processes.

The Amazon GameLift Agent executes instructions in the container fleet's runtime configuration. The runtime configuration identifies (1) the executable to start running, (2) an optional set of launch parameters, and (3) the number of processes to run concurrently. A runtime configuration can have instructions for multiple different executables. At least one instruction must be for the game server executable. For example, a runtime configuration might instruct the agent to maintain 10 processes of your game server executable for production use, 1 process of the same executable with special launch parameters for testing, and 1 process for a logging utility.

You can modify a fleet's runtime configuration at any time. The Amazon GameLift Agent periodically requests updates from the service. When an updated runtime configuration is available, the Agent receives it and begins implementing the instructions. Actions might include adding or shutting down server processes.

The Amazon GameLift Agent is an open-source version of the on-compute agent that Amazon GameLift uses for managed EC2 fleets. This guide provides instructions on how to build the Agent from source and build it into a container image. The Agent handles the following tasks:

Server process management:

• Start, shut down, and replace server processes based on the runtime configuration.

• Shut down server processes when they don't activate in time.

• Report to Amazon GameLift when a server process terminates.

• Emit fleet events for server processes.

Container management:

• Shut down server processes in response to prompts from Amazon GameLift.

• Report container health.

Log uploading tasks:

• Upload game session logs to a designated Amazon S3 bucket.

• Upload on-compute agent logs to a designated Amazon S3 bucket.

Scaling fleet capacity

Fleet capacity measures the number of game sessions that the fleet can host at any one time. You can also measure capacity based on the number of players the fleet can support simultaneously.

To increase or decrease a fleet's hosting capacity, you add or remove fleet instances. A container fleet's packing strategy determines how many game sessions run concurrently on each fleet instance. This number tells you the number of game sessions (and player slots) you add or subtract when you increase or decrease the fleet capacity.

With container fleets, you can use any of the scaling methods provided by Amazon GameLift. These include:

• Set fleet capacity manually by setting a specific desired fleet instance count.

• Set up automatic scaling by targeting a desired buffer of available instances (target tracking). This method automatically maintains a set of idle hosting resources so that incoming players can always get into games quickly. As player demand increases or decreases, the size of this buffer is continually adjusted.

• Set up automatic scaling with custom scaling rules (advanced feature).

Game client/server connections

Managed EC2 fleets and container fleets handle connections between game clients and cloud-hosted game servers in a similar way. When Amazon GameLift creates a new game session, the service communicates the game session’s connection information. Game clients use the information to connect directly to the game server that’s hosting the game session. For all types of fleets, connection information consists of an IP address and port assignment.

When creating a container fleet, you define two sets of port ranges. First, you define a range of external-facing connection ports that allow game clients to connect to a game. Second, you define a set of internal-only container ports, which are assigned to each game server process that's running in the container. Amazon GameLift dynamically maps the internal container ports to external connection ports to give players access to games. This approach provides an additional layer of security by protecting your game servers from direct access to the container ports.

When defining port ranges for a container fleet, you must provide ranges with enough ports to accommodate all server processes that run concurrently across the containers on an instance.

For additional control, you also set inbound permissions for a fleet. Inbound permissions determine which connection ports are open for incoming traffic. You can change a fleet's inbound permissions at any time. With inbound permissions you can quickly shut down all connection ports, open some, or open all as needed.