You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 2.4.

Deployments v2

Overview

Version 2 of the API for deployments management. Intended for use by the web GUI.

Version information

Version : 2

URI scheme

Host : docker.mender.io
BasePath : /api/management/v2/deployments
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Paths


Create a deployment

POST /deployments

Description

Deploy software to devices matching the given filter. The artifact is auto assigned to the device from all available artifacts based on artifact name and device type. Devices for which there are no compatible artifacts to be installed are considered finished successfully as well as receive the status of noartifact. If there are no artifacts for the deployment, the deployment will not be created and the 422 Unprocessable Entity status code will be returned. Dynamic deployments feature is available only to Enterprise users.

Parameters

Type Name Description Schema
Body deployment
required
New deployment that needs to be created. NewDeployment

Responses

HTTP Code Description Schema
201 New deployment created.
Headers :
Location (string) : URL of the newly created deployment.
No Content
400 Bad request, see error message for details. Error
403 Feature not available in your Plan. Error
422 Unprocessable Entity. Error
500 Internal Server Error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP request

Request body
{
  "name" : "production",
  "artifact_name" : "Application 0.0.1",
  "filter_id" : "00a0c91e6-7dec-11d0-a765-f81d4faebf6",
  "phases" : [ {
    "batch_size" : 5,
    "start_ts" : "2020-07-06T15:04:49.114+0000"
  }, {
    "batch_size" : 15,
    "start_ts" : "2020-07-06T16:04:49.114+0000"
  }, {
    "start_ts" : "2020-07-06T17:04:49.114+0000"
  } ],
  "retries" : 3
}

Example HTTP response

Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 403
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 422
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Definitions

Error

Error descriptor.

Name Description Schema
error
optional
Description of the error. string
request_id
optional
Request ID (same as in X-MEN-RequestID header). string

NewDeployment

Name Description Schema
artifact_name
required
string
filter_id
required
ID of a filter from inventory service. string
max_devices
optional
max_devices denotes a limit on a number of completed deployments (failed or successful) above which the dynamic deployment will be finished integer
name
required
string
phases
optional
< NewDeploymentPhase > array
retries
optional
The number of times a device can retry the deployment in case of failure, defaults to 0 integer

NewDeploymentPhase

Name Description Schema
batch_size
optional
Percentage of devices to update in the phase.
This field is optional for the last phase.
The last phase will contain the rest of the devices.
Note that if the percentage of devices entered does not add up to a whole number of devices it is rounded down, and in the case it is rounded down to zero, a 400 error will be returned.
This is mostly a concern when the deployment consists of a low number of devices, like say 5 percent of 11 devices will round to zero, and an error is returned by the server.
In the case of dynamic deployment, the number of devices for each phase is being calculated based on the initial number of devices matching the filter.
integer
start_ts
optional
Start date of a phase.
Can be skipped for the first phase of a new deployment definition ('start immediately').
string (date-time)

Security

ManagementJWT

API token issued by User Authentication service. Format: 'Bearer [JWT]'

Type : apiKey
Name : Authorization
In : HEADER