Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

CreateContainerGroupDefinition

This operation is used with the Amazon GameLift containers feature, which is currently in public preview.

Creates a ContainerGroupDefinition resource that describes a set of containers for hosting your game server with Amazon GameLift managed EC2 hosting. An Amazon GameLift container group is similar to a container "task" and "pod". Each container group can have one or more containers.

Use container group definitions when you create a container fleet. Container group definitions determine how Amazon GameLift deploys your containers to each instance in a container fleet.

You can create two types of container groups, based on scheduling strategy:

A replica container group manages the containers that run your game server application and supporting software. Replica container groups might be replicated multiple times on each fleet instance, depending on instance resources.
A daemon container group manages containers that run other software, such as background services, logging, or test processes. You might use a daemon container group for processes that need to run only once per fleet instance, or processes that need to persist independently of the replica container group.

To create a container group definition, specify a group name, a list of container definitions, and maximum total CPU and memory requirements for the container group. Specify an operating system and scheduling strategy or use the default values. When using the AWS CLI tool, you can pass in your container definitions as a JSON file.

Note

This operation requires AWS Identity and Access Management (IAM) permissions to access container images in Amazon ECR repositories. See IAM permissions for Amazon GameLift for help setting the appropriate permissions.

If successful, this operation creates a new ContainerGroupDefinition resource with an ARN value assigned. You can't change the properties of a container group definition. Instead, create a new one.

Learn more

Request Syntax


{
   "ContainerDefinitions": [ 
      { 
         "Command": [ "string" ],
         "ContainerName": "string",
         "Cpu": number,
         "DependsOn": [ 
            { 
               "Condition": "string",
               "ContainerName": "string"
            }
         ],
         "EntryPoint": [ "string" ],
         "Environment": [ 
            { 
               "Name": "string",
               "Value": "string"
            }
         ],
         "Essential": boolean,
         "HealthCheck": { 
            "Command": [ "string" ],
            "Interval": number,
            "Retries": number,
            "StartPeriod": number,
            "Timeout": number
         },
         "ImageUri": "string",
         "MemoryLimits": { 
            "HardLimit": number,
            "SoftLimit": number
         },
         "PortConfiguration": { 
            "ContainerPortRanges": [ 
               { 
                  "FromPort": number,
                  "Protocol": "string",
                  "ToPort": number
               }
            ]
         },
         "WorkingDirectory": "string"
      }
   ],
   "Name": "string",
   "OperatingSystem": "string",
   "SchedulingStrategy": "string",
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "TotalCpuLimit": number,
   "TotalMemoryLimit": number
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

ContainerDefinitions

Definitions for all containers in this group. Each container definition identifies the container image and specifies configuration settings for the container. See the Container fleet design guide for container guidelines.

Type: Array of ContainerDefinitionInput objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: Yes

Name

A descriptive identifier for the container group definition. The name value must be unique in an AWS Region.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: ^[a-zA-Z0-9\-]+$

Required: Yes

OperatingSystem

The platform that is used by containers in the container group definition. All containers in a group must run on the same operating system.

Type: String

Valid Values: AMAZON_LINUX_2023

Required: Yes

TotalCpuLimit

The maximum amount of CPU units to allocate to the container group. Set this parameter to an integer value in CPU units (1 vCPU is equal to 1024 CPU units). All containers in the group share this memory. If you specify CPU limits for individual containers, set this parameter based on the following guidelines. The value must be equal to or greater than the sum of the CPU limits for all containers in the group.

Type: Integer

Valid Range: Minimum value of 128. Maximum value of 10240.

Required: Yes

TotalMemoryLimit

The maximum amount of memory (in MiB) to allocate to the container group. All containers in the group share this memory. If you specify memory limits for individual containers, set this parameter based on the following guidelines. The value must be (1) greater than the sum of the soft memory limits for all containers in the group, and (2) greater than any individual container's hard memory limit.

Type: Integer

Valid Range: Minimum value of 4. Maximum value of 1024000.

Required: Yes

SchedulingStrategy

The method for deploying the container group across fleet instances. A replica container group might have multiple copies on each fleet instance. A daemon container group has one copy per fleet instance. Default value is REPLICA.

Type: String

Valid Values: REPLICA | DAEMON

Required: No

Tags

A list of labels to assign to the container group definition resource. Tags are developer-defined key-value pairs. Tagging AWS resources are useful for resource management, access management and cost allocation. For more information, see Tagging AWS Resources in the AWS General Reference.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No

Response Syntax


{
   "ContainerGroupDefinition": { 
      "ContainerDefinitions": [ 
         { 
            "Command": [ "string" ],
            "ContainerName": "string",
            "Cpu": number,
            "DependsOn": [ 
               { 
                  "Condition": "string",
                  "ContainerName": "string"
               }
            ],
            "EntryPoint": [ "string" ],
            "Environment": [ 
               { 
                  "Name": "string",
                  "Value": "string"
               }
            ],
            "Essential": boolean,
            "HealthCheck": { 
               "Command": [ "string" ],
               "Interval": number,
               "Retries": number,
               "StartPeriod": number,
               "Timeout": number
            },
            "ImageUri": "string",
            "MemoryLimits": { 
               "HardLimit": number,
               "SoftLimit": number
            },
            "PortConfiguration": { 
               "ContainerPortRanges": [ 
                  { 
                     "FromPort": number,
                     "Protocol": "string",
                     "ToPort": number
                  }
               ]
            },
            "ResolvedImageDigest": "string",
            "WorkingDirectory": "string"
         }
      ],
      "ContainerGroupDefinitionArn": "string",
      "CreationTime": number,
      "Name": "string",
      "OperatingSystem": "string",
      "SchedulingStrategy": "string",
      "Status": "string",
      "StatusReason": "string",
      "TotalCpuLimit": number,
      "TotalMemoryLimit": number
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

ContainerGroupDefinition

The properties of the newly created container group definition resource. You use this resource to create a container fleet.

Type: ContainerGroupDefinition object

Errors

For information about the errors that are common to all actions, see Common Errors.

ConflictException

The requested operation would cause a conflict with the current state of a service resource associated with the request. Resolve the conflict before retrying this request.

HTTP Status Code: 400

InternalServiceException

The service encountered an unrecoverable internal failure while processing the request. Clients can retry such requests immediately or after a waiting period.

HTTP Status Code: 500

InvalidRequestException

One or more parameter values in the request are invalid. Correct the invalid parameter values before retrying.

HTTP Status Code: 400

LimitExceededException

The requested operation would cause the resource to exceed the allowed service limit. Resolve the issue before retrying.

HTTP Status Code: 400

TaggingFailedException

The requested tagging operation did not succeed. This may be due to invalid tag format or the maximum tag limit may have been exceeded. Resolve the issue before retrying.

HTTP Status Code: 400

UnauthorizedException

The client failed authentication. Clients should not retry such requests.

HTTP Status Code: 400

UnsupportedRegionException

The requested operation is not supported in the Region specified.

HTTP Status Code: 400

Examples

Create a replica container group definition with one container

This example creates a container group definition with scheduling strategy REPLICA. It has a single container definition to run our game server processes and the Amazon GameLift Agent.

Our container definition have these characteristics:

It's designated essential, which is required for a container that runs the Agent.
It defines a container port range, which is required for containers that run game server processes.
The image URI points to an ECR private repo.
When there's only one container in the container group, there's no need for container-specific memory limits, CPU limits, or dependencies.
It doesn't need a health check configuration, because the Agent handles that task for the container.

HTTP requests are authenticated using an AWS Signature Version 4 signature in the Authorization header field.

Sample Request


{
  "Name": "MyAdventureGameContainerGroup",
  "SchedulingStrategy": "REPLICA",
  "OperatingSystem": "AMAZON_LINUX_2023",
  "TotalMemoryLimit": 4096,
  "TotalCpuLimit": 1024,
  "ContainerDefinitions": [
    {
      "ContainerName": "MyAdventureGameContainer",
      "ImageUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/MyAdventureGameContainerImage",
      "Essential": TRUE,
      "PortConfiguration": { 
        "ContainerPortRanges": [ 
          { 
            "FromPort": 35000,
            "Protocol": "TCP",
            "ToPort": 40000
          }
        ]
      }
    }
  ]
}

Sample Response


{
  "ContainerGroupDefinition": { 
    "ContainerDefinitions": [ 
      { 
        "ContainerName": "MyAdventureGameContainer",
        "Essential": TRUE,
        "ImageUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/MyAdventureGameContainerImage",
        "PortConfiguration": { 
          "ContainerPortRanges": [ 
            { 
              "FromPort": 35000,
              "Protocol": "TCP",
              "ToPort": 40000
            }
          ]
        },
        "ResolvedImageDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ],
    "ContainerGroupDefinitionArn": "arn:aws:gamelift:us-west-2:111122223333:containergroupdefinition/MyAdventureGameContainerGroup",
    "CreationTime": 1496365885.44,
    "Name": "MyAdventureGameContainerGroup",
    "OperatingSystem": "AMAZON_LINUX_2023",
    "SchedulingStrategy": "REPLICA",
    "Status": "COPYING",
    "TotalCpuLimit": 4096,
    "TotalMemoryLimit": 1024
  }
}