# Utilitydeploymenttemplate

The UtilityDeploymentTemplate indicates which utility / utilities you want to deploy onto each host (bare metal or VM). A utility, also known as a sidecar, is always deployed once per host. You can indicate whether a utility should be deployed only on bare metal servers or virtual machines, or both.

When a new host is selected for deployment of game servers, the utility will be the first thing to be deployed onto the host. Reversely, when a host has been freed from any game server applications, the utilities will be removed again, cleaning up the host.

!\[UtilityDeploymentTemplate]\(../images/DeploymentConfigurationOverviewUtilDepTempl.png)Figure 1: Highlighting where the UtilityDeploymentTemplate elements belong in the overview

## Usage

A UtilityDeploymentTemplate is used by a [Fleet](/game-hosting/elements/deploymentenvironment/fleet.md) and defines which ApplicationBuilds (of type Utility) will be deployed for that Fleet. A single UtilityDeploymentTemplate can define more than one ApplicationBuild by adding multiple [UtilityDeploymentTemplate](#utilitydeploymenttemplatebuild-element-structure) elements. Each of these defines a single ApplicationBuild (of type Utility).

Each ApplicationBuild in the UtilityDeploymentTemplate will be deployed once per host, unless indicated otherwise in a [UtilityDeploymentTemplateBuild](#utilitydeploymenttemplatebuild-element-structure). There you can indicate whether a utility should be deployed onto bare metal only, VM only or both (UtilityDeploymentTemplate.deployOn). Additionally a limit can be set to the amount of hosts the utilities are deployed on (UtilityDeploymentTemplate.installsPerLocation). This can be useful for certain types of utilities such as ping servers, for which you may only need a limited number.

You can create as many UtilityDeploymentTemplates as you like within the platform. However, a Fleet can only point to one UtilityDeploymentTemplate at a time. A UtilityDeploymentTemplate can be shared (re-used) across multiple fleets though.

{% hint style="info" %}
Utilities / sidecars must be regular applications that run in the foreground. It is generally not a good idea to start utilities as a service.
{% endhint %}

## Element structure

| Property                       | Value type                                                                             | Required  | Description                                                                                         |
| ------------------------------ | -------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------- |
| id                             | string                                                                                 | Read-only | Unique identifier of this element                                                                   |
| fleetIds                       | \[int]                                                                                 | Read-only | List of [Fleet](/game-hosting/elements/deploymentenvironment/fleet.md) IDs this template is used in |
| name                           | string                                                                                 | Yes       | Name of the template                                                                                |
| inUse                          | boolean                                                                                | Read-only | Indicates whether this template is actively being used in a Fleet                                   |
| createdAt                      | int                                                                                    | Read-only | A unix timestamp of when this element was created                                                   |
| utilityDeploymentTemplateBuild | \[[UtilityDeploymentTemplateBuild](#utilitydeploymenttemplatebuild-element-structure)] | Yes       | List of UtilityDeploymentTemplateBuild elements, pointing to ApplicationBuilds                      |

Table 1: UtilityDeploymentTemplate element structure

## UtilityDeploymentTemplateBuild element structure

| Property            | Value type | Required | Description                                                                                                                                    |
| ------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| applicationBuildId  | string     | Yes      | Identifier of the [ApplicationBuild](/game-hosting/elements/application/applicationbuild.md) you want to deploy                                |
| deployOn            | int        | No       | <p><strong>1</strong>: bare metal<br><strong>2</strong>: VM<br><strong>3</strong>: both (default)</p>                                          |
| installsPerLocation | int        | No       | The amount of hosts to deploy this utility on, on a per DC location basis. The value 0 means "install on all hosts". Defaults to 0 if omitted. |

Table 2: UtilityDeploymentTemplateBuild element structure

## API example

Create a new GameDeploymentTemplate within your i3D.net account.

[Full API reference](/api/api_one.md#v3-deploymenttemplate-game)

#### HTTP request

[`POST /v3/deploymentTemplate/utility`](/api/api_one.md#v3-deploymenttemplate-utility)

#### Request body

```
{
  "name": "MyUtilityDeploymentTemplate",
  "utilityDeploymentTemplateBuild": [
    {
      "applicationBuildId": "3801243597300703061",
      "deployOn": 3,
      "installsPerLocation": 0
    }
  ]
}
```

#### Response body

```
[
  {
    "id": "5077110393967868847",
    "fleetIds": [
      0
    ],
    "name": "MyUtilityDeploymentTemplate",
    "inUse": 0,
    "createdAt": 1573060365,
    "utilityDeploymentTemplateBuild": [
      {
        "applicationBuildId": "3801243597300703061",
        "deployOn": 3,
        "installsPerLocation": 0
      }
    ]
  }
]
```

## Attach UtilityDeploymentTemplate to a Fleet:

[Full API reference](/api/api_one.md#v3-fleet)

#### HTTP request

[`PUT /v3/fleet/{fleetId}`](/api/api_one.md#v3-fleet-fleetid)

#### Request body

```
{
  "utilityDeploymentTemplateId": "8243136848298003197",
}
```

#### Response body

```
[
  {
    "id": "string",
    "name": "string",
    "deploymentEnvironmentId": "string",
    "deploymentProfileId": "string",
    "gameDeploymentTemplateId": "string",
    "utilityDeploymentTemplateId": "8243136848298003197",
    "operationalStatus": 0
  }
]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.i3d.net/game-hosting/elements/deploymentenvironment/index/utilitydeploymenttemplate.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.