Skip to content

ApplicationInstance

An ApplicationInstance is the element that represents a deployed ApplicationBuild (e.g. a deployed game server or utility). It describes an actual instance of your software deployed onto a host.

With automatic deployments enabled, an ApplicationInstance is created, destroyed and controlled by the platform. You can also do this manually though and additionally get information about all your ApplicationInstance elements using the API endpoints for an ApplicationInstance.

Element structure

Property Value type Required Description
id string Read-only Unique identifier of this element
deploymentEnvironmentId string Read-only Unique identifier of the DeploymentEnvironment it's deployed in
deploymentEnvironmentName string Read-only The name of the DeploymentEnvironment it's deployed in
fleetId string Read-only Unique identifier of the Fleet it's deployed in
fleetName string Read-only The name of the Fleet it's deployed in
hostId int Read-only Unique identifier of the Host it's deployed on
isVirtual int Read-only 1 if it's deployed onto a VM, 0 if deployed onto bare metal
applicationId string Read-only Unique identifier of the Application this instance is based on
applicationName string Read-only The name of the Application this instance is based on
applicationType int Read-only The type of application as inherited from its parent Application:
1: Game server
2: Utility
3 DependencyInstaller
4 DependencyUninstaller
applicationBuildId string Read-only Unique identifier of the ApplicationBuild this instance is based on
dcLocationId int Read-only Host data center location ID
dcLocationName string Read-only Host data center location name
regionId int Read-only Unique identifier of the deployment region it's deployed in
regionName string Read-only The name of the deployment region it's deployed in
status int Read-only Game and Utility instances:
0: inactive
1: setup
2: offline
3: starting
4: online
5: allocated

Dependency (Un-)Installer instances:
0: inactive
101: setup
102: offline
103: starting
104: running
105: completed
106: error
manuallyDeployed int Read-only 0: automatically deployed
1: manually deployed
createdAt int Read-only Unix timestamp of when this element was created
updatedAt int Read-only Unix timestamp of the last change to this element
startedAt int Read-only Unix timestamp of when this element was last started
stoppedAt int Read-only Unix timestamp of when this element was last stopped
pid int Read-only PID of the instance
pidChangedAt int Read-only Unix timestamp of the last PID change
startupParams string Read-only The exact startup parameters that were used to start this application instance with all properties resolved to their respective values. Will be null if the instance has not been started, but will retain its previous value if it was stopped. Once set it will never be cleared again
executable string Read-only The name of the executable that was ran when the application instance started. Will be null if the instance has not been started, but will retain its previous value if it was stopped. Once set it will never be cleared again
ipAddress [ApplicationInstanceIP] Read-only All IP addresses active for this instance
numPlayersMax int Read-only Maximum number of players allowed on a game server [only applies to instances of type Game Server]
numPlayers int Read-only Current number of players on the game server [only applies to instances of type Game Server]
liveHostName string Read-only Current game server name [only applies to instances of type Game Server]
liveMap string Read-only Current map running on the game server [only applies to instances of type Game Server]
liveGameVersion string Read-only Current version of the game server software [only applies to instances of type Game Server]
liveRules string Read-only Current "rules" of the game server [only applies to instances of type Game Server]
autoRestart int Read-only If auto restart is 1, the application instance will automatically restart after (self-)shutdown
properties [ApplicationInstanceProperty] Read-only Properties inherited from the related ApplicationBuild
labelReadOnly [Label] Read-only Collection of read-only labels generated by the system
labelPublic [Label] No Collection of client-defined labels
metadata [Metadata] No Metadata
markedForDeletion int Read-only 1 if the application instance is about to be destroyed
Table 1: ApplicationInstance element structure

Application instance status

During the lifetime of an ApplicationInstance it goes through several operational statuses. This is stored in the status property of the element. The different status levels and what they represent are explained in the following tables:

Game and Utility instances

Status code Status name Description
0 inactive The instance is no longer in use
1 setup The instance is being setup / deployed for the first time
2 offline The instance is deployed but not running
3 starting The instance is currently starting up (optional)
4 online The instance has started up and is fully working (and initialized)
5 allocated The instance has been allocated by a matchmaker
Table 2: Game and Utility ApplicationInstance operational statuses

Dependency (Un-)Installer instances

Status code Status name Description
0 inactive The instance is no longer in use
101 setup The instance is being setup / deployed for the first time
102 offline The instance is deployed but not running
103 starting The instance is currently starting up (optional)
104 running The instance has started up and is currently running
105 completed The instance has stopped without error
106 error The instance has stopped with error. To get the console output of the instance, see /v3/applicationInstance/{applicationInstanceId}/log
Table 2: Dependency (Un-)Installer ApplicationInstance operational statuses

Startup initialization period

By default the status of a game instance will be set to ONLINE (4) after it's been started. This status means your game instance is ready to accept players. If however your game server requires an initialization period before it can accept players and you want our system to know about this, then you can do the following:

In your ApplicationBuild, enable the instanceDoesReadyCallback option. With this checked, our platform will set the status of your game instances to STARTING (3). Next, you must have your game instance tell our backend when it is ready to accept players by having it perform a callback to our API. The status will then be set to ONLINE (4) and our platform then knows the game instance can be allocated (if applicable).

Property inheritance

Any properties defined for an ApplicationBuild will be inherited by an ApplicationInstance.

Labels

A user can define custom labels (key / value pairs) for an ApplicationInstance, to allow for easy identification and filtering of ApplicationInstance elements.

Alongside client-defined labels there will also be additional read-only labels generated by the platform:

  • application_id
  • fleet_id
  • host_id
  • dc_location_id
  • region_id
  • application_build_id

Read more about Labels.

Relations

An ApplicationInstance is deployed according to an ApplicationBuild.