Sign In to the Console
Amazon GameLift Service
API Reference (API Version 2015-10-01)
AWS Documentation » Amazon GameLift » API Reference » Actions » GetInstanceAccess
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

GetInstanceAccess

Requests remote access to a fleet instance. Remote access is useful for debugging, gathering benchmarking data, or watching activity in real time.

Access requires credentials that match the operating system of the instance. For a Windows instance, Amazon GameLift returns a user name and password as strings for use with a Windows Remote Desktop client. For a Linux instance, Amazon GameLift returns a user name and RSA private key, also as strings, for use with an SSH client. The private key must be saved in the proper format to a .pem file before using. If you're making this request using the AWS CLI, saving the secret can be handled as part of the GetInstanceAccess request. (See the example later in this topic). For more information on remote access, see Remotely Accessing an Instance.

To request access to a specific instance, specify the IDs of both the instance and the fleet it belongs to. You can retrieve a fleet's instance IDs by calling DescribeInstances. If successful, an InstanceAccess object is returned containing the instance's IP address and a set of credentials.

Request Syntax

{
   "FleetId": "string",
   "InstanceId": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

FleetId

Unique identifier for a fleet that contains the instance you want access to. The fleet can be in any of the following statuses: ACTIVATING, ACTIVE, or ERROR. Fleets with an ERROR status may be accessible for a short time before they are deleted.

Type: String

Pattern: ^fleet-\S+

Required: Yes

InstanceId

Unique identifier for an instance you want to get access to. You can access an instance in any status.

Type: String

Pattern: [a-zA-Z0-9\.-]+

Required: Yes

Response Syntax

{
   "InstanceAccess": { 
      "Credentials": { 
         "Secret": "string",
         "UserName": "string"
      },
      "FleetId": "string",
      "InstanceId": "string",
      "IpAddress": "string",
      "OperatingSystem": "string"
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

InstanceAccess

Object that contains connection information for a fleet instance, including IP address and access credentials.

Type: InstanceAccess object

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalServiceException

The service encountered an unrecoverable internal failure while processing the request. Clients can retry such requests immediately or after a waiting period.

HTTP Status Code: 500

InvalidRequestException

One or more parameter values in the request are invalid. Correct the invalid parameter values before retrying.

HTTP Status Code: 400

NotFoundException

A service resource associated with the request could not be found. Clients should not retry such requests.

HTTP Status Code: 400

UnauthorizedException

The client failed authentication. Clients should not retry such requests.

HTTP Status Code: 400

Examples

Get credentials for a Linux instance

This example requests a set of credentials to remotely connect to a fleet instance running Linux.

If you're calling GetInstanceAccess programmatically, as with the JSON syntax, you need to save the returned value of Secret (an RsA private key) as a .pem file in the proper format. The returned value uses a newline (\n) to indicate a line break.

If you're calling GetInstanceAccess with the AWS CLI, you can automatically store the RSA private key as a .pem file in the proper format. See the CLI syntax example, which saves the private key to a file called MyPrivateKey.pem. Once the private key is saved, update the file permissions with the following command:

$ chmod 400 MyPrivateKey.pem

HTTP requests are authenticated using an AWS Signature Version 4 signature in the Authorization header field.

Sample Request

POST / HTTP/1.1
Host: gamelift.us-west-2.amazonaws.com;
Accept-Encoding: identity
Content-Length: 105
User-Agent: aws-cli/1.11.36 Python/2.7.9 Windows/7 botocore/1.4.93
Content-Type: application/x-amz-json-1.0
Authorization: AWS4-HMAC-SHA256  Credential=AKIAIOSFODNN7EXAMPLE/20170406/us-west-2/gamelift/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
X-Amz-Date: 20170406T004805Z
X-Amz-Target: GameLift.GetInstanceAccess 
	
    {"FleetId": "fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa",
    "InstanceId": "i-11111111a222b333c"
    }

CLI syntax:
    aws gamelift get-instance-access --fleet-id "fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa" --instance-id "i-11111111a222b333c" --query 'InstanceAccess.Credentials.Secret' --output text > MyPrivateKey.pem

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: b34f8665-EXAMPLE
Content-Type: application/x-amz-json-1.1
Content-Length: 1986
Date: Thu, 06 Apr 2017 00:48:07 GMT

{"InstanceAccess": {
    "Credentials": {
        "Secret": "-----BEGIN RSA PRIVATE KEY-----nEXAMPLEKEYKCAQEAy7WZhaDsrA1W3mRlQtvhwyORRX8gnxgDAfRt/gx42kWXsT4rXE/b5CpSgie/\nvBoU7jLxx92pNHoFnByP+Dc21eyyz6CvjTmWA0JwfWiW5/akH7iO5dSrvC7dQkW2duV5QuUdE0QW\nZ/aNxMniGQE6XAgfwlnXVBwrerrQo+ZWQeqiUwwMkuEbLeJFLhMCvYURpUMSC1oehm449ilx9X1F\nG50TCFeOzfl8dqqCP6GzbPaIjiU19xX/azOR9V+tpUOzEL+wmXnZt3/nHPQ5xvD2OJH67km6SuPW\noPzev/D8V+x4+bHthfSjR9Y7DvQFjfBVwHXigBdtZcU2/wei8D/HYwIDAQABAoIBAGZ1kaEvnrqu\n/uler7vgIn5m7lN5LKw4hJLAIW6tUT/fzvtcHK0SkbQCQXuriHmQ2MQyJX/0kn2NfjLV/ufGxbL1\nmb5qwMGUnEpJaZD6QSSs3kICLwWUYUiGfc0uiSbmJoap/GTLU0W5Mfcv36PaBUNy5p53V6G7hXb2\nbahyWyJNfjLe4M86yd2YK3V2CmK+X/BOsShnJ36+hjrXPPWmV3N9zEmCdJjA+K15DYmhm/tJWSD9\n81oGk9TopEp7CkIfatEATyyZiVqoRq6k64iuM9JkA3OzdXzMQexXVJ1TLZVEH0E7bhlY9d8O1ozR\noQs/FiZNAx2iijCWyv0lpjE73+kCgYEA9mZtyhkHkFDpwrSM1APaL8oNAbbjwEy7Z5Mqfql+lIp1\nYkriL0DbLXlvRAH+yHPRit2hHOjtUNZh4Axv+cpg09qbUI3+43eEy24B7G/Uh+GTfbjsXsOxQx/x\np9otyVwc7hsQ5TA5PZb+mvkJ5OBEKzet9XcKwONBYELGhnEPe7cCgYEA06Vgov6YHleHui9kHuws\nayav0elc5zkxjF9nfHFJRry21R1trw2Vdpn+9g481URrpzWVOEihvm+xTtmaZlSp//lkq75XDwnU\nWA8gkn6O3QE3fq2yN98BURsAKdJfJ5RL1HvGQvTe10HLYYXpJnEkHv+Unl2ajLivWUt5pbBrKbUC\ngYBjbO+OZk0sCcpZ29sbzjYjpIddErySIyRX5gV2uNQwAjLdp9PfN295yQ+BxMBXiIycWVQiw0bH\noMo7yykABY7Ozd5wQewBQ4AdSlWSX4nGDtsiFxWiI5sKuAAeOCbTosy1s8w8fxoJ5Tz1sdoxNeGs\nArq6Wv/G16zQuAE9zK9vvwKBgF+09VI/1wJBirsDGz9whVWfFPrTkJNvJZzYt69qezxlsjgFKshy\nWBhd4xHZtmCqpBPlAymEjr/TOlbxyARmXMnIOWIAnNXMGB4KGSyl1mzSVAoQ+fqR+cJ3d0dyPl1j\njjb0Ed/NY8frlNDxAVHE8BSkdsx2f6ELEyBKJSRr9snRAoGAMrTwYneXzvTskF/S5Fyu0iOegLDa\nNWUH38v/nDCgEpIXD5Hn3qAEcju1IjmbwlvtW+nY2jVhv7UGd8MjwUTNGItdb6nsYqM2asrnF3qS\nVRkAKKKYeGjkpUfVTrW0YFjXkfcrR/V+QFL5OndHAKJXjW7a4ejJLncTzmZSpYzwApc=\n-----END RSA PRIVATE KEY-----", 
        "UserName": "gl-user-remote"
    },
    "FleetId": "fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa", 
    "InstanceId": "i-11111111a222b333c",
    "IpAddress": "192.0.2.0", 
    "OperatingSystem": "AMAZON_LINUX"
}

Get credentials for a Windows instance

This example requests a set of credentials to remotely connect to a fleet instance running Windows.

HTTP requests are authenticated using an AWS Signature Version 4 signature in the Authorization header field.

Sample Request

POST / HTTP/1.1
Host: gamelift.us-west-2.amazonaws.com;
Accept-Encoding: identity
Content-Length: 105
User-Agent: aws-cli/1.11.36 Python/2.7.9 Windows/7 botocore/1.4.93
Content-Type: application/x-amz-json-1.0
Authorization: AWS4-HMAC-SHA256  Credential=AKIAIOSFODNN7EXAMPLE/20170406/us-west-2/gamelift/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
X-Amz-Date: 20170406T004805Z
X-Amz-Target: GameLift.GetInstanceAccess 
	
    {"FleetId": "fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa",
    "InstanceId": "i-11111111a222b333c"
    }

CLI syntax:
    aws gamelift get-instance-access --fleet-id "fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa" --instance-id "i-11111111a222b333c"

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: b34f8665-EXAMPLE
Content-Type: application/x-amz-json-1.1
Content-Length: 1986
Date: Thu, 06 Apr 2017 00:48:07 GMT

{"InstanceAccess": {
    "Credentials": {
        "Secret": "aA1bBB2cCCd3EEE", 
        "UserName": "gl-user-remote"
    },
    "FleetId": "fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa", 
    "InstanceId": "i-11111111a222b333c",
    "IpAddress": "192.0.2.0", 
    "OperatingSystem": "WIN_2012"
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: