GetInstanceAccess
Requests remote access to a fleet instance. Remote access is useful for debugging, gathering benchmarking data, or observing activity in real time.
To remotely access an instance, you need credentials that match the operating system
of the instance. For a Windows instance, GameLift returns a user name and password as
strings for use with a Windows Remote Desktop client. For a Linux instance, 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 Amazon CLI, saving the secret can be handled
as part of the GetInstanceAccess
request, as shown in one of the examples
for this operation.
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.
Learn more
Remotely Access Fleet Instances
Related actions
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.
In the following list, the required parameters are described first.
- FleetId
-
A unique identifier for the fleet that contains the instance you want access to. You can use either the fleet ID or ARN value. The fleet can be in any of the following statuses:
ACTIVATING
,ACTIVE
, orERROR
. Fleets with anERROR
status may be accessible for a short time before they are deleted.Type: String
Pattern:
^fleet-\S+|^arn:.*:fleet\/fleet-\S+
Required: Yes
- InstanceId
-
A unique identifier for the 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
-
The 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
-
THe requested resources was not found. The resource was either not created yet or deleted.
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 Amazon 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
Sample Request
{"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
{"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.
Sample Request
{"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
{"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 Amazon SDKs, see the following: