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
deletedAt	int	Read-only	Unix timestamp of the Application instance deletion
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
6	allocating	The instance is in the process of being 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.