Amazon GameLift

2018/05/10 - Amazon GameLift - 2 new 4 updated api methods

Changes  AutoScaling Target Tracking scaling simplification along with StartFleetActions and StopFleetActions APIs to suspend and resume automatic scaling at will.

StopFleetActions (new) Link ¶

Suspends activity on a fleet. Currently, this operation is used to stop a fleet's auto-scaling activity. It is used to temporarily stop scaling events triggered by the fleet's scaling policies. The policies can be retained and auto-scaling activity can be restarted using StartFleetActions . You can view a fleet's stopped actions using DescribeFleetAttributes .

To stop fleet actions, specify the fleet ID and the type of actions to suspend. When auto-scaling fleet actions are stopped, Amazon GameLift no longer initiates scaling events except to maintain the fleet's desired instances setting ( FleetCapacity . Changes to the fleet's capacity must be done manually using UpdateFleetCapacity .

See also: AWS API Documentation

Request Syntax

client.stop_fleet_actions(
    FleetId='string',
    Actions=[
        'AUTO_SCALING',
    ]
)
type FleetId

string

param FleetId

[REQUIRED]

Unique identifier for a fleet

type Actions

list

param Actions

[REQUIRED]

List of actions to suspend on the fleet.

  • (string) --

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

StartFleetActions (new) Link ¶

Resumes activity on a fleet that was suspended with StopFleetActions . Currently, this operation is used to restart a fleet's auto-scaling activity.

To start fleet actions, specify the fleet ID and the type of actions to restart. When auto-scaling fleet actions are restarted, Amazon GameLift once again initiates scaling events as triggered by the fleet's scaling policies. If actions on the fleet were never stopped, this operation will have no effect. You can view a fleet's stopped actions using DescribeFleetAttributes .

Operations related to fleet capacity scaling include:

  • DescribeFleetCapacity

  • UpdateFleetCapacity

  • DescribeEC2InstanceLimits

  • Manage scaling policies:

    • PutScalingPolicy (auto-scaling)

    • DescribeScalingPolicies (auto-scaling)

    • DeleteScalingPolicy (auto-scaling)

  • Manage fleet actions:

    • StartFleetActions

    • StopFleetActions

See also: AWS API Documentation

Request Syntax

client.start_fleet_actions(
    FleetId='string',
    Actions=[
        'AUTO_SCALING',
    ]
)
type FleetId

string

param FleetId

[REQUIRED]

Unique identifier for a fleet

type Actions

list

param Actions

[REQUIRED]

List of actions to restart on the fleet.

  • (string) --

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

CreateFleet (updated) Link ¶
Changes (response)
{'FleetAttributes': {'StoppedActions': ['AUTO_SCALING']}}

Creates a new fleet to run your game servers. A fleet is a set of Amazon Elastic Compute Cloud (Amazon EC2) instances, each of which can run multiple server processes to host game sessions. You set up a fleet to use instances with certain hardware specifications (see Amazon EC2 Instance Types for more information), and deploy your game build to run on each instance.

To create a new fleet, you must specify the following: (1) a fleet name, (2) the build ID of a successfully uploaded game build, (3) an EC2 instance type, and (4) a run-time configuration, which describes the server processes to run on each instance in the fleet. If you don't specify a fleet type (on-demand or spot), the new fleet uses on-demand instances by default.

You can also configure the new fleet with the following settings:

If you use Amazon CloudWatch for metrics, you can add the new fleet to a metric group. By adding multiple fleets to a metric group, you can view aggregated metrics for all the fleets in the group.

If the CreateFleet call is successful, Amazon GameLift performs the following tasks. You can track the process of a fleet by checking the fleet status or by monitoring fleet creation events:

  • Creates a fleet record. Status: NEW .

  • Begins writing events to the fleet event log, which can be accessed in the Amazon GameLift console. Sets the fleet's target capacity to 1 (desired instances), which triggers Amazon GameLift to start one new EC2 instance.

  • Downloads the game build to the new instance and installs it. Statuses: DOWNLOADING , VALIDATING , BUILDING .

  • Starts launching server processes on the instance. If the fleet is configured to run multiple server processes per instance, Amazon GameLift staggers each launch by a few seconds. Status: ACTIVATING .

  • Sets the fleet's status to ACTIVE as soon as one server process is ready to host a game session.

Fleet-related operations include:

  • CreateFleet

  • ListFleets

  • DeleteFleet

  • Describe fleets:

    • DescribeFleetAttributes

    • DescribeFleetCapacity

    • DescribeFleetPortSettings

    • DescribeFleetUtilization

    • DescribeRuntimeConfiguration

    • DescribeEC2InstanceLimits

    • DescribeFleetEvents

  • Update fleets:

    • UpdateFleetAttributes

    • UpdateFleetCapacity

    • UpdateFleetPortSettings

    • UpdateRuntimeConfiguration

  • Manage fleet actions:

    • StartFleetActions

    • StopFleetActions

See also: AWS API Documentation

Request Syntax

client.create_fleet(
    Name='string',
    Description='string',
    BuildId='string',
    ServerLaunchPath='string',
    ServerLaunchParameters='string',
    LogPaths=[
        'string',
    ],
    EC2InstanceType='t2.micro'|'t2.small'|'t2.medium'|'t2.large'|'c3.large'|'c3.xlarge'|'c3.2xlarge'|'c3.4xlarge'|'c3.8xlarge'|'c4.large'|'c4.xlarge'|'c4.2xlarge'|'c4.4xlarge'|'c4.8xlarge'|'r3.large'|'r3.xlarge'|'r3.2xlarge'|'r3.4xlarge'|'r3.8xlarge'|'r4.large'|'r4.xlarge'|'r4.2xlarge'|'r4.4xlarge'|'r4.8xlarge'|'r4.16xlarge'|'m3.medium'|'m3.large'|'m3.xlarge'|'m3.2xlarge'|'m4.large'|'m4.xlarge'|'m4.2xlarge'|'m4.4xlarge'|'m4.10xlarge',
    EC2InboundPermissions=[
        {
            'FromPort': 123,
            'ToPort': 123,
            'IpRange': 'string',
            'Protocol': 'TCP'|'UDP'
        },
    ],
    NewGameSessionProtectionPolicy='NoProtection'|'FullProtection',
    RuntimeConfiguration={
        'ServerProcesses': [
            {
                'LaunchPath': 'string',
                'Parameters': 'string',
                'ConcurrentExecutions': 123
            },
        ],
        'MaxConcurrentGameSessionActivations': 123,
        'GameSessionActivationTimeoutSeconds': 123
    },
    ResourceCreationLimitPolicy={
        'NewGameSessionsPerCreator': 123,
        'PolicyPeriodInMinutes': 123
    },
    MetricGroups=[
        'string',
    ],
    PeerVpcAwsAccountId='string',
    PeerVpcId='string',
    FleetType='ON_DEMAND'|'SPOT'
)
type Name

string

param Name

[REQUIRED]

Descriptive label that is associated with a fleet. Fleet names do not need to be unique.

type Description

string

param Description

Human-readable description of a fleet.

type BuildId

string

param BuildId

[REQUIRED]

Unique identifier for a build to be deployed on the new fleet. The build must have been successfully uploaded to Amazon GameLift and be in a READY status. This fleet setting cannot be changed once the fleet is created.

type ServerLaunchPath

string

param ServerLaunchPath

This parameter is no longer used. Instead, specify a server launch path using the RuntimeConfiguration parameter. (Requests that specify a server launch path and launch parameters instead of a run-time configuration will continue to work.)

type ServerLaunchParameters

string

param ServerLaunchParameters

This parameter is no longer used. Instead, specify server launch parameters in the RuntimeConfiguration parameter. (Requests that specify a server launch path and launch parameters instead of a run-time configuration will continue to work.)

type LogPaths

list

param LogPaths

This parameter is no longer used. Instead, to specify where Amazon GameLift should store log files once a server process shuts down, use the Amazon GameLift server API ProcessReady() and specify one or more directory paths in logParameters . See more information in the Server API Reference .

  • (string) --

type EC2InstanceType

string

param EC2InstanceType

[REQUIRED]

Name of an EC2 instance type that is supported in Amazon GameLift. A fleet instance type determines the computing resources of each instance in the fleet, including CPU, memory, storage, and networking capacity. Amazon GameLift supports the following EC2 instance types. See Amazon EC2 Instance Types for detailed descriptions.

type EC2InboundPermissions

list

param EC2InboundPermissions

Range of IP addresses and port settings that permit inbound traffic to access server processes running on the fleet. If no inbound permissions are set, including both IP address range and port range, the server processes in the fleet cannot accept connections. You can specify one or more sets of permissions for a fleet.

  • (dict) --

    A range of IP addresses and port settings that allow inbound traffic to connect to server processes on Amazon GameLift. Each game session hosted on a fleet is assigned a unique combination of IP address and port number, which must fall into the fleet's allowed ranges. This combination is included in the GameSession object.

    • FromPort (integer) -- [REQUIRED]

      Starting value for a range of allowed port numbers.

    • ToPort (integer) -- [REQUIRED]

      Ending value for a range of allowed port numbers. Port numbers are end-inclusive. This value must be higher than FromPort .

    • IpRange (string) -- [REQUIRED]

      Range of allowed IP addresses. This value must be expressed in CIDR notation. Example: "000.000.000.000/[subnet mask] " or optionally the shortened version "0.0.0.0/[subnet mask] ".

    • Protocol (string) -- [REQUIRED]

      Network communication protocol used by the fleet.

type NewGameSessionProtectionPolicy

string

param NewGameSessionProtectionPolicy

Game session protection policy to apply to all instances in this fleet. If this parameter is not set, instances in this fleet default to no protection. You can change a fleet's protection policy using UpdateFleetAttributes , but this change will only affect sessions created after the policy change. You can also set protection for individual instances using UpdateGameSession .

  • NoProtection -- The game session can be terminated during a scale-down event.

  • FullProtection -- If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.

type RuntimeConfiguration

dict

param RuntimeConfiguration

Instructions for launching server processes on each instance in the fleet. The run-time configuration for a fleet has a collection of server process configurations, one for each type of server process to run on an instance. A server process configuration specifies the location of the server executable, launch parameters, and the number of concurrent processes with that configuration to maintain on each instance. A CreateFleet request must include a run-time configuration with at least one server process configuration; otherwise the request fails with an invalid request exception. (This parameter replaces the parameters ServerLaunchPath and ServerLaunchParameters ; requests that contain values for these parameters instead of a run-time configuration will continue to work.)

  • ServerProcesses (list) --

    Collection of server process configurations that describe which server processes to run on each instance in a fleet.

    • (dict) --

      A set of instructions for launching server processes on each instance in a fleet. Each instruction set identifies the location of the server executable, optional launch parameters, and the number of server processes with this configuration to maintain concurrently on the instance. Server process configurations make up a fleet's `` RuntimeConfiguration `` .

      • LaunchPath (string) -- [REQUIRED]

        Location of the server executable in a game build. All game builds are installed on instances at the root : for Windows instances C:\game , and for Linux instances /local/game . A Windows game build with an executable file located at MyGame\latest\server.exe must have a launch path of "C:\game\MyGame\latest\server.exe ". A Linux game build with an executable file located at MyGame/latest/server.exe must have a launch path of "/local/game/MyGame/latest/server.exe ".

      • Parameters (string) --

        Optional list of parameters to pass to the server executable on launch.

      • ConcurrentExecutions (integer) -- [REQUIRED]

        Number of server processes using this configuration to run concurrently on an instance.

  • MaxConcurrentGameSessionActivations (integer) --

    Maximum number of game sessions with status ACTIVATING to allow on an instance simultaneously. This setting limits the amount of instance resources that can be used for new game activations at any one time.

  • GameSessionActivationTimeoutSeconds (integer) --

    Maximum amount of time (in seconds) that a game session can remain in status ACTIVATING . If the game session is not active before the timeout, activation is terminated and the game session status is changed to TERMINATED .

type ResourceCreationLimitPolicy

dict

param ResourceCreationLimitPolicy

Policy that limits the number of game sessions an individual player can create over a span of time for this fleet.

  • NewGameSessionsPerCreator (integer) --

    Maximum number of game sessions that an individual can create during the policy period.

  • PolicyPeriodInMinutes (integer) --

    Time span used in evaluating the resource creation limit policy.

type MetricGroups

list

param MetricGroups

Name of a metric group to add this fleet to. A metric group tracks metrics across all fleets in the group. Use an existing metric group name to add this fleet to the group, or use a new name to create a new metric group. A fleet can only be included in one metric group at a time.

  • (string) --

type PeerVpcAwsAccountId

string

param PeerVpcAwsAccountId

Unique identifier for the AWS account with the VPC that you want to peer your Amazon GameLift fleet with. You can find your Account ID in the AWS Management Console under account settings.

type PeerVpcId

string

param PeerVpcId

Unique identifier for a VPC with resources to be accessed by your Amazon GameLift fleet. The VPC must be in the same region where your fleet is deployed. To get VPC information, including IDs, use the Virtual Private Cloud service tools, including the VPC Dashboard in the AWS Management Console.

type FleetType

string

param FleetType

Indicates whether to use on-demand instances or spot instances for this fleet. If empty, the default is ON_DEMAND. Both categories of instances use identical hardware and configurations, based on the instance type selected for this fleet. You can acquire on-demand instances at any time for a fixed price and keep them as long as you need them. Spot instances have lower prices, but spot pricing is variable, and while in use they can be interrupted (with a two-minute notification). Learn more about Amazon GameLift spot instances with at Choose Computing Resources .

rtype

dict

returns

Response Syntax

{
    'FleetAttributes': {
        'FleetId': 'string',
        'FleetArn': 'string',
        'FleetType': 'ON_DEMAND'|'SPOT',
        'InstanceType': 't2.micro'|'t2.small'|'t2.medium'|'t2.large'|'c3.large'|'c3.xlarge'|'c3.2xlarge'|'c3.4xlarge'|'c3.8xlarge'|'c4.large'|'c4.xlarge'|'c4.2xlarge'|'c4.4xlarge'|'c4.8xlarge'|'r3.large'|'r3.xlarge'|'r3.2xlarge'|'r3.4xlarge'|'r3.8xlarge'|'r4.large'|'r4.xlarge'|'r4.2xlarge'|'r4.4xlarge'|'r4.8xlarge'|'r4.16xlarge'|'m3.medium'|'m3.large'|'m3.xlarge'|'m3.2xlarge'|'m4.large'|'m4.xlarge'|'m4.2xlarge'|'m4.4xlarge'|'m4.10xlarge',
        'Description': 'string',
        'Name': 'string',
        'CreationTime': datetime(2015, 1, 1),
        'TerminationTime': datetime(2015, 1, 1),
        'Status': 'NEW'|'DOWNLOADING'|'VALIDATING'|'BUILDING'|'ACTIVATING'|'ACTIVE'|'DELETING'|'ERROR'|'TERMINATED',
        'BuildId': 'string',
        'ServerLaunchPath': 'string',
        'ServerLaunchParameters': 'string',
        'LogPaths': [
            'string',
        ],
        'NewGameSessionProtectionPolicy': 'NoProtection'|'FullProtection',
        'OperatingSystem': 'WINDOWS_2012'|'AMAZON_LINUX',
        'ResourceCreationLimitPolicy': {
            'NewGameSessionsPerCreator': 123,
            'PolicyPeriodInMinutes': 123
        },
        'MetricGroups': [
            'string',
        ],
        'StoppedActions': [
            'AUTO_SCALING',
        ]
    }
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • FleetAttributes (dict) --

      Properties for the newly created fleet.

      • FleetId (string) --

        Unique identifier for a fleet.

      • FleetArn (string) --

        Identifier for a fleet that is unique across all regions.

      • FleetType (string) --

        Indicates whether the fleet uses on-demand or spot instances. A spot instance in use may be interrupted with a two-minute notification.

      • InstanceType (string) --

        EC2 instance type indicating the computing resources of each instance in the fleet, including CPU, memory, storage, and networking capacity. See Amazon EC2 Instance Types for detailed descriptions.

      • Description (string) --

        Human-readable description of the fleet.

      • Name (string) --

        Descriptive label that is associated with a fleet. Fleet names do not need to be unique.

      • CreationTime (datetime) --

        Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").

      • TerminationTime (datetime) --

        Time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").

      • Status (string) --

        Current status of the fleet.

        Possible fleet statuses include the following:

        • NEW -- A new fleet has been defined and desired instances is set to 1.

        • DOWNLOADING/VALIDATING/BUILDING/ACTIVATING -- Amazon GameLift is setting up the new fleet, creating new instances with the game build and starting server processes.

        • ACTIVE -- Hosts can now accept game sessions.

        • ERROR -- An error occurred when downloading, validating, building, or activating the fleet.

        • DELETING -- Hosts are responding to a delete fleet request.

        • TERMINATED -- The fleet no longer exists.

      • BuildId (string) --

        Unique identifier for a build.

      • ServerLaunchPath (string) --

        Path to a game server executable in the fleet's build, specified for fleets created before 2016-08-04 (or AWS SDK v. 0.12.16). Server launch paths for fleets created after this date are specified in the fleet's RuntimeConfiguration .

      • ServerLaunchParameters (string) --

        Game server launch parameters specified for fleets created before 2016-08-04 (or AWS SDK v. 0.12.16). Server launch parameters for fleets created after this date are specified in the fleet's RuntimeConfiguration .

      • LogPaths (list) --

        Location of default log files. When a server process is shut down, Amazon GameLift captures and stores any log files in this location. These logs are in addition to game session logs; see more on game session logs in the Amazon GameLift Developer Guide . If no default log path for a fleet is specified, Amazon GameLift automatically uploads logs that are stored on each instance at C:\game\logs (for Windows) or /local/game/logs (for Linux). Use the Amazon GameLift console to access stored logs.

        • (string) --

      • NewGameSessionProtectionPolicy (string) --

        Type of game session protection to set for all new instances started in the fleet.

        • NoProtection -- The game session can be terminated during a scale-down event.

        • FullProtection -- If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.

      • OperatingSystem (string) --

        Operating system of the fleet's computing resources. A fleet's operating system depends on the OS specified for the build that is deployed on this fleet.

      • ResourceCreationLimitPolicy (dict) --

        Fleet policy to limit the number of game sessions an individual player can create over a span of time.

        • NewGameSessionsPerCreator (integer) --

          Maximum number of game sessions that an individual can create during the policy period.

        • PolicyPeriodInMinutes (integer) --

          Time span used in evaluating the resource creation limit policy.

      • MetricGroups (list) --

        Names of metric groups that this fleet is included in. In Amazon CloudWatch, you can view metrics for an individual fleet or aggregated metrics for fleets that are in a fleet metric group. A fleet can be included in only one metric group at a time.

        • (string) --

      • StoppedActions (list) --

        List of fleet actions that have been suspended using StopFleetActions . This includes auto-scaling.

        • (string) --

DescribeFleetAttributes (updated) Link ¶
Changes (response)
{'FleetAttributes': {'StoppedActions': ['AUTO_SCALING']}}

Retrieves fleet properties, including metadata, status, and configuration, for one or more fleets. You can request attributes for all fleets, or specify a list of one or more fleet IDs. When requesting multiple fleets, use the pagination parameters to retrieve results as a set of sequential pages. If successful, a FleetAttributes object is returned for each requested fleet ID. When specifying a list of fleet IDs, attribute objects are returned only for fleets that currently exist.

Note

Some API actions may limit the number of fleet IDs allowed in one request. If a request exceeds this limit, the request fails and the error message includes the maximum allowed.

Fleet-related operations include:

  • CreateFleet

  • ListFleets

  • DeleteFleet

  • Describe fleets:

    • DescribeFleetAttributes

    • DescribeFleetCapacity

    • DescribeFleetPortSettings

    • DescribeFleetUtilization

    • DescribeRuntimeConfiguration

    • DescribeEC2InstanceLimits

    • DescribeFleetEvents

  • Update fleets:

    • UpdateFleetAttributes

    • UpdateFleetCapacity

    • UpdateFleetPortSettings

    • UpdateRuntimeConfiguration

  • Manage fleet actions:

    • StartFleetActions

    • StopFleetActions

See also: AWS API Documentation

Request Syntax

client.describe_fleet_attributes(
    FleetIds=[
        'string',
    ],
    Limit=123,
    NextToken='string'
)
type FleetIds

list

param FleetIds

Unique identifier for a fleet(s) to retrieve attributes for. To request attributes for all fleets, leave this parameter empty.

  • (string) --

type Limit

integer

param Limit

Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages. This parameter is ignored when the request specifies one or a list of fleet IDs.

type NextToken

string

param NextToken

Token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To start at the beginning of the result set, do not specify a value. This parameter is ignored when the request specifies one or a list of fleet IDs.

rtype

dict

returns

Response Syntax

{
    'FleetAttributes': [
        {
            'FleetId': 'string',
            'FleetArn': 'string',
            'FleetType': 'ON_DEMAND'|'SPOT',
            'InstanceType': 't2.micro'|'t2.small'|'t2.medium'|'t2.large'|'c3.large'|'c3.xlarge'|'c3.2xlarge'|'c3.4xlarge'|'c3.8xlarge'|'c4.large'|'c4.xlarge'|'c4.2xlarge'|'c4.4xlarge'|'c4.8xlarge'|'r3.large'|'r3.xlarge'|'r3.2xlarge'|'r3.4xlarge'|'r3.8xlarge'|'r4.large'|'r4.xlarge'|'r4.2xlarge'|'r4.4xlarge'|'r4.8xlarge'|'r4.16xlarge'|'m3.medium'|'m3.large'|'m3.xlarge'|'m3.2xlarge'|'m4.large'|'m4.xlarge'|'m4.2xlarge'|'m4.4xlarge'|'m4.10xlarge',
            'Description': 'string',
            'Name': 'string',
            'CreationTime': datetime(2015, 1, 1),
            'TerminationTime': datetime(2015, 1, 1),
            'Status': 'NEW'|'DOWNLOADING'|'VALIDATING'|'BUILDING'|'ACTIVATING'|'ACTIVE'|'DELETING'|'ERROR'|'TERMINATED',
            'BuildId': 'string',
            'ServerLaunchPath': 'string',
            'ServerLaunchParameters': 'string',
            'LogPaths': [
                'string',
            ],
            'NewGameSessionProtectionPolicy': 'NoProtection'|'FullProtection',
            'OperatingSystem': 'WINDOWS_2012'|'AMAZON_LINUX',
            'ResourceCreationLimitPolicy': {
                'NewGameSessionsPerCreator': 123,
                'PolicyPeriodInMinutes': 123
            },
            'MetricGroups': [
                'string',
            ],
            'StoppedActions': [
                'AUTO_SCALING',
            ]
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • FleetAttributes (list) --

      Collection of objects containing attribute metadata for each requested fleet ID.

      • (dict) --

        General properties describing a fleet.

        Fleet-related operations include:

        • CreateFleet

        • ListFleets

        • DeleteFleet

        • Describe fleets:

          • DescribeFleetAttributes

          • DescribeFleetCapacity

          • DescribeFleetPortSettings

          • DescribeFleetUtilization

          • DescribeRuntimeConfiguration

          • DescribeEC2InstanceLimits

          • DescribeFleetEvents

        • Update fleets:

          • UpdateFleetAttributes

          • UpdateFleetCapacity

          • UpdateFleetPortSettings

          • UpdateRuntimeConfiguration

        • Manage fleet actions:

          • StartFleetActions

          • StopFleetActions

        • FleetId (string) --

          Unique identifier for a fleet.

        • FleetArn (string) --

          Identifier for a fleet that is unique across all regions.

        • FleetType (string) --

          Indicates whether the fleet uses on-demand or spot instances. A spot instance in use may be interrupted with a two-minute notification.

        • InstanceType (string) --

          EC2 instance type indicating the computing resources of each instance in the fleet, including CPU, memory, storage, and networking capacity. See Amazon EC2 Instance Types for detailed descriptions.

        • Description (string) --

          Human-readable description of the fleet.

        • Name (string) --

          Descriptive label that is associated with a fleet. Fleet names do not need to be unique.

        • CreationTime (datetime) --

          Time stamp indicating when this data object was created. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").

        • TerminationTime (datetime) --

          Time stamp indicating when this data object was terminated. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").

        • Status (string) --

          Current status of the fleet.

          Possible fleet statuses include the following:

          • NEW -- A new fleet has been defined and desired instances is set to 1.

          • DOWNLOADING/VALIDATING/BUILDING/ACTIVATING -- Amazon GameLift is setting up the new fleet, creating new instances with the game build and starting server processes.

          • ACTIVE -- Hosts can now accept game sessions.

          • ERROR -- An error occurred when downloading, validating, building, or activating the fleet.

          • DELETING -- Hosts are responding to a delete fleet request.

          • TERMINATED -- The fleet no longer exists.

        • BuildId (string) --

          Unique identifier for a build.

        • ServerLaunchPath (string) --

          Path to a game server executable in the fleet's build, specified for fleets created before 2016-08-04 (or AWS SDK v. 0.12.16). Server launch paths for fleets created after this date are specified in the fleet's RuntimeConfiguration .

        • ServerLaunchParameters (string) --

          Game server launch parameters specified for fleets created before 2016-08-04 (or AWS SDK v. 0.12.16). Server launch parameters for fleets created after this date are specified in the fleet's RuntimeConfiguration .

        • LogPaths (list) --

          Location of default log files. When a server process is shut down, Amazon GameLift captures and stores any log files in this location. These logs are in addition to game session logs; see more on game session logs in the Amazon GameLift Developer Guide . If no default log path for a fleet is specified, Amazon GameLift automatically uploads logs that are stored on each instance at C:\game\logs (for Windows) or /local/game/logs (for Linux). Use the Amazon GameLift console to access stored logs.

          • (string) --

        • NewGameSessionProtectionPolicy (string) --

          Type of game session protection to set for all new instances started in the fleet.

          • NoProtection -- The game session can be terminated during a scale-down event.

          • FullProtection -- If the game session is in an ACTIVE status, it cannot be terminated during a scale-down event.

        • OperatingSystem (string) --

          Operating system of the fleet's computing resources. A fleet's operating system depends on the OS specified for the build that is deployed on this fleet.

        • ResourceCreationLimitPolicy (dict) --

          Fleet policy to limit the number of game sessions an individual player can create over a span of time.

          • NewGameSessionsPerCreator (integer) --

            Maximum number of game sessions that an individual can create during the policy period.

          • PolicyPeriodInMinutes (integer) --

            Time span used in evaluating the resource creation limit policy.

        • MetricGroups (list) --

          Names of metric groups that this fleet is included in. In Amazon CloudWatch, you can view metrics for an individual fleet or aggregated metrics for fleets that are in a fleet metric group. A fleet can be included in only one metric group at a time.

          • (string) --

        • StoppedActions (list) --

          List of fleet actions that have been suspended using StopFleetActions . This includes auto-scaling.

          • (string) --

    • NextToken (string) --

      Token that indicates where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.

DescribeScalingPolicies (updated) Link ¶
Changes (response)
{'ScalingPolicies': {'PolicyType': 'RuleBased | TargetBased',
                     'TargetConfiguration': {'TargetValue': 'double'}}}

Retrieves all scaling policies applied to a fleet.

To get a fleet's scaling policies, specify the fleet ID. You can filter this request by policy status, such as to retrieve only active scaling policies. Use the pagination parameters to retrieve results as a set of sequential pages. If successful, set of ScalingPolicy objects is returned for the fleet.

A fleet may have all of its scaling policies suspended ( StopFleetActions ). This action does not affect the status of the scaling policies, which remains ACTIVE. To see whether a fleet's scaling policies are in force or suspended, call DescribeFleetAttributes and check the stopped actions.

Operations related to fleet capacity scaling include:

  • DescribeFleetCapacity

  • UpdateFleetCapacity

  • DescribeEC2InstanceLimits

  • Manage scaling policies:

    • PutScalingPolicy (auto-scaling)

    • DescribeScalingPolicies (auto-scaling)

    • DeleteScalingPolicy (auto-scaling)

  • Manage fleet actions:

    • StartFleetActions

    • StopFleetActions

See also: AWS API Documentation

Request Syntax

client.describe_scaling_policies(
    FleetId='string',
    StatusFilter='ACTIVE'|'UPDATE_REQUESTED'|'UPDATING'|'DELETE_REQUESTED'|'DELETING'|'DELETED'|'ERROR',
    Limit=123,
    NextToken='string'
)
type FleetId

string

param FleetId

[REQUIRED]

Unique identifier for a fleet to retrieve scaling policies for.

type StatusFilter

string

param StatusFilter

Scaling policy status to filter results on. A scaling policy is only in force when in an ACTIVE status.

  • ACTIVE -- The scaling policy is currently in force.

  • UPDATEREQUESTED -- A request to update the scaling policy has been received.

  • UPDATING -- A change is being made to the scaling policy.

  • DELETEREQUESTED -- A request to delete the scaling policy has been received.

  • DELETING -- The scaling policy is being deleted.

  • DELETED -- The scaling policy has been deleted.

  • ERROR -- An error occurred in creating the policy. It should be removed and recreated.

type Limit

integer

param Limit

Maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages.

type NextToken

string

param NextToken

Token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this action. To start at the beginning of the result set, do not specify a value.

rtype

dict

returns

Response Syntax

{
    'ScalingPolicies': [
        {
            'FleetId': 'string',
            'Name': 'string',
            'Status': 'ACTIVE'|'UPDATE_REQUESTED'|'UPDATING'|'DELETE_REQUESTED'|'DELETING'|'DELETED'|'ERROR',
            'ScalingAdjustment': 123,
            'ScalingAdjustmentType': 'ChangeInCapacity'|'ExactCapacity'|'PercentChangeInCapacity',
            'ComparisonOperator': 'GreaterThanOrEqualToThreshold'|'GreaterThanThreshold'|'LessThanThreshold'|'LessThanOrEqualToThreshold',
            'Threshold': 123.0,
            'EvaluationPeriods': 123,
            'MetricName': 'ActivatingGameSessions'|'ActiveGameSessions'|'ActiveInstances'|'AvailableGameSessions'|'AvailablePlayerSessions'|'CurrentPlayerSessions'|'IdleInstances'|'PercentAvailableGameSessions'|'PercentIdleInstances'|'QueueDepth'|'WaitTime',
            'PolicyType': 'RuleBased'|'TargetBased',
            'TargetConfiguration': {
                'TargetValue': 123.0
            }
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • ScalingPolicies (list) --

      Collection of objects containing the scaling policies matching the request.

      • (dict) --

        Rule that controls how a fleet is scaled. Scaling policies are uniquely identified by the combination of name and fleet ID.

        Operations related to fleet capacity scaling include:

        • DescribeFleetCapacity

        • UpdateFleetCapacity

        • DescribeEC2InstanceLimits

        • Manage scaling policies:

          • PutScalingPolicy (auto-scaling)

          • DescribeScalingPolicies (auto-scaling)

          • DeleteScalingPolicy (auto-scaling)

        • Manage fleet actions:

          • StartFleetActions

          • StopFleetActions

        • FleetId (string) --

          Unique identifier for a fleet that is associated with this scaling policy.

        • Name (string) --

          Descriptive label that is associated with a scaling policy. Policy names do not need to be unique.

        • Status (string) --

          Current status of the scaling policy. The scaling policy can be in force only when in an ACTIVE status. Scaling policies can be suspended for individual fleets (see StopFleetActions ; if suspended for a fleet, the policy status does not change. View a fleet's stopped actions by calling DescribeFleetCapacity .

          • ACTIVE -- The scaling policy can be used for auto-scaling a fleet.

          • UPDATE_REQUESTED -- A request to update the scaling policy has been received.

          • UPDATING -- A change is being made to the scaling policy.

          • DELETE_REQUESTED -- A request to delete the scaling policy has been received.

          • DELETING -- The scaling policy is being deleted.

          • DELETED -- The scaling policy has been deleted.

          • ERROR -- An error occurred in creating the policy. It should be removed and recreated.

        • ScalingAdjustment (integer) --

          Amount of adjustment to make, based on the scaling adjustment type.

        • ScalingAdjustmentType (string) --

          Type of adjustment to make to a fleet's instance count (see FleetCapacity ):

          • ChangeInCapacity -- add (or subtract) the scaling adjustment value from the current instance count. Positive values scale up while negative values scale down.

          • ExactCapacity -- set the instance count to the scaling adjustment value.

          • PercentChangeInCapacity -- increase or reduce the current instance count by the scaling adjustment, read as a percentage. Positive values scale up while negative values scale down.

        • ComparisonOperator (string) --

          Comparison operator to use when measuring a metric against the threshold value.

        • Threshold (float) --

          Metric value used to trigger a scaling event.

        • EvaluationPeriods (integer) --

          Length of time (in minutes) the metric must be at or beyond the threshold before a scaling event is triggered.

        • MetricName (string) --

          Name of the Amazon GameLift-defined metric that is used to trigger a scaling adjustment. For detailed descriptions of fleet metrics, see Monitor Amazon GameLift with Amazon CloudWatch .

          • ActivatingGameSessions -- Game sessions in the process of being created.

          • ActiveGameSessions -- Game sessions that are currently running.

          • ActiveInstances -- Fleet instances that are currently running at least one game session.

          • AvailableGameSessions -- Additional game sessions that fleet could host simultaneously, given current capacity.

          • AvailablePlayerSessions -- Empty player slots in currently active game sessions. This includes game sessions that are not currently accepting players. Reserved player slots are not included.

          • CurrentPlayerSessions -- Player slots in active game sessions that are being used by a player or are reserved for a player.

          • IdleInstances -- Active instances that are currently hosting zero game sessions.

          • PercentAvailableGameSessions -- Unused percentage of the total number of game sessions that a fleet could host simultaneously, given current capacity. Use this metric for a target-based scaling policy.

          • PercentIdleInstances -- Percentage of the total number of active instances that are hosting zero game sessions.

          • QueueDepth -- Pending game session placement requests, in any queue, where the current fleet is the top-priority destination.

          • WaitTime -- Current wait time for pending game session placement requests, in any queue, where the current fleet is the top-priority destination.

        • PolicyType (string) --

          Type of scaling policy to create. For a target-based policy, set the parameter MetricName to 'PercentAvailableGameSessions' and specify a TargetConfiguration . For a rule-based policy set the following parameters: MetricName , ComparisonOperator , Threshold , EvaluationPeriods , ScalingAdjustmentType , and ScalingAdjustment .

        • TargetConfiguration (dict) --

          Object that contains settings for a target-based scaling policy.

          • TargetValue (float) --

            Desired value to use with a target-based scaling policy. The value must be relevant for whatever metric the scaling policy is using. For example, in a policy using the metric PercentAvailableGameSessions, the target value should be the preferred size of the fleet's buffer (the percent of capacity that should be idle and ready for new game sessions).

    • NextToken (string) --

      Token that indicates where to resume retrieving results on the next call to this action. If no token is returned, these results represent the end of the list.

PutScalingPolicy (updated) Link ¶
Changes (request)
{'PolicyType': 'RuleBased | TargetBased',
 'TargetConfiguration': {'TargetValue': 'double'}}

Creates or updates a scaling policy for a fleet. Scaling policies are used to automatically scale a fleet's hosting capacity to meet player demand. An active scaling policy instructs Amazon GameLift to track a fleet metric and automatically change the fleet's capacity when a certain threshold is reached. There are two types of scaling policies: target-based and rule-based. Use a target-based policy to quickly and efficiently manage fleet scaling; this option is the most commonly used. Use rule-based policies when you need to exert fine-grained control over auto-scaling.

Fleets can have multiple scaling policies of each type in force at the same time; you can have one target-based policy, one or multiple rule-based scaling policies, or both. We recommend caution, however, because multiple auto-scaling policies can have unintended consequences.

You can temporarily suspend all scaling policies for a fleet by calling StopFleetActions with the fleet action AUTO_SCALING. To resume scaling policies, call StartFleetActions with the same fleet action. To stop just one scaling policy--or to permanently remove it, you must delete the policy with DeleteScalingPolicy .

Learn more about how to work with auto-scaling in Set Up Fleet Automatic Scaling .

Target-based policy

A target-based policy tracks a single metric: PercentAvailableGameSessions. This metric tells us how much of a fleet's hosting capacity is ready to host game sessions but is not currently in use. This is the fleet's buffer; it measures the additional player demand that the fleet could handle at current capacity. With a target-based policy, you set your ideal buffer size and leave it to Amazon GameLift to take whatever action is needed to maintain that target.

For example, you might choose to maintain a 10% buffer for a fleet that has the capacity to host 100 simultaneous game sessions. This policy tells Amazon GameLift to take action whenever the fleet's available capacity falls below or rises above 10 game sessions. Amazon GameLift will start new instances or stop unused instances in order to return to the 10% buffer.

To create or update a target-based policy, specify a fleet ID and name, and set the policy type to "TargetBased". Specify the metric to track (PercentAvailableGameSessions) and reference a TargetConfiguration object with your desired buffer value. Exclude all other parameters. On a successful request, the policy name is returned. The scaling policy is automatically in force as soon as it's successfully created. If the fleet's auto-scaling actions are temporarily suspended, the new policy will be in force once the fleet actions are restarted.

Rule-based policy

A rule-based policy tracks specified fleet metric, sets a threshold value, and specifies the type of action to initiate when triggered. With a rule-based policy, you can select from several available fleet metrics. Each policy specifies whether to scale up or scale down (and by how much), so you need one policy for each type of action.

For example, a policy may make the following statement: "If the percentage of idle instances is greater than 20% for more than 15 minutes, then reduce the fleet capacity by 10%."

A policy's rule statement has the following structure:

If [MetricName] is [ComparisonOperator] [Threshold] for [EvaluationPeriods] minutes, then [ScalingAdjustmentType] to/by [ScalingAdjustment] .

To implement the example, the rule statement would look like this:

If [PercentIdleInstances] is [GreaterThanThreshold] [20] for [15] minutes, then [PercentChangeInCapacity] to/by [10] .

To create or update a scaling policy, specify a unique combination of name and fleet ID, and set the policy type to "RuleBased". Specify the parameter values for a policy rule statement. On a successful request, the policy name is returned. Scaling policies are automatically in force as soon as they're successfully created. If the fleet's auto-scaling actions are temporarily suspended, the new policy will be in force once the fleet actions are restarted.

Operations related to fleet capacity scaling include:

  • DescribeFleetCapacity

  • UpdateFleetCapacity

  • DescribeEC2InstanceLimits

  • Manage scaling policies:

    • PutScalingPolicy (auto-scaling)

    • DescribeScalingPolicies (auto-scaling)

    • DeleteScalingPolicy (auto-scaling)

  • Manage fleet actions:

    • StartFleetActions

    • StopFleetActions

See also: AWS API Documentation

Request Syntax

client.put_scaling_policy(
    Name='string',
    FleetId='string',
    ScalingAdjustment=123,
    ScalingAdjustmentType='ChangeInCapacity'|'ExactCapacity'|'PercentChangeInCapacity',
    Threshold=123.0,
    ComparisonOperator='GreaterThanOrEqualToThreshold'|'GreaterThanThreshold'|'LessThanThreshold'|'LessThanOrEqualToThreshold',
    EvaluationPeriods=123,
    MetricName='ActivatingGameSessions'|'ActiveGameSessions'|'ActiveInstances'|'AvailableGameSessions'|'AvailablePlayerSessions'|'CurrentPlayerSessions'|'IdleInstances'|'PercentAvailableGameSessions'|'PercentIdleInstances'|'QueueDepth'|'WaitTime',
    PolicyType='RuleBased'|'TargetBased',
    TargetConfiguration={
        'TargetValue': 123.0
    }
)
type Name

string

param Name

[REQUIRED]

Descriptive label that is associated with a scaling policy. Policy names do not need to be unique. A fleet can have only one scaling policy with the same name.

type FleetId

string

param FleetId

[REQUIRED]

Unique identifier for a fleet to apply this policy to. The fleet cannot be in any of the following statuses: ERROR or DELETING.

type ScalingAdjustment

integer

param ScalingAdjustment

Amount of adjustment to make, based on the scaling adjustment type.

type ScalingAdjustmentType

string

param ScalingAdjustmentType

Type of adjustment to make to a fleet's instance count (see FleetCapacity ):

  • ChangeInCapacity -- add (or subtract) the scaling adjustment value from the current instance count. Positive values scale up while negative values scale down.

  • ExactCapacity -- set the instance count to the scaling adjustment value.

  • PercentChangeInCapacity -- increase or reduce the current instance count by the scaling adjustment, read as a percentage. Positive values scale up while negative values scale down; for example, a value of "-10" scales the fleet down by 10%.

type Threshold

float

param Threshold

Metric value used to trigger a scaling event.

type ComparisonOperator

string

param ComparisonOperator

Comparison operator to use when measuring the metric against the threshold value.

type EvaluationPeriods

integer

param EvaluationPeriods

Length of time (in minutes) the metric must be at or beyond the threshold before a scaling event is triggered.

type MetricName

string

param MetricName

[REQUIRED]

Name of the Amazon GameLift-defined metric that is used to trigger a scaling adjustment. For detailed descriptions of fleet metrics, see Monitor Amazon GameLift with Amazon CloudWatch .

  • ActivatingGameSessions -- Game sessions in the process of being created.

  • ActiveGameSessions -- Game sessions that are currently running.

  • ActiveInstances -- Fleet instances that are currently running at least one game session.

  • AvailableGameSessions -- Additional game sessions that fleet could host simultaneously, given current capacity.

  • AvailablePlayerSessions -- Empty player slots in currently active game sessions. This includes game sessions that are not currently accepting players. Reserved player slots are not included.

  • CurrentPlayerSessions -- Player slots in active game sessions that are being used by a player or are reserved for a player.

  • IdleInstances -- Active instances that are currently hosting zero game sessions.

  • PercentAvailableGameSessions -- Unused percentage of the total number of game sessions that a fleet could host simultaneously, given current capacity. Use this metric for a target-based scaling policy.

  • PercentIdleInstances -- Percentage of the total number of active instances that are hosting zero game sessions.

  • QueueDepth -- Pending game session placement requests, in any queue, where the current fleet is the top-priority destination.

  • WaitTime -- Current wait time for pending game session placement requests, in any queue, where the current fleet is the top-priority destination.

type PolicyType

string

param PolicyType

Type of scaling policy to create. For a target-based policy, set the parameter MetricName to 'PercentAvailableGameSessions' and specify a TargetConfiguration . For a rule-based policy set the following parameters: MetricName , ComparisonOperator , Threshold , EvaluationPeriods , ScalingAdjustmentType , and ScalingAdjustment .

type TargetConfiguration

dict

param TargetConfiguration

Object that contains settings for a target-based scaling policy.

  • TargetValue (float) -- [REQUIRED]

    Desired value to use with a target-based scaling policy. The value must be relevant for whatever metric the scaling policy is using. For example, in a policy using the metric PercentAvailableGameSessions, the target value should be the preferred size of the fleet's buffer (the percent of capacity that should be idle and ready for new game sessions).

rtype

dict

returns

Response Syntax

{
    'Name': 'string'
}

Response Structure

  • (dict) --

    Represents the returned data in response to a request action.

    • Name (string) --

      Descriptive label that is associated with a scaling policy. Policy names do not need to be unique.