GetInstanceAccess
Requests authorization to remotely connect to an instance in an Amazon GameLift managed fleet. Use this operation to connect to instances with game servers that use Amazon GameLift server SDK 4.x or earlier. To connect to instances with game servers that use server SDK 5.x or later, call GetComputeAccess.
To request access to an instance, specify IDs for the instance and the fleet it belongs to. You can retrieve instance IDs for a fleet by calling DescribeInstances with the fleet ID.
If successful, this operation returns an IP address and credentials. The returned credentials match the operating system of the instance, as follows:
-
For a Windows instance: returns a user name and secret (password) for use with a Windows Remote Desktop client.
-
For a Linux instance: returns a user name and secret (RSA private key) for use with an SSH client. You must save the secret to a
.pem
file. If you're using the Amazon CLI, see the example Get credentials for a Linux instance for tips on automatically saving the secret to a.pem
file.
Learn more
Remotely connect to 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.
Note
In the following list, the required parameters are described first.
- FleetId
-
A unique identifier for the fleet that contains the instance you want to access. You can request access to instances in EC2 fleets with the following statuses:
ACTIVATING
,ACTIVE
, orERROR
. Use either a fleet ID or an ARN value.Note
You can access fleets in
ERROR
status for a short period of time before Amazon GameLift deletes them.Type: String
Pattern:
^fleet-\S+|^arn:.*:fleet\/fleet-\S+
Required: Yes
- InstanceId
-
A unique identifier for the instance you want to access. 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 deployed with a Linux Amazon machine image (AMI). The instance is running a game server build with server SDK version 4.02.
When calling GetInstanceAccess
programmatically, 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 save the RSA private key as a .pem
file. The CLI
syntax in this example saves the secret to a file called
MyPrivateKey.pem
. After saving the private key, you can 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_2"
}
Get credentials for a Windows instance
This example requests a set of credentials to remotely connect to a fleet instance deployed with a Windows Amazon machine image (AMI). The instance is running a game server build with server SDK version 4.02.
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: