describe_instances

describe_instances(**kwargs)

Retrieves information about a fleet's instances, including instance IDs, connection data, and status.

This operation can be used in the following ways:

  • To get information on all instances that are deployed to a fleet's home Region, provide the fleet ID.
  • To get information on all instances that are deployed to a fleet's remote location, provide the fleet ID and location name.
  • To get information on a specific instance in a fleet, provide the fleet ID and instance ID.

Use the pagination parameters to retrieve results as a set of sequential pages.

If successful, an Instance object is returned for each requested instance. Instances are not returned in any particular order.

See also: AWS API Documentation

Request Syntax

response = client.describe_instances(
    FleetId='string',
    InstanceId='string',
    Limit=123,
    NextToken='string',
    Location='string'
)
Parameters
  • FleetId (string) --

    [REQUIRED]

    A unique identifier for the fleet to retrieve instance information for. You can use either the fleet ID or ARN value.

  • InstanceId (string) -- A unique identifier for an instance to retrieve. Specify an instance ID or leave blank to retrieve all instances in the fleet.
  • Limit (integer) -- The maximum number of results to return. Use this parameter with NextToken to get results as a set of sequential pages.
  • NextToken (string) -- A token that indicates the start of the next sequential page of results. Use the token that is returned with a previous call to this operation. To start at the beginning of the result set, do not specify a value.
  • Location (string) -- The name of a location to retrieve instance information for, in the form of an Amazon Web Services Region code such as us-west-2 .
Return type

dict

Returns

Response Syntax

{
    'Instances': [
        {
            'FleetId': 'string',
            'FleetArn': 'string',
            'InstanceId': 'string',
            'IpAddress': 'string',
            'DnsName': 'string',
            'OperatingSystem': 'WINDOWS_2012'|'AMAZON_LINUX'|'AMAZON_LINUX_2',
            'Type': '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'|'c5.large'|'c5.xlarge'|'c5.2xlarge'|'c5.4xlarge'|'c5.9xlarge'|'c5.12xlarge'|'c5.18xlarge'|'c5.24xlarge'|'c5a.large'|'c5a.xlarge'|'c5a.2xlarge'|'c5a.4xlarge'|'c5a.8xlarge'|'c5a.12xlarge'|'c5a.16xlarge'|'c5a.24xlarge'|'r3.large'|'r3.xlarge'|'r3.2xlarge'|'r3.4xlarge'|'r3.8xlarge'|'r4.large'|'r4.xlarge'|'r4.2xlarge'|'r4.4xlarge'|'r4.8xlarge'|'r4.16xlarge'|'r5.large'|'r5.xlarge'|'r5.2xlarge'|'r5.4xlarge'|'r5.8xlarge'|'r5.12xlarge'|'r5.16xlarge'|'r5.24xlarge'|'r5a.large'|'r5a.xlarge'|'r5a.2xlarge'|'r5a.4xlarge'|'r5a.8xlarge'|'r5a.12xlarge'|'r5a.16xlarge'|'r5a.24xlarge'|'m3.medium'|'m3.large'|'m3.xlarge'|'m3.2xlarge'|'m4.large'|'m4.xlarge'|'m4.2xlarge'|'m4.4xlarge'|'m4.10xlarge'|'m5.large'|'m5.xlarge'|'m5.2xlarge'|'m5.4xlarge'|'m5.8xlarge'|'m5.12xlarge'|'m5.16xlarge'|'m5.24xlarge'|'m5a.large'|'m5a.xlarge'|'m5a.2xlarge'|'m5a.4xlarge'|'m5a.8xlarge'|'m5a.12xlarge'|'m5a.16xlarge'|'m5a.24xlarge'|'c5d.large'|'c5d.xlarge'|'c5d.2xlarge'|'c5d.4xlarge'|'c5d.9xlarge'|'c5d.12xlarge'|'c5d.18xlarge'|'c5d.24xlarge'|'c6a.large'|'c6a.xlarge'|'c6a.2xlarge'|'c6a.4xlarge'|'c6a.8xlarge'|'c6a.12xlarge'|'c6a.16xlarge'|'c6a.24xlarge'|'c6i.large'|'c6i.xlarge'|'c6i.2xlarge'|'c6i.4xlarge'|'c6i.8xlarge'|'c6i.12xlarge'|'c6i.16xlarge'|'c6i.24xlarge'|'r5d.large'|'r5d.xlarge'|'r5d.2xlarge'|'r5d.4xlarge'|'r5d.8xlarge'|'r5d.12xlarge'|'r5d.16xlarge'|'r5d.24xlarge',
            'Status': 'PENDING'|'ACTIVE'|'TERMINATING',
            'CreationTime': datetime(2015, 1, 1),
            'Location': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Instances (list) --

      A collection of objects containing properties for each instance returned.

      • (dict) --

        Represents an EC2 instance of virtual computing resources that hosts one or more game servers. In GameLift, a fleet can contain zero or more instances.

        Related actions

        • FleetId (string) --

          A unique identifier for the fleet that the instance is in.

        • FleetArn (string) --

          The Amazon Resource Name ( ARN ) that is assigned to a GameLift fleet resource and uniquely identifies it. ARNs are unique across all Regions. Format is arn:aws:gamelift:<region>::fleet/fleet-a1234567-b8c9-0d1e-2fa3-b45c6d7e8912 .

        • InstanceId (string) --

          A unique identifier for the instance.

        • IpAddress (string) --

          IP address that is assigned to the instance.

        • DnsName (string) --

          The DNS identifier assigned to the instance that is running the game session. Values have the following format:

          • TLS-enabled fleets: <unique identifier>.<region identifier>.amazongamelift.com .
          • Non-TLS-enabled fleets: ec2-<unique identifier>.compute.amazonaws.com . (See Amazon EC2 Instance IP Addressing.)

          When connecting to a game session that is running on a TLS-enabled fleet, you must use the DNS name, not the IP address.

        • OperatingSystem (string) --

          Operating system that is running on this instance.

        • Type (string) --

          Amazon EC2 instance type that defines the computing resources of this instance.

        • Status (string) --

          Current status of the instance. Possible statuses include the following:

          • PENDING -- The instance is in the process of being created and launching server processes as defined in the fleet's run-time configuration.
          • ACTIVE -- The instance has been successfully created and at least one server process has successfully launched and reported back to GameLift that it is ready to host a game session. The instance is now considered ready to host game sessions.
          • TERMINATING -- The instance is in the process of shutting down. This may happen to reduce capacity during a scaling down event or to recycle resources in the event of a problem.
        • CreationTime (datetime) --

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

        • Location (string) --

          The fleet location of the instance, expressed as an Amazon Web Services Region code, such as us-west-2 .

    • NextToken (string) --

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

Exceptions

  • GameLift.Client.exceptions.UnauthorizedException
  • GameLift.Client.exceptions.InvalidRequestException
  • GameLift.Client.exceptions.NotFoundException
  • GameLift.Client.exceptions.InternalServiceException
  • GameLift.Client.exceptions.UnsupportedRegionException