AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Calls the Amazon GameLift Service CreateContainerGroupDefinition API operation.

Syntax

New-GMLContainerGroupDefinition
-Name <String>
-ContainerGroupType <ContainerGroupType>
-GameServerContainerDefinition_ContainerName <String>
-PortConfiguration_ContainerPortRange <ContainerPortRange[]>
-GameServerContainerDefinition_DependsOn <ContainerDependency[]>
-GameServerContainerDefinition_EnvironmentOverride <ContainerEnvironment[]>
-GameServerContainerDefinition_ImageUri <String>
-GameServerContainerDefinition_MountPoint <ContainerMountPoint[]>
-OperatingSystem <ContainerOperatingSystem>
-GameServerContainerDefinition_ServerSdkVersion <String>
-SupportContainerDefinition <SupportContainerDefinitionInput[]>
-Tag <Tag[]>
-TotalMemoryLimitMebibyte <Int32>
-TotalVcpuLimit <Double>
-VersionDescription <String>
-Select <String>
-Force <SwitchParameter>
-ClientConfig <AmazonGameLiftConfig>

Description

Creates a ContainerGroupDefinition that describes a set of containers for hosting your game server with Amazon GameLift Servers managed containers hosting. An Amazon GameLift Servers container group is similar to a container task or pod. Use container group definitions when you create a container fleet with CreateContainerFleet. A container group definition determines how Amazon GameLift Servers deploys your containers to each instance in a container fleet. You can maintain multiple versions of a container group definition. There are two types of container groups:
  • A game server container group has the containers that run your game server application and supporting software. A game server container group can have these container types:
    • Game server container. This container runs your game server. You can define one game server container in a game server container group.
    • Support container. This container runs software in parallel with your game server. You can define up to 8 support containers in a game server group.
    When building a game server container group definition, you can choose to bundle your game server executable and all dependent software into a single game server container. Alternatively, you can separate the software into one game server container and one or more support containers. On a container fleet instance, a game server container group can be deployed multiple times (depending on the compute resources of the instance). This means that all containers in the container group are replicated together.
  • A per-instance container group has containers for processes that aren't replicated on a container fleet instance. This might include background services, logging, test processes, or processes that need to persist independently of the game server container group. When building a per-instance container group, you can define up to 10 support containers.
This operation requires Identity and Access Management (IAM) permissions to access container images in Amazon ECR repositories. See IAM permissions for Amazon GameLift Servers for help setting the appropriate permissions. Request options Use this operation to make the following types of requests. You can specify values for the minimum required parameters and customize optional values later.
  • Create a game server container group definition. Provide the following required parameter values:
    • Name
    • ContainerGroupType (GAME_SERVER)
    • OperatingSystem (omit to use default value)
    • TotalMemoryLimitMebibytes (omit to use default value)
    • TotalVcpuLimit (omit to use default value)
    • At least one GameServerContainerDefinition
      • ContainerName
      • ImageUrl
      • PortConfiguration
      • ServerSdkVersion (omit to use default value)
  • Create a per-instance container group definition. Provide the following required parameter values:
    • Name
    • ContainerGroupType (PER_INSTANCE)
    • OperatingSystem (omit to use default value)
    • TotalMemoryLimitMebibytes (omit to use default value)
    • TotalVcpuLimit (omit to use default value)
    • At least one SupportContainerDefinition
      • ContainerName
      • ImageUrl
Results If successful, this request creates a ContainerGroupDefinition resource and assigns a unique ARN value. You can update most properties of a container group definition by calling UpdateContainerGroupDefinition, and optionally save the update as a new version.

Parameters

-ClientConfig <AmazonGameLiftConfig>
Amazon.PowerShell.Cmdlets.GML.AmazonGameLiftClientCmdlet.ClientConfig
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerGroupType <ContainerGroupType>
The type of container group being defined. Container group type determines how Amazon GameLift Servers deploys the container group on each fleet instance.Default value: GAME_SERVER
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Force <SwitchParameter>
This parameter overrides confirmation prompts to force the cmdlet to continue its operation. This parameter should always be used with caution.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-GameServerContainerDefinition_ContainerName <String>
A string that uniquely identifies the container definition within a container group.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-GameServerContainerDefinition_DependsOn <ContainerDependency[]>
Establishes dependencies between this container and the status of other containers in the same container group. A container can have dependencies on multiple different containers. You can use dependencies to establish a startup/shutdown sequence across the container group. For example, you might specify that ContainerB has a START dependency on ContainerA. This dependency means that ContainerB can't start until after ContainerA has started. This dependency is reversed on shutdown, which means that ContainerB must shut down before ContainerA can shut down. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-GameServerContainerDefinition_EnvironmentOverride <ContainerEnvironment[]>
A set of environment variables to pass to the container on startup. See the ContainerDefinition::environment parameter in the Amazon Elastic Container Service API Reference. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-GameServerContainerDefinition_ImageUri <String>
The location of the container image to deploy to a container fleet. Provide an image in an Amazon Elastic Container Registry public or private repository. The repository must be in the same Amazon Web Services account and Amazon Web Services Region where you're creating the container group definition. For limits on image size, see Amazon GameLift Servers endpoints and quotas. You can use any of the following image URI formats:
  • Image ID only: [AWS account].dkr.ecr.[AWS region].amazonaws.com/[repository ID]
  • Image ID and digest: [AWS account].dkr.ecr.[AWS region].amazonaws.com/[repository ID]@[digest]
  • Image ID and tag: [AWS account].dkr.ecr.[AWS region].amazonaws.com/[repository ID]:[tag]
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-GameServerContainerDefinition_MountPoint <ContainerMountPoint[]>
A mount point that binds a path inside the container to a file or directory on the host system and lets it access the file or directory. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesGameServerContainerDefinition_MountPoints
-GameServerContainerDefinition_ServerSdkVersion <String>
The Amazon GameLift Servers server SDK version that the game server is integrated with. Only game servers using 5.2.0 or higher are compatible with container fleets.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Name <String>
A descriptive identifier for the container group definition. The name value must be unique in an Amazon Web Services Region.
Required?True
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
-OperatingSystem <ContainerOperatingSystem>
The platform that all containers in the group use. Containers in a group must run on the same operating system.Default value: AMAZON_LINUX_2023Amazon 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 server SDK version 4.x for Amazon GameLift Servers, first update the game server build to server SDK 5.x, and then deploy to AL2023 instances. See Migrate to server SDK version 5.
Required?True
Position?Named
Accept pipeline input?True (ByPropertyName)
-PortConfiguration_ContainerPortRange <ContainerPortRange[]>
A set of one or more container port number ranges. The ranges can't overlap if the ranges' network protocols are the same. Overlapping ranges with different protocols is allowed but not recommended. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesGameServerContainerDefinition_PortConfiguration_ContainerPortRanges
-Select <String>
Use the -Select parameter to control the cmdlet output. The default value is 'ContainerGroupDefinition'. Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.GameLift.Model.CreateContainerGroupDefinitionResponse). Specifying the name of a property of type Amazon.GameLift.Model.CreateContainerGroupDefinitionResponse will result in that property being returned. Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SupportContainerDefinition <SupportContainerDefinitionInput[]>
One or more definition for support containers in this group. You can define a support container in any type of container group. You can pass in your container definitions as a JSON file. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSupportContainerDefinitions
-Tag <Tag[]>
A list of labels to assign to the container group definition resource. Tags are developer-defined key-value pairs. Tagging Amazon Web Services resources are useful for resource management, access management and cost allocation. For more information, see Tagging Amazon Web Services Resources in the Amazon Web Services General Reference. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesTags
-TotalMemoryLimitMebibyte <Int32>
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 an individual container, the total value must be greater than any individual container's memory limit.Default value: 1024
Required?True
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesTotalMemoryLimitMebibytes
-TotalVcpuLimit <Double>
The maximum amount of vCPU units to allocate to the container group (1 vCPU is equal to 1024 CPU units). All containers in the group share this memory. If you specify vCPU limits for individual containers, the total value must be equal to or greater than the sum of the CPU limits for all containers in the group.Default value: 1
Required?True
Position?Named
Accept pipeline input?True (ByPropertyName)
-VersionDescription <String>
A description for the initial version of this container group definition.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-EndpointUrl <String>
The endpoint to make the call against.Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-Region <Object>
The system name of an AWS region or an AWSRegion instance. This governs the endpoint that will be used when calling service operations. Note that the AWS resources referenced in a call are usually region-specific.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRegionToCall
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

Amazon.GameLift.Model.ContainerGroupDefinition or Amazon.GameLift.Model.CreateContainerGroupDefinitionResponse
This cmdlet returns an Amazon.GameLift.Model.ContainerGroupDefinition object. The service call response (type Amazon.GameLift.Model.CreateContainerGroupDefinitionResponse) can be returned by specifying '-Select *'.
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z