Create container group definitions for an Amazon GameLift container fleet - Amazon GameLift
Before you startClone a container group definitionCreate a replica container group definitionCreate a container definition JSON file

Create container group definitions for an Amazon GameLift container fleet

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

A container group definition describes how to deploy your containerized game server applications to a container fleet. It's a blueprint that identifies the set of containers to run on the fleet and how to run them. When you create a container fleet, you specify the container group definitions to deploy to the fleet. For more information about container groups, see Container fleet components.

Before you start

Complete the following tasks:

  • Design a container architecture for hosting your game servers. See Design an Amazon GameLift container fleet.

  • Plan the container definitions to include in the container group. If you’re using the AWS CLI, create your container definition in a JSON file.

  • Push the final container images to an Amazon Elastic Container Registry (Amazon ECR) registry in the same AWS Region where you plan to create the container group. Amazon GameLift stores a snapshot of each image at the time you create container group definition, and uses the copy when deploying to a container fleet. See Prepare a container image with your game server software.

  • Verify that your AWS user has IAM permissions to access the Amazon ECR repository. See Manage user permissions for Amazon GameLift. At minimum, you need permissions for the following actions:

    • ecr:DescribeImages

    • ecr:BatchGetImage

    • ecr:GetDownloadUrlForLayer

Clone a container group definition

You can use the Amazon GameLift console to clone an existing container group definition.

To clone a container group

  1. In the Amazon GameLift console, go to the left navigation pane and choose Container groups.

  2. On the Container groups list page, select the existing container group that you want to clone. After you select a container group, the Clone button is active.

  3. Choose Clone. This action opens the container group creation wizard with pre-filled settings.

  4. Enter a new name for the cloned container group. Container group in the same region must have unique names.

  5. Step through the container group and container definition pages, review, and Create the new container group.

Create a replica container group definition

A replica container group manages your game server software. A replica container group has at least one container that runs the Amazon GameLift Agent and your game server processes. The group might have additional “sidecar” containers to run supporting software.

This topic describes how to create a container group definition using the Amazon GameLift console or AWS CLI tools. For more detailed information on setting container group configurations, refer to Design an Amazon GameLift container fleet.

Console

In the Amazon GameLift console, select the AWS Region where you want to create the container group.

Open the console’s left navigation bar and choose Container groups. On the Container groups page, choose Create container group.

Step 1: Define group details.

  1. Enter a container group definition name. This name must be unique to the AWS account and Region. In the console, group definitions are listed by name, so it can be helpful to assign meaningful labels.

  2. Select the Replica scheduling strategy.

  3. For Total memory limit, enter the maximum memory available to the container group. For help calculating this value, see Set resource limits.

  4. For Total CPU limit, enter the maximum computing power available to the container group. For help calculating this value, see Set resource limits.

Step 2: Add container definitions.

Define the container with your game server application and the Amazon GameLift Agent. This is your essential replica container.

  1. Provide a container definition Name. Each container defined for the group must have a unique name value.

  2. Identify the Amazon ECR image URI of the container image. Enter any of the following formats:

    • Image URI only: [AWS account].dkr.ecr.[AWS Region].amazonaws.com/[repository ID]

    • Image URI + digest: [AWS account].dkr.ecr.[AWS Region].amazonaws.com/[repository ID]@[digest]

    • Image URI + tag: [AWS account].dkr.ecr.[AWS Region].amazonaws.com/[repository ID]:[tag]

  3. For Essential container, Yes is automatically selected for the first container definition. If you add another container definition, you can toggle this setting on or off for each definition. For more details, see Designate essential containers.

  4. Set one or more Internal container port ranges. This container hosts your game servers, so define a range with enough ports for each server process to run in the container group. For more details, see Configure network connections.

  5. The optional settings Overrides and Environment variables let you specify values to pass to the container on launch. Values you set here override any settings already in the container image.

  6. Set optional container Limits to manage resource allocation for this container. For more details, see Set resource limits.

  7. Define additional non-essential containers as needed:

    • Provide a container definition Name and ECR image URI. Non-essential containers must not run the Amazon GameLift Agent.

    • Set an Internal container port range only if the containers has processes that need network access.

    • Optionally set up a Health check for the container. When a non-essential container fails a health check, it prompts a restart of the failing container only.

    • Optionally set Overrides, Environment variables, and resource allocation Limits as needed.

Step 3: Configure dependencies.

If you have more than one container in your container group definition, you can define dependencies between them. Use dependencies to set up startup and shutdown sequences based on container condition. For more details, see Set container dependencies.

  1. Identify the Container name that you want to add a dependency for. This container doesn't start until the dependency condition is satisfied.

  2. Identify the dependency Container name and Condition. This container must meet the condition before the dependent container can start.

  3. Set additional dependencies as needed. You can create multiple dependencies for any container. Avoid creating circular dependencies.

Step 4: Review and create.

  1. Review all your container group definition settings. You can't change the configuration of a container group definition after it's created. Use Edit to make changes to any section, including each of your container definitions for the group.

  2. When you're finished reviewing, choose Create.

    If your request is successful, the console displays the detail page for the new container group definition resource. Initially the status is COPYING, as Amazon GameLift starts taking snapshots of all the container images for the group. When this phase is complete, the container group definition status changes to READY. A container group definition must be in READY status before you can create a container fleet with it.

AWS CLI

When you use the AWS CLI to create a container group definition, maintain your container definition configurations in a separate JSON file. You can reference the file in your CLI command. See Create a container definition JSON file for schema examples.

Create a container group definition

To create a new container group definition, use the create-container-group-definition CLI command. For more information about this command, see create-container-group-definition in the AWS CLI Command Reference.

Example : Replica container group

This example illustrates a request for a replica container group definition. The command structure for creating replica and daemon group definitions are essentially identical. Specific details for each type of group are described in the individual container definitions.

This example assumes that you’ve created a JSON file with the container definitions for this group.

aws gamelift create-container-group-definition \
    --name MyAdventureGameContainerGroup \
    --operating-system AMAZON_LINUX_2023 \
    --scheduling-strategy REPLICA \
    --total-memory-limit 4096 \
    --total-cpu-limit 1024 \
    --container-definitions file://SimpleServer.json

Create a container definition JSON file

When you create a container group definition, you also define the containers for the group. A container definition specifies the Amazon ECR repository where the container image is stored, and optional configurations for network ports, limits for CPU and memory usage, and other settings. We recommend creating a single JSON file with the configurations for all the containers in a container group. Maintaining a file is useful for storing, sharing, version tracking these critical configurations. If you use the AWS CLI to create your container group definitions, you can reference the file in the command.

To create a container definition

  1. Create and open a new .JSON file. For example:

    [~/work/glc]$ vim SimpleServer.json

  2. Create a separate container definition for each of the containers for the group. Copy the following example content and modify it as needed for your containers. For details on the syntax of a container definition, see ContainerDefinitionInput in the Amazon GameLift API Reference.

  3. Save the file locally so that you can refer to it in an AWS CLI command.

This example describes the essential container for your replica container group. The essential replica container includes your game server application, the Amazon GameLift Agent, and can include other supporting software for your game hosting. The definition must include a name, image URI, and a port configuration. This example also sets some container-specific resource limits.

[
  {
    "ContainerName": "SimpleServer",
    "ImageUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/gl-containers:complex-server",
    "Essential": true,
    "Cpu": 256,
    "MemoryLimits": { 
      "HardLimit": 128
  },
     "PortConfiguration": {
            "ContainerPortRanges": [
               {
                  "FromPort": 2000,
                  "Protocol": "TCP",
                  "ToPort": 2100
               }
            ]
      }
    }
]