CreateContainerGroupDefinition
This operation is currently not available. It is under improvement as we respond to customer feedback from the Containers public preview. Stay tuned for more details about the upcoming General Availability launch later this year. Thank you for your support and patience!
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.
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.
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.
Note
Amazon Linux 2 (AL2) will reach end of support on 6/30/2025. See more details in the Amazon Linux 2 FAQs
. For game servers that are hosted on AL2 and use Amazon GameLift server SDK 4.x., first update the game server build to server SDK 5.x, and then deploy to AL2023 instances. See Migrate to Amazon GameLift server SDK version 5. 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
}
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: