Skip to main content

game_server_groups

Creates, updates, deletes, gets or lists a game_server_groups resource.

Overview​

Namegame_server_groups
TypeResource
Idaws.gamelift.game_server_groups

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
auto_scaling_group_arnstringA generated unique ID for the Amazon EC2 Auto Scaling group that is associated with this game server group. (pattern: <code>^[\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*$</code>)
balancing_strategystringIndicates how Amazon GameLift Servers FleetIQ balances the use of Spot Instances and On-Demand Instances in the game server group. Method options include the following: SPOT_ONLY - Only Spot Instances are used in the game server group. If Spot Instances are unavailable or not viable for game hosting, the game server group provides no hosting capacity until Spot Instances can again be used. Until then, no new instances are started, and the existing nonviable Spot Instances are terminated (after current gameplay ends) and are not replaced. SPOT_PREFERRED - (default value) Spot Instances are used whenever available in the game server group. If Spot Instances are unavailable, the game server group continues to provide hosting capacity by falling back to On-Demand Instances. Existing nonviable Spot Instances are terminated (after current gameplay ends) and are replaced with new On-Demand Instances. ON_DEMAND_ONLY - Only On-Demand Instances are used in the game server group. No Spot Instances are used, even when available, while this balancing strategy is in force. (SPOT_ONLY, SPOT_PREFERRED, ON_DEMAND_ONLY)
creation_timestring (date-time)A time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").
game_server_group_arnstringA generated unique ID for the game server group. (pattern: <code>^arn:.:gameservergroup/[a-zA-Z0-9-.]$</code>)
game_server_group_namestringA developer-defined identifier for the game server group. The name is unique for each Region in each Amazon Web Services account. (pattern: <code>^[a-zA-Z0-9-.]+$</code>)
game_server_protection_policystringA flag that indicates whether instances in the game server group are protected from early termination. Unprotected instances that have active game servers running might be terminated during a scale-down event, causing players to be dropped from the game. Protected instances cannot be terminated while there are active game servers running except in the event of a forced game server group deletion (see ). An exception to this is with Spot Instances, which can be terminated by Amazon Web Services regardless of protection status. (NO_PROTECTION, FULL_PROTECTION)
instance_definitionsarrayThe set of Amazon EC2 instance types that Amazon GameLift Servers FleetIQ can use when balancing and automatically scaling instances in the corresponding Auto Scaling group.
last_updated_timestring (date-time)A timestamp that indicates when this game server group was last updated.
role_arnstringThe Amazon Resource Name (ARN) for an IAM role that allows Amazon GameLift Servers to access your Amazon EC2 Auto Scaling groups. (pattern: <code>^arn:.*:role/[\w+=,.@-]+</code>)
statusstringThe current status of the game server group. Possible statuses include: NEW - Amazon GameLift Servers FleetIQ has validated the CreateGameServerGroup() request. ACTIVATING - Amazon GameLift Servers FleetIQ is setting up a game server group, which includes creating an Auto Scaling group in your Amazon Web Services account. ACTIVE - The game server group has been successfully created. DELETE_SCHEDULED - A request to delete the game server group has been received. DELETING - Amazon GameLift Servers FleetIQ has received a valid DeleteGameServerGroup() request and is processing it. Amazon GameLift Servers FleetIQ must first complete and release hosts before it deletes the Auto Scaling group and the game server group. DELETED - The game server group has been successfully deleted. ERROR - The asynchronous processes of activating or deleting a game server group has failed, resulting in an error state. (NEW, ACTIVATING, ACTIVE, DELETE_SCHEDULED, DELETING, DELETED, ERROR)
status_reasonstringAdditional information about the current game server group status. This information might provide additional insight on groups that are in ERROR status.
suspended_actionsarrayA list of activities that are currently suspended for this game server group. If this property is empty, all activities are occurring.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_game_server_groupselectregionThis API works with the following fleet types: EC2 (FleetIQ) Retrieves information on a game server group. This operation returns only properties related to Amazon GameLift Servers FleetIQ. To view or update properties for the corresponding Auto Scaling group, such as launch template, auto scaling policies, and maximum/minimum group size, access the Auto Scaling group directly. To get attributes for a game server group, provide a group name or ARN value. If successful, a GameServerGroup object is returned. Learn more Amazon GameLift Servers FleetIQ Guide
list_game_server_groupsselectregionThis API works with the following fleet types: EC2 (FleetIQ) Lists a game server groups.
create_game_server_groupinsertregion, GameServerGroupName, RoleArn, MinSize, MaxSize, LaunchTemplate, InstanceDefinitionsThis API works with the following fleet types: EC2 (FleetIQ) Creates a Amazon GameLift Servers FleetIQ game server group for managing game hosting on a collection of Amazon Elastic Compute Cloud instances for game hosting. This operation creates the game server group, creates an Auto Scaling group in your Amazon Web Services account, and establishes a link between the two groups. You can view the status of your game server groups in the Amazon GameLift Servers console. Game server group metrics and events are emitted to Amazon CloudWatch. Before creating a new game server group, you must have the following: An Amazon Elastic Compute Cloud launch template that specifies how to launch Amazon Elastic Compute Cloud instances with your game server build. For more information, see Launching an Instance from a Launch Template in the Amazon Elastic Compute Cloud User Guide. An IAM role that extends limited access to your Amazon Web Services account to allow Amazon GameLift Servers FleetIQ to create and interact with the Auto Scaling group. For more information, see Create IAM roles for cross-service interaction in the Amazon GameLift Servers FleetIQ Developer Guide. To create a new game server group, specify a unique group name, IAM role and Amazon Elastic Compute Cloud launch template, and provide a list of instance types that can be used in the group. You must also set initial maximum and minimum limits on the group's instance count. You can optionally set an Auto Scaling policy with target tracking based on a Amazon GameLift Servers FleetIQ metric. Once the game server group and corresponding Auto Scaling group are created, you have full access to change the Auto Scaling group's configuration as needed. Several properties that are set when creating a game server group, including maximum/minimum size and auto-scaling policy settings, must be updated directly in the Auto Scaling group. Keep in mind that some Auto Scaling group properties are periodically updated by Amazon GameLift Servers FleetIQ as part of its balancing activities to optimize for availability and cost. Learn more Amazon GameLift Servers FleetIQ Guide
update_game_server_groupupdateregion, GameServerGroupNameThis API works with the following fleet types: EC2 (FleetIQ) Updates Amazon GameLift Servers FleetIQ-specific properties for a game server group. Many Auto Scaling group properties are updated on the Auto Scaling group directly, including the launch template, Auto Scaling policies, and maximum/minimum/desired instance counts. To update the game server group, specify the game server group ID and provide the updated values. Before applying the updates, the new values are validated to ensure that Amazon GameLift Servers FleetIQ can continue to perform instance balancing activity. If successful, a GameServerGroup object is returned. Target tracking Auto Scaling policies on the Auto Scaling group cannot be updated through the Amazon Web Services Management Console. Instead, use the Amazon Elastic Compute Cloud Auto Scaling PutScalingPolicy API action to update these policies. Learn more Amazon GameLift Servers FleetIQ Guide
delete_game_server_groupdeleteregionThis API works with the following fleet types: EC2 (FleetIQ) Terminates a game server group and permanently deletes the game server group record. You have several options for how these resources are impacted when deleting the game server group. Depending on the type of delete operation selected, this operation might affect these resources: The game server group The corresponding Auto Scaling group All game servers that are currently running in the group To delete a game server group, identify the game server group to delete and specify the type of delete operation to initiate. Game server groups can only be deleted if they are in ACTIVE or ERROR status. If the delete request is successful, a series of operations are kicked off. The game server group status is changed to DELETE_SCHEDULED, which prevents new game servers from being registered and stops automatic scaling activity. Once all game servers in the game server group are deregistered, Amazon GameLift Servers FleetIQ can begin deleting resources. If any of the delete operations fail, the game server group is placed in ERROR status. Amazon GameLift Servers FleetIQ emits delete events to Amazon CloudWatch. Learn more Amazon GameLift Servers FleetIQ Guide
claim_game_serverexecregion, GameServerGroupNameThis API works with the following fleet types: EC2 (FleetIQ) Locates an available game server and temporarily reserves it to host gameplay and players. This operation is called from a game client or client service (such as a matchmaker) to request hosting resources for a new game session. In response, Amazon GameLift Servers FleetIQ locates an available game server, places it in CLAIMED status for 60 seconds, and returns connection information that players can use to connect to the game server. To claim a game server, identify a game server group. You can also specify a game server ID, although this approach bypasses Amazon GameLift Servers FleetIQ placement optimization. Optionally, include game data to pass to the game server at the start of a game session, such as a game map or player information. Add filter options to further restrict how a game server is chosen, such as only allowing game servers on ACTIVE instances to be claimed. When a game server is successfully claimed, connection information is returned. A claimed game server's utilization status remains AVAILABLE while the claim status is set to CLAIMED for up to 60 seconds. This time period gives the game server time to update its status to UTILIZED after players join. If the game server's status is not updated within 60 seconds, the game server reverts to unclaimed status and is available to be claimed by another request. The claim time period is a fixed value and is not configurable. If you try to claim a specific game server, this request will fail in the following cases: If the game server utilization status is UTILIZED. If the game server claim status is CLAIMED. If the game server is running on an instance in DRAINING status and the provided filter option does not allow placing on DRAINING instances. Learn more Amazon GameLift Servers FleetIQ Guide
suspend_game_server_groupexecregion, GameServerGroupName, SuspendActionsThis API works with the following fleet types: EC2 (FleetIQ) Temporarily stops activity on a game server group without terminating instances or the game server group. You can restart activity by calling ResumeGameServerGroup. You can suspend the following activity: Instance type replacement - This activity evaluates the current game hosting viability of all Spot instance types that are defined for the game server group. It updates the Auto Scaling group to remove nonviable Spot Instance types, which have a higher chance of game server interruptions. It then balances capacity across the remaining viable Spot Instance types. When this activity is suspended, the Auto Scaling group continues with its current balance, regardless of viability. Instance protection, utilization metrics, and capacity scaling activities continue to be active. To suspend activity, specify a game server group ARN and the type of activity to be suspended. If successful, a GameServerGroup object is returned showing that the activity is listed in SuspendedActions. Learn more Amazon GameLift Servers FleetIQ Guide

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

This API works with the following fleet types: EC2 (FleetIQ) Retrieves information on a game server group. This operation returns only properties related to Amazon GameLift Servers FleetIQ. To view or update properties for the corresponding Auto Scaling group, such as launch template, auto scaling policies, and maximum/minimum group size, access the Auto Scaling group directly. To get attributes for a game server group, provide a group name or ARN value. If successful, a GameServerGroup object is returned. Learn more Amazon GameLift Servers FleetIQ Guide

SELECT
auto_scaling_group_arn,
balancing_strategy,
creation_time,
game_server_group_arn,
game_server_group_name,
game_server_protection_policy,
instance_definitions,
last_updated_time,
role_arn,
status,
status_reason,
suspended_actions
FROM aws.gamelift.game_server_groups
WHERE region = '{{ region }}' -- required
;

INSERT examples​

This API works with the following fleet types: EC2 (FleetIQ) Creates a Amazon GameLift Servers FleetIQ game server group for managing game hosting on a collection of Amazon Elastic Compute Cloud instances for game hosting. This operation creates the game server group, creates an Auto Scaling group in your Amazon Web Services account, and establishes a link between the two groups. You can view the status of your game server groups in the Amazon GameLift Servers console. Game server group metrics and events are emitted to Amazon CloudWatch. Before creating a new game server group, you must have the following: An Amazon Elastic Compute Cloud launch template that specifies how to launch Amazon Elastic Compute Cloud instances with your game server build. For more information, see Launching an Instance from a Launch Template in the Amazon Elastic Compute Cloud User Guide. An IAM role that extends limited access to your Amazon Web Services account to allow Amazon GameLift Servers FleetIQ to create and interact with the Auto Scaling group. For more information, see Create IAM roles for cross-service interaction in the Amazon GameLift Servers FleetIQ Developer Guide. To create a new game server group, specify a unique group name, IAM role and Amazon Elastic Compute Cloud launch template, and provide a list of instance types that can be used in the group. You must also set initial maximum and minimum limits on the group's instance count. You can optionally set an Auto Scaling policy with target tracking based on a Amazon GameLift Servers FleetIQ metric. Once the game server group and corresponding Auto Scaling group are created, you have full access to change the Auto Scaling group's configuration as needed. Several properties that are set when creating a game server group, including maximum/minimum size and auto-scaling policy settings, must be updated directly in the Auto Scaling group. Keep in mind that some Auto Scaling group properties are periodically updated by Amazon GameLift Servers FleetIQ as part of its balancing activities to optimize for availability and cost. Learn more Amazon GameLift Servers FleetIQ Guide

INSERT INTO aws.gamelift.game_server_groups (
GameServerGroupName,
RoleArn,
MinSize,
MaxSize,
LaunchTemplate,
InstanceDefinitions,
AutoScalingPolicy,
BalancingStrategy,
GameServerProtectionPolicy,
VpcSubnets,
Tags,
region
)
SELECT 
'{{ GameServerGroupName }}' /* required */,
'{{ RoleArn }}' /* required */,
{{ MinSize }} /* required */,
{{ MaxSize }} /* required */,
'{{ LaunchTemplate }}' /* required */,
'{{ InstanceDefinitions }}' /* required */,
'{{ AutoScalingPolicy }}',
'{{ BalancingStrategy }}',
'{{ GameServerProtectionPolicy }}',
'{{ VpcSubnets }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
game_server_group
;

UPDATE examples​

This API works with the following fleet types: EC2 (FleetIQ) Updates Amazon GameLift Servers FleetIQ-specific properties for a game server group. Many Auto Scaling group properties are updated on the Auto Scaling group directly, including the launch template, Auto Scaling policies, and maximum/minimum/desired instance counts. To update the game server group, specify the game server group ID and provide the updated values. Before applying the updates, the new values are validated to ensure that Amazon GameLift Servers FleetIQ can continue to perform instance balancing activity. If successful, a GameServerGroup object is returned. Target tracking Auto Scaling policies on the Auto Scaling group cannot be updated through the Amazon Web Services Management Console. Instead, use the Amazon Elastic Compute Cloud Auto Scaling PutScalingPolicy API action to update these policies. Learn more Amazon GameLift Servers FleetIQ Guide

UPDATE aws.gamelift.game_server_groups
SET 
GameServerGroupName = '{{ GameServerGroupName }}',
RoleArn = '{{ RoleArn }}',
InstanceDefinitions = '{{ InstanceDefinitions }}',
GameServerProtectionPolicy = '{{ GameServerProtectionPolicy }}',
BalancingStrategy = '{{ BalancingStrategy }}'
WHERE 
region = '{{ region }}' --required
AND GameServerGroupName = '{{ GameServerGroupName }}' --required
RETURNING
game_server_group;

DELETE examples​

This API works with the following fleet types: EC2 (FleetIQ) Terminates a game server group and permanently deletes the game server group record. You have several options for how these resources are impacted when deleting the game server group. Depending on the type of delete operation selected, this operation might affect these resources: The game server group The corresponding Auto Scaling group All game servers that are currently running in the group To delete a game server group, identify the game server group to delete and specify the type of delete operation to initiate. Game server groups can only be deleted if they are in ACTIVE or ERROR status. If the delete request is successful, a series of operations are kicked off. The game server group status is changed to DELETE_SCHEDULED, which prevents new game servers from being registered and stops automatic scaling activity. Once all game servers in the game server group are deregistered, Amazon GameLift Servers FleetIQ can begin deleting resources. If any of the delete operations fail, the game server group is placed in ERROR status. Amazon GameLift Servers FleetIQ emits delete events to Amazon CloudWatch. Learn more Amazon GameLift Servers FleetIQ Guide

DELETE FROM aws.gamelift.game_server_groups
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

This API works with the following fleet types: EC2 (FleetIQ) Locates an available game server and temporarily reserves it to host gameplay and players. This operation is called from a game client or client service (such as a matchmaker) to request hosting resources for a new game session. In response, Amazon GameLift Servers FleetIQ locates an available game server, places it in CLAIMED status for 60 seconds, and returns connection information that players can use to connect to the game server. To claim a game server, identify a game server group. You can also specify a game server ID, although this approach bypasses Amazon GameLift Servers FleetIQ placement optimization. Optionally, include game data to pass to the game server at the start of a game session, such as a game map or player information. Add filter options to further restrict how a game server is chosen, such as only allowing game servers on ACTIVE instances to be claimed. When a game server is successfully claimed, connection information is returned. A claimed game server's utilization status remains AVAILABLE while the claim status is set to CLAIMED for up to 60 seconds. This time period gives the game server time to update its status to UTILIZED after players join. If the game server's status is not updated within 60 seconds, the game server reverts to unclaimed status and is available to be claimed by another request. The claim time period is a fixed value and is not configurable. If you try to claim a specific game server, this request will fail in the following cases: If the game server utilization status is UTILIZED. If the game server claim status is CLAIMED. If the game server is running on an instance in DRAINING status and the provided filter option does not allow placing on DRAINING instances. Learn more Amazon GameLift Servers FleetIQ Guide

EXEC aws.gamelift.game_server_groups.claim_game_server 
@region='{{ region }}' --required 
@@json=
'{
"GameServerGroupName": "{{ GameServerGroupName }}", 
"GameServerId": "{{ GameServerId }}", 
"GameServerData": "{{ GameServerData }}", 
"FilterOption": "{{ FilterOption }}"
}'
;
Last updated on