Architect your fleet container structure Set resource limits Designate essential containers Configure network connections Set up health checks for containers Set container dependencies Configure a container fleet

Design an Amazon GameLift container fleet

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

These topics present the key decisions you’ll make when setting up an Amazon GameLift container fleet. Your decisions impact how you configure settings for containers, container groups, and fleets.

Architect your fleet container structure

As a first step, identify the software and resources needed to host your game server, including the following:

Your game server application. The application must be integrated with Amazon GameLift functionality for hosting, including the server SDK version 5+. See Integrate your game with Amazon GameLift.
The Amazon GameLift Agent. This on-compute agent maintains communication with the Amazon GameLift service and manages the lifecycle of all game server processes. For more details, see Game servers and the Amazon GameLift Agent.
Additional software and resources as needed. This might include software needed to run your game server applications. Common supporting software is used for logging and monitoring, security, content delivery, and data synchronization.

Next, decide how to structure your software and resources for an Amazon GameLift container fleet. Amazon GameLift uses container groups to organize containers. A fleet always has one replica container group and can optionally have a daemon container fleet. For more details, see Container fleet components.

Start by designing your replica container group. Consider the following guidelines:
- Bundle your game server application and the Amazon GameLift Agent into the same container. Make this container the replica group’s only essential container.
- Organize all other software for your game server into containers. You might choose to put everything into a single container in the replica group. Or you might choose to create one or more sidecar containers. Some reasons to use sidecars include:
  - To set up a startup/shutdown sequence for individual software. You can achieve this by placing software in separate containers and set up dependencies between them.
  - To set container-specific limits for memory and CPU usage.
  - To specify different container configuration settings for each container, such as a launch command, entry point, working directory, environment variables, or health checks.
Decide whether you need a daemon container group for your fleet. Consider the following:
- Daemon containers are typically used to run background or monitoring processes.
- Containers in a daemon group aren't replicated on a fleet instance. This means that containers in a daemon group don’t scale along with the replica container group.
- A daemon group can have multiple containers. You can designate any container in a daemon group as essential.

Set resource limits

For each container group, determine how much memory and CPU the group needs to run its software. Amazon GameLift relies on this information to manage resources for the container group. It also uses this information to calculate how many replica container groups a fleet image can hold. You can also set limits for individual containers.

Set optional limits for containers

Setting container-specific resource limits lets you exert greater control over how individual containers can use the group’s resources. If you don’t set container-specific limits, all containers in the group share the group resources. Sharing offers greater flexibility to use resources where they're needed. It also increases the potential for processes to compete with each other and result in container failure.

Set any of the following ContainerDefinition properties for any container.

SoftLimit (memory) – Reserve a minimum amount of memory for the container’s exclusive use. The container always has the reserved amount available to it. It can exceed this minimum at any time, if additional resources are available.
HardLimit (memory) – Set a maximum memory limit for the container. If the container exceeds this limit, it results in a restart.
Cpu limit – Reserve a minimum amount of CPU resources for the container's exclusive use. The container always has the reserved amount available to it. It can exceed this minimum at any time, if additional resources are available. (1024 CPU units is the equivalent of 1 vCPU.)

Set total resource limits for a container group

Tell Amazon GameLift how much memory and CPU resources each container group needs. The goal is to allocate enough resources to optimize game server performance. Amazon GameLift uses these limits to calculate how to pack replica container groups on a fleet instance. You’ll also use them when choosing an instance type for a container fleet.

Calculate the total memory and CPU needed for all processes in each container in a group. Consider the following:

What processes run in all containers in the container group? Add up the resources required for these processes.
How many concurrent game server processes do you plan to run in each container group? You set this value as part of a fleet's runtime configuration, but you need to plan enough memory for them here (see Optimize your runtime configuration).

Based on your estimate of container group requirements, set the following ContainerGroupDefinition properties:

TotalMemoryLimit – Set a maximum memory limit for the container group. All containers in the group share allocated memory. If you set individual container limits, the total memory limit must be:
- equal to or greater than the sum of all container soft memory limits
- equal to or greater than the highest hard memory limit for a container in the group
TotalCpuLimit – Set a maximum CPU limit for the container group. All containers in the group share allocated CPU resources. If you set individual container limits, the total CPU limit must be:
- equal to or greater than the sum of all container CPU limits. As a best practice, consider setting this value to double the sum of the container CPU limits.

Example scenario

Let’s say we’re defining a replica container group with the following three containers:

Container A is our essential replica container. It runs game server processes and the Amazon GameLift Agent. We estimate the resource requirements for one game server at 512 MiB and 1024 CPU. We plan to have the container run 10 server processes. Because this container runs our most critical software, we set a soft memory reserve of 6144 MiB and no hard memory limit or CPU reserve limit.
Container B runs supporting software with resource requirements estimated at 1024 MiB and 1536 CPU. We set a soft memory reserve limit of 1024 MiB, a hard memory limit of 2048 MiB, and a CPU reserve limit of 1024 CPU.
Container C runs non-critical logging and other monitoring utilities. We set a hard memory limit of 512 MiB and a CPU reserve limit of 512 CPU.

Using this information, we set the following total limits for the container group:

Total memory limit: 7680 MiB. This value exceeds (1) the sum of soft memory limits (6144+1024 MiB), and (2) the highest hard memory limit (1024 MiB).
Total CPU limit: 13312 CPU. This value exceeds the sum of the CPU limit (1024+512 CPU).

Designate essential containers

For each container, designate the container as essential or non-essential. All container groups must have at least one essential container. The essential container does the critical work of the container group, such as hosting your game servers. The essential container is always expected to be running. If it fails, the entire container group restarts.

Your fleet’s replica container group can have exactly one essential container. This container runs the Amazon GameLift Agent and the game server processes it manages.
If your fleet has a daemon container group, you can designate multiple essential containers. Make a daemon container essential if you want a container failure to prompt a container group restart.

Set the ContainerDefinition property Essential to either true or false for each container.

Configure network connections

You can establish network access to let external traffic connect to any container in a container fleet. For example, you must establish network connections to the container that runs your game server processes, so that game clients can join and play your game. Game clients connect to game servers using ports and IP addresses.

In a container fleet, the connection between a client and server is not direct. Internally, a process in a container listens on a container port. Externally, incoming traffic connects to a fleet instance using a connection port. Amazon GameLift maintains the mappings between internal container ports and external-facing connection ports, so that incoming traffic gets routed to the correct process on the instance.

Amazon GameLift provides an extra layer of control for your network connections. Each container fleet has an inbound permissions setting, which lets you control access to each external-facing connection port. You can't change an existing fleet's port configurations, but you can allow or restrict access as needed by adjusting the inbound permissions. For example, you can remove permissions for all connection ports to shut off all access to the fleet's containers.

Networking ports allow external traffic to connect to processes that are running in a container fleet. EC2 inbound permissions allow traffic to access connection ports, which are opened on each instance in the fleet. Connection ports are mapped internally to container ports, which are assigned to individual processes.

Set container port ranges

Configure a container definition with enough container ports for any process that needs external access. Some containers won't need any ports. Others must have enough ports to assign one to every process that needs one.

Your essential replica container group, which runs your game servers, needs a port for every concurrently running game server process (as configured in the fleet's RuntimeConfiguration). The game server process listens on the assigned port and reports it to Amazon GameLift.

When you create a container group definition, define a container port range for each container that needs network access (see ContainerDefinitionInput:PortConfiguration) . Make sure that the range is large enough to assign a port to each process that needs one. Processes must be assigned port numbers in the container's port configuration.

Set connection port ranges

Configure your container fleet with a set of connection ports. Connection ports provide external access to the fleet instances that are running your containers. Amazon GameLift assigns connection ports and maps them to container ports as needed.

When you create a container fleet, define a connection port range (see ContainerGroupsConfiguration:ConnectionPortRange). Make sure that the range has enough ports to map to every container port across a fleet instance. To calculate the minimum connection ports needed, use the following formula:

[Total number of container ports defined for containers in the replica container group] * [Number of replica container groups per instance] + [Total number of container ports defined for containers in the daemon container group]

As a best practice, double the minimum number of connection ports.

Note

The number of connecton ports can potentially limit the number of replica container groups per instance. If a fleet has only enough connection ports for one replica container group per instance, Amazon GameLift will deploy only one replica container group, even if the instances have enough compute power for multiple replica container groups.

Set inbound permissions

Inbound permissions control external access to a container fleet by specifying which connection ports to open for incoming traffic. You can use this setting to turn a fleet's network access on and off as needed.

When you create a container fleet, define a set of inbound permissions (see CreateFleet:EC2InboundPermissions). Set inbound permission port properties to include some or all the values in the fleet's connection port settings. To change inbound permissions on an existing container fleet, call UpdateFleetPortSettings.

Example scenario

This example illustrates how to set all three network connection properties.

Our fleet's replica container group has 1 container, which runs the game server processes. The runtime confiruation tells the container to run 10 concurrent game server processes.

In the replica container group definition, we set the PortConfiguration parameter for this container as follows:
```
"PortConfiguration": {
  "ContainerPortRanges": [ { "FromPort": 10, "ToPort": 20, "Protocol": "TCP"} ]  } 
```
Our fleet also has a daemon container group with 1 container. It has 1 process that needs network access. In the daemon container group definition, we set the PortConfiguration parameter for this container as follows:
```
"PortConfiguration": {
  "ContainerPortRanges": [ { "FromPort": 25, "ToPort": 25, "Protocol": "TCP"} ]  }
```

Our fleet is configured with 3 replica container groups per fleet instance. Given this information, we can use the formula to calculate the number of connection ports we need:
- Minimum: 31 ports [10 replica container ports * 3 replica container groups per instance + 1 daemon container port]
- Best practice: 62 ports [minimum ports * 2]
When creating the container fleet, we set the ConnectionPortRange parameter in ContainerGroupsConfiguration as follows:
```
"ConnectionPortRange": { "FromPort": 1010, "ToPort": 1071 }
```
We want to allow access to all available connection ports. When creating the container fleet, we set the EC2InboundPermissions parameter as follows:
```
"EC2InboundPermissions": [ 
  {"FromPort": 1010, "ToPort": 1071, "IpRange": "10.24.34.0/23", "Protocol": "TCP"} ]
```

Set up health checks for containers

A container automatically restarts if it experiences a terminal failure and stops running. If the container is essential, the entire container group restarts.

You can define additional custom criteria to measure container health and use a health check to test that criteria. To set up a container health check, you can define it in a docker container image or in your container definition. If you set a health check in the container definition, it overrides any settings in the container image.

Set optional health checks based on the container type as follows:

For an essential replica container, don’t configure health checks. The Amazon GameLift Agent automatically handles health reporting for this container.
For non-essential replica containers and any daemon containers, you can optionally set health check parameters.

Set the following ContainerDefinition properties for a container health check:

Command — Provide a command that checks some aspect of the container’s health. You decide what criteria to use to measure health. The command must result in an exit value of 1 (unhealthy) or 0 (healthy).
StartPeriod — Specify an initial delay before health check failures start counting. This delay gives the container time to bootstrap its processes.
Interval — Decide how often to run the health check command. How quickly do you want to detect and resolve a container failure?
Timeout — Decide how long to wait for success or failure before retrying the health check command. How long should the health check command take to complete?
Retries — How many times should the health check command be retried before registering a failure?

Set container dependencies

Within each container group you can set dependencies between containers based on container status. A dependency impacts when the dependent container can start or shut down based the status of another container.

A key use case for dependencies is to create startup and shutdown sequences for the container group.

For example, you might want Container A to start first and complete successfully before Containers B and C start. To achieve this, first create a dependency for Container B on Container A, with the condition that Container A must complete successfully. Then create a dependency for Container C on Container A with the same condition. Startup sequences occur in reverse order for shutdown.

Configure a container fleet

When you create a container fleet, consider the following decision points. Most of these points are dependent on your container architecture and configuration.

Decide where you want to deploy your fleet

In general, you want to deploy your fleets geographically near your players to minimize latency. You can deploy your container fleet to any Each AWS Region that Amazon GameLift supports. If you want to deploy the same game server to additional geographic locations, you can add remote locations to the fleet including AWS Regions and Local Zones. For a multi-location fleet, You can adjust capacity independently in each fleet location. For more information about supported fleet locations, see Amazon GameLift hosting locations.

Choose an instance type and size for your fleet

Amazon GameLift supports a wide range of Amazon EC2 instances types, all of which are available for use with a container fleet. Instance type availability and price varies by location. You can view a list of supported instance types, filtered by location, in the Amazon GameLift console (under Resources, Instance and service quotas).

When choosing an instance type, first consider the instance family. Instance families offer various combinations of CPU, memory, storage, and networking capabilities. Get more information on EC2 instance families. Within each family you have a range of instance sizes to choose from. Consider the following issues when selecting an instance size:

What's the minimum instance size that can support your workload? Use this information to eliminate any instance types that are too small.
What instance type sizes are a good fit for your container architecture? Ideally, you want to choose a size that can accommodate multiple copies of your replica container group with minimal wasted space.
What scaling granularity makes sense for your game? Scale fleet capacity involves adding or removing instances, and each instance represents the ability to host a specific number of game sessions. Consider how much capacity you want to add or remove with each instance. If player demand varies by thousands from minute to minute, then it might make sense to use very large instances that can host hundreds or thousands of game sessions. By contrast, you might prefer more fine-grained scaling control with smaller instance types.
Are there cost savings available based on size? You might find that the cost of certain instance types vary by location due to availability.

Optimize your runtime configuration

A fleet's runtime configuration is a set of instructions for how to run server processes for game session hosting. These instructions are implemented by the Amazon GameLift Agent in each replica container group in the fleet.

A fleet's runtime configuration determines how many server processes run concurrently in each replica container group. This setting impacts how you calculate your container group resource limits and how you choose an instance type for your fleet. You need to balance these three elements when designing your fleet.

For more information about how to use runtime configurations, see Manage how Amazon GameLift launches game servers.

Set other optional fleet settings

You can use the following optional features when configuring a container fleet:

Set up your game servers to access other AWS resources. See Communicate with other AWS resources from your fleets.
Protect game sessions with active players from terminating prematurely during a scale-down event.
Limit the number of game sessions that one individual can create on the fleet within a limited span of time.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Prepare a container image

Create container group definitions