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 |
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 |
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 |
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.