Forced Deployment - Manually

The classical approach to updating game servers is to update them all at the same time, within a maintenance window.

Instance selection

When you create a task through the API you can select the instances to create the tasks for you in multiple ways.

Normally this is quite easy, assuming you want to update all instances in a Fleet, DeploymentRegion or DcLocation, or for example all instances currently running on a certain ApplicationBuild. In that case you can simply enter any of these IDs during task creation in the Task request body (see below) and deployment tasks for all instances in said element will be created.

In other cases you may want to update really specific instances. If you do, you can first do a listing of the application instances you are interested in, by using any GET endpoint listed in the ApplicationInstance section of the API documentation, using any selection method you wish. You can then compile your list of application instance IDs, to be used in the deployment task that we'll be creating next.

Below is a task request body illustrating the options for instance selection:

{
  "taskTemplateId": 0,
  "applicationInstanceIds": [
    "string"
  ],
  "fleetId": "",
  "regionId": "",
  "labels": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "executeAt": 0,
  "taskActionParam": [
    {
      "paramName": "string",
      "paramValue": "string"
    }
  ]
}

The properties relevant for instance selection are:

applicationInstanceIds - supply an array of literal applicationInstance Ids
fleetId - supply a fleet Id to select all the application instances in it
regionId - supply a region Id to select all the application instances in it
labels - supply additional application instance labels for more precise selections:
- application_id
- host_id
- dc_location_id
- application_build_id
- any custom label created by you

You are not limited to using one filter property at a time; you can combine properties to create the final selection of instances.

API example

Below we will illustrate creating forced update tasks via the API.

Step 1: find the appropriate Task Template ID

Creating tasks is done by means of providing a Task Template for the task you want performed. A Task Template is a description of a certain task whereby a task contains one or more actions. An action can be a deployment, preload, start / stop instance, etc.

HTTP request

GET /applicationInstance/task/template

Response body

[
    {
        ...
    },
    {
        "id": 2,
        "name": "Deploy a software build",
        "description": "Install a software build onto a server. This can be used to install an initial build of a new game instance, or to patch an existing instance. If the software build was previously downloaded (preloaded), it will not be downloaded again.",
        "actions": [
            {
                "idx": 0,
                "actionType": "Download software build",
                "requiredParams": {
                    "buildId": "The ID of the applicationBuild. Its build archive will be downloaded."
                }
            },
            {
                "idx": 1,
                "actionType": "Extract software build",
                "requiredParams": {
                    "buildId": "The ID of the applicationBuild. This action will extract the build archive that has been downloaded."
                }
            },
            {
                "idx": 2,
                "actionType": "Stop instance",
                "requiredParams": {
                    "methodId": "The ID of the stop-method, indicating how you want to stop the application instance.",
                    "timeout": "If the stop-method is graceful, you can indicate a maximum time to wait here, before the application instance is forcefully terminated."
                }
            },
            {
                "idx": 3,
                "actionType": "Deploy software build to instance",
                "requiredParams": {
                    "buildId": "The ID of the applicationBuild. This action expects the build archive to already have been downloaded and extracted onto the host."
                }
            },
            {
                "idx": 4,
                "actionType": "Start instance",
                "requiredParams": null
            }
        ]
    },
    {
        ...
    }
]

The template that we are interested in is displayed - the others have been snipped.

This template with ID 2 is the deployment template. You can see the 5 actions it contains: download, extract, stop instance, deploy instance and start instance. Each of these actions has a requiredParams parameter detailing what information the action needs in order to be performed successfully. If the requiredParams value is null, the action does not require any parameters. These parameters must be provided in the taskActionParam parameter of the HTTP request to create the task later on.

buildId refers to the applicationBuild ID you want to deploy. Note that you see this parameter in three actions. You only need to provide it once later on in the HTTP request body.
methodId refers to the stop method to perform. The default value of 1 stands for "kill the process immediately". Other methods depend on whether your game supports graceful stop methods, allowing a game to finish before we take down the instance. [make a note here of how to obtain the methodIds].
timeout refers to the maximum length of the grace period the stop action will adhere to. If an instance has not stopped after <timeout> seconds, it will be forcefully shut down.

These are all the parameters needed to use a deployment task template.

Step 2: create the deployment tasks

Now you can create the actual Tasks for the application instances you want to update. You do not have to create a Task for each ApplicationInstance individually; the following endpoint will create deployment Tasks for all the given application instances with one API call. They will all become part of a TaskBatch, an object that encapsulates and tracks the progress of all individual Tasks.

HTTP request

POST /applicationInstance/task

Request body

{
  "taskTemplateId": 2,
  "applicationInstanceIds": [
    "7307311272729997509", "1803671638346755523"
  ],
  "fleetId": "1382702706111300109",
  "executeAt": 0,
  "taskActionParam": [
    {
      "paramName": "buildId",
      "paramValue": "3772131712593619554"
    },
    {
      "paramName": "methodId",
      "paramValue": "1"
    },
    {
      "paramName": "timeout",
      "paramValue": "0"
    }
  ]
}

Here we request a deployment task to be created for:

two individual application instances
plus, all active application instances in the fleet with ID 1382702706111300109

Because executeAt is 0, the tasks will be performed immediately. If you want to schedule tasks for future execution, enter a unix timestamp here.

The taskActionParam field states:

deploy the ApplicationBuild with ID 3772131712593619554
stop all instances immediately (methodId = 1)
the timeout is 0, because the stop method is "immediately" and as such a timeout does not apply

Response body

[
  {
    "id": 3874,
    "createdAt": 1567172470,
    "executeAt": 1567172470,
    "finishedAt": 0,
    "numTasks": 78,
    "numTasksOk": 0,
    "numTasksFailed": 0,
    "numTasksCancelled": 0,
    "taskIds": [
      285613,
      285614,
      285615,
      ... snipped ...
    ]
  }
]

The response contains a TaskBatch object, showing you a global status of all individual Tasks.

Property	Value type	Description
id	int	A unique TaskBatch identifier
createdAt	int	Unix timestamp of creation time
executeAt	int	Unix timestamp of execution time
finishedAt	int	Unix timestamp of when the last Tasks was finished executing
numTasks	int	Total number of Tasks in this TaskBatch
numTasksOk	int	Number of successfully executed Tasks
numTasksFailed	int	Number of failed Tasks
numTasksCancelled	int	Number of cancelled Tasks
taskIds	[int]	Array of key-value pairs indicating Task ID vs Task Result Code

Table 1: TaskBatch element structure