Docker Swarm API
Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
OpenAPI Specification
swagger: '2.0'
info:
title: Docker Engine Config Swarm API
version: '1.54'
x-logo:
url: https://docs.docker.com/assets/images/logo-docker-main.png
description: "The Engine API is an HTTP API served by Docker Engine. It is the API the\nDocker client uses to communicate with the Engine, so everything the Docker\nclient can do can be done with the API.\n\nMost of the client's commands map directly to API endpoints (e.g. `docker ps`\nis `GET /containers/json`). The notable exception is running containers,\nwhich consists of several API calls.\n\n# Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof the API call. The body of the response will be JSON in the following\nformat:\n\n```\n{\n \"message\": \"page not found\"\n}\n```\n\n# Versioning\n\nThe API is usually changed in each release, so API calls are versioned to\nensure that clients don't break. To lock to a specific version of the API,\nyou prefix the URL with its version, for example, call `/v1.30/info` to use\nthe v1.30 version of the `/info` endpoint. If the API version specified in\nthe URL is not supported by the daemon, a HTTP `400 Bad Request` error message\nis returned.\n\nIf you omit the version-prefix, the current version of the API (v1.50) is used.\nFor example, calling `/info` is the same as calling `/v1.52/info`. Using the\nAPI without a version-prefix is deprecated and will be removed in a future release.\n\nEngine releases in the near future should support this version of the API,\nso your client will continue to work even if it is talking to a newer Engine.\n\nThe API uses an open schema model, which means the server may add extra properties\nto responses. Likewise, the server will ignore any extra query parameters and\nrequest body properties. When you write clients, you need to ignore additional\nproperties in responses to ensure they do not break when talking to newer\ndaemons.\n\n\n# Authentication\n\nAuthentication for registries is handled client side. The client has to send\nauthentication details to various endpoints that need to communicate with\nregistries, such as `POST /images/(name)/push`. These are sent as\n`X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5)\n(JSON) string with the following structure:\n\n```\n{\n \"username\": \"string\",\n \"password\": \"string\",\n \"serveraddress\": \"string\"\n}\n```\n\nThe `serveraddress` is a domain/IP without a protocol. Throughout this\nstructure, double quotes are required.\n\nIf you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth),\nyou can just pass this instead of credentials:\n\n```\n{\n \"identitytoken\": \"9cbaf023786cd7...\"\n}\n```\n"
basePath: /v1.54
schemes:
- http
- https
consumes:
- application/json
- text/plain
produces:
- application/json
- text/plain
tags:
- name: Swarm
x-displayName: Swarm
description: 'Engines can be clustered together in a swarm. Refer to the
[swarm mode documentation](https://docs.docker.com/engine/swarm/)
for more information.
'
paths:
/swarm:
get:
summary: Inspect swarm
operationId: SwarmInspect
responses:
200:
description: no error
schema:
$ref: '#/definitions/Swarm'
404:
description: no such swarm
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- Swarm
/swarm/init:
post:
summary: Initialize a new swarm
operationId: SwarmInit
produces:
- application/json
- text/plain
responses:
200:
description: no error
schema:
description: The node ID
type: string
example: 7v2t30z9blmxuhnyo6s4cpenp
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is already part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: body
in: body
required: true
schema:
type: object
title: SwarmInitRequest
properties:
ListenAddr:
description: 'Listen address used for inter-manager communication, as well
as determining the networking interface used for the VXLAN
Tunnel Endpoint (VTEP). This can either be an address/port
combination in the form `192.168.1.1:4567`, or an interface
followed by a port number, like `eth0:4567`. If the port number
is omitted, the default swarm listening port is used.
'
type: string
AdvertiseAddr:
description: 'Externally reachable address advertised to other nodes. This
can either be an address/port combination in the form
`192.168.1.1:4567`, or an interface followed by a port number,
like `eth0:4567`. If the port number is omitted, the port
number from the listen address is used. If `AdvertiseAddr` is
not specified, it will be automatically detected when possible.
'
type: string
DataPathAddr:
description: 'Address or interface to use for data path traffic (format:
`<ip|interface>`), for example, `192.168.1.1`, or an interface,
like `eth0`. If `DataPathAddr` is unspecified, the same address
as `AdvertiseAddr` is used.
The `DataPathAddr` specifies the address that global scope
network drivers will publish towards other nodes in order to
reach the containers running on this node. Using this parameter
it is possible to separate the container data traffic from the
management traffic of the cluster.
'
type: string
DataPathPort:
description: 'DataPathPort specifies the data path port number for data traffic.
Acceptable port range is 1024 to 49151.
if no port is set or is set to 0, default port 4789 will be used.
'
type: integer
format: uint32
DefaultAddrPool:
description: 'Default Address Pool specifies default subnet pools for global
scope networks.
'
type: array
items:
type: string
example:
- 10.10.0.0/16
- 20.20.0.0/16
ForceNewCluster:
description: Force creation of a new swarm.
type: boolean
SubnetSize:
description: 'SubnetSize specifies the subnet size of the networks created
from the default subnet pool.
'
type: integer
format: uint32
Spec:
$ref: '#/definitions/SwarmSpec'
example:
ListenAddr: 0.0.0.0:2377
AdvertiseAddr: 192.168.1.1:2377
DataPathPort: 4789
DefaultAddrPool:
- 10.10.0.0/8
- 20.20.0.0/8
SubnetSize: 24
ForceNewCluster: false
Spec:
Orchestration: {}
Raft: {}
Dispatcher: {}
CAConfig: {}
EncryptionConfig:
AutoLockManagers: false
tags:
- Swarm
/swarm/join:
post:
summary: Join an existing swarm
operationId: SwarmJoin
responses:
200:
description: no error
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is already part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: body
in: body
required: true
schema:
type: object
title: SwarmJoinRequest
properties:
ListenAddr:
description: 'Listen address used for inter-manager communication if the node
gets promoted to manager, as well as determining the networking
interface used for the VXLAN Tunnel Endpoint (VTEP).
'
type: string
AdvertiseAddr:
description: 'Externally reachable address advertised to other nodes. This
can either be an address/port combination in the form
`192.168.1.1:4567`, or an interface followed by a port number,
like `eth0:4567`. If the port number is omitted, the port
number from the listen address is used. If `AdvertiseAddr` is
not specified, it will be automatically detected when possible.
'
type: string
DataPathAddr:
description: 'Address or interface to use for data path traffic (format:
`<ip|interface>`), for example, `192.168.1.1`, or an interface,
like `eth0`. If `DataPathAddr` is unspecified, the same address
as `AdvertiseAddr` is used.
The `DataPathAddr` specifies the address that global scope
network drivers will publish towards other nodes in order to
reach the containers running on this node. Using this parameter
it is possible to separate the container data traffic from the
management traffic of the cluster.
'
type: string
RemoteAddrs:
description: 'Addresses of manager nodes already participating in the swarm.
'
type: array
items:
type: string
JoinToken:
description: Secret token for joining this swarm.
type: string
example:
ListenAddr: 0.0.0.0:2377
AdvertiseAddr: 192.168.1.1:2377
DataPathAddr: 192.168.1.1
RemoteAddrs:
- node1:2377
JoinToken: SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2
tags:
- Swarm
/swarm/leave:
post:
summary: Leave a swarm
operationId: SwarmLeave
responses:
200:
description: no error
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: force
description: 'Force leave swarm, even if this is the last manager or that it will
break the cluster.
'
in: query
type: boolean
default: false
tags:
- Swarm
/swarm/update:
post:
summary: Update a swarm
operationId: SwarmUpdate
responses:
200:
description: no error
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/SwarmSpec'
- name: version
in: query
description: 'The version number of the swarm object being updated. This is
required to avoid conflicting writes.
'
type: integer
format: int64
required: true
- name: rotateWorkerToken
in: query
description: Rotate the worker join token.
type: boolean
default: false
- name: rotateManagerToken
in: query
description: Rotate the manager join token.
type: boolean
default: false
- name: rotateManagerUnlockKey
in: query
description: Rotate the manager unlock key.
type: boolean
default: false
tags:
- Swarm
/swarm/unlockkey:
get:
summary: Get the unlock key
operationId: SwarmUnlockkey
consumes:
- application/json
responses:
200:
description: no error
schema:
type: object
title: UnlockKeyResponse
properties:
UnlockKey:
description: The swarm's unlock key.
type: string
example:
UnlockKey: SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- Swarm
/swarm/unlock:
post:
summary: Unlock a locked manager
operationId: SwarmUnlock
consumes:
- application/json
produces:
- application/json
parameters:
- name: body
in: body
required: true
schema:
type: object
title: SwarmUnlockRequest
properties:
UnlockKey:
description: The swarm's unlock key.
type: string
example:
UnlockKey: SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8
responses:
200:
description: no error
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- Swarm
definitions:
ObjectVersion:
description: 'The version number of the object such as node, service, etc. This is needed
to avoid conflicting writes. The client must send the version number along
with the modified specification when updating these objects.
This approach ensures safe concurrency and determinism in that the change
on the object may not be applied if the version number has changed from the
last read. In other words, if two update requests specify the same base
version, only one of the requests can succeed. As a result, two separate
update requests that happen at the same time will not unintentionally
overwrite each other.
'
type: object
properties:
Index:
type: integer
format: uint64
example: 373531
JoinTokens:
description: 'JoinTokens contains the tokens workers and managers need to join the swarm.
'
type: object
properties:
Worker:
description: 'The token workers can use to join the swarm.
'
type: string
example: SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx
Manager:
description: 'The token managers can use to join the swarm.
'
type: string
example: SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2
Swarm:
type: object
allOf:
- $ref: '#/definitions/ClusterInfo'
- type: object
properties:
JoinTokens:
$ref: '#/definitions/JoinTokens'
TLSInfo:
description: 'Information about the issuer of leaf TLS certificates and the trusted root
CA certificate.
'
type: object
properties:
TrustRoot:
description: 'The root CA certificate(s) that are used to validate leaf TLS
certificates.
'
type: string
CertIssuerSubject:
description: The base64-url-safe-encoded raw subject bytes of the issuer.
type: string
CertIssuerPublicKey:
description: 'The base64-url-safe-encoded raw public key bytes of the issuer.
'
type: string
example:
TrustRoot: '-----BEGIN CERTIFICATE-----
MIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw
EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0
MzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf
3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
Af8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO
PQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz
pxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H
-----END CERTIFICATE-----
'
CertIssuerSubject: MBMxETAPBgNVBAMTCHN3YXJtLWNh
CertIssuerPublicKey: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A==
ErrorResponse:
description: Represents an error.
type: object
required:
- message
properties:
message:
description: The error message.
type: string
x-nullable: false
example:
message: Something went wrong.
ClusterInfo:
description: 'ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
'
x-nullable: true
type: object
properties:
ID:
description: The ID of the swarm.
type: string
example: abajmipo7b4xz5ip2nrla6b11
Version:
$ref: '#/definitions/ObjectVersion'
CreatedAt:
description: 'Date and time at which the swarm was initialised in
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds.
'
type: string
format: dateTime
example: '2016-08-18T10:44:24.496525531Z'
UpdatedAt:
description: 'Date and time at which the swarm was last updated in
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds.
'
type: string
format: dateTime
example: '2017-08-09T07:09:37.632105588Z'
Spec:
$ref: '#/definitions/SwarmSpec'
TLSInfo:
$ref: '#/definitions/TLSInfo'
RootRotationInProgress:
description: 'Whether there is currently a root CA rotation in progress for the swarm
'
type: boolean
example: false
DataPathPort:
description: 'DataPathPort specifies the data path port number for data traffic.
Acceptable port range is 1024 to 49151.
If no port is set or is set to 0, the default port (4789) is used.
'
type: integer
format: uint32
default: 4789
example: 4789
DefaultAddrPool:
description: 'Default Address Pool specifies default subnet pools for global scope
networks.
'
type: array
items:
type: string
format: CIDR
example:
- 10.10.0.0/16
- 20.20.0.0/16
SubnetSize:
description: 'SubnetSize specifies the subnet size of the networks created from the
default subnet pool.
'
type: integer
format: uint32
maximum: 29
default: 24
example: 24
SwarmSpec:
description: User modifiable swarm configuration.
type: object
properties:
Name:
description: Name of the swarm.
type: string
example: default
Labels:
description: User-defined key/value metadata.
type: object
additionalProperties:
type: string
example:
com.example.corp.type: production
com.example.corp.department: engineering
Orchestration:
description: Orchestration configuration.
type: object
x-nullable: true
properties:
TaskHistoryRetentionLimit:
description: 'The number of historic tasks to keep per instance or node. If
negative, never remove completed or failed tasks.
'
type: integer
format: int64
example: 10
Raft:
description: Raft configuration.
type: object
properties:
SnapshotInterval:
description: The number of log entries between snapshots.
type: integer
format: uint64
example: 10000
KeepOldSnapshots:
description: 'The number of snapshots to keep beyond the current snapshot.
'
type: integer
format: uint64
LogEntriesForSlowFollowers:
description: 'The number of log entries to keep around to sync up slow followers
after a snapshot is created.
'
type: integer
format: uint64
example: 500
ElectionTick:
description: 'The number of ticks that a follower will wait for a message from
the leader before becoming a candidate and starting an election.
`ElectionTick` must be greater than `HeartbeatTick`.
A tick currently defaults to one second, so these translate
directly to seconds currently, but this is NOT guaranteed.
'
type: integer
example: 3
HeartbeatTick:
description: 'The number of ticks between heartbeats. Every HeartbeatTick ticks,
the leader will send a heartbeat to the followers.
A tick currently defaults to one second, so these translate
directly to seconds currently, but this is NOT guaranteed.
'
type: integer
example: 1
Dispatcher:
description: Dispatcher configuration.
type: object
x-nullable: true
properties:
HeartbeatPeriod:
description: 'The delay for an agent to send a heartbeat to the dispatcher.
'
type: integer
format: int64
example: 5000000000
CAConfig:
description: CA configuration.
type: object
x-nullable: true
properties:
NodeCertExpiry:
description: The duration node certificates are issued for.
type: integer
format: int64
example: 7776000000000000
ExternalCAs:
description: 'Configuration for forwarding signing requests to an external
certificate authority.
'
type: array
items:
type: object
properties:
Protocol:
description: 'Protocol for communication with the external CA (currently
only `cfssl` is supported).
'
type: string
enum:
- cfssl
default: cfssl
URL:
description: 'URL where certificate signing requests should be sent.
'
type: string
Options:
description: 'An object with key/value pairs that are interpreted as
protocol-specific options for the external CA driver.
'
type: object
additionalProperties:
type: string
CACert:
description: 'The root CA certificate (in PEM format) this external CA uses
to issue TLS certificates (assumed to be to the current swarm
root CA certificate if not provided).
'
type: string
SigningCACert:
description: 'The desired signing CA certificate for all swarm node TLS leaf
certificates, in PEM format.
'
type: string
SigningCAKey:
description: 'The desired signing CA key for all swarm node TLS leaf certificates,
in PEM format.
'
type: string
ForceRotate:
description: 'An integer whose purpose is to force swarm to generate a new
signing CA certificate and key, if none have been specified in
`SigningCACert` and `SigningCAKey`
'
format: uint64
type: integer
EncryptionConfig:
description: Parameters related to encryption-at-rest.
type: object
properties:
AutoLockManagers:
description: 'If set, generate a key and use it to lock data stored on the
managers.
'
type: boolean
example: false
TaskDefaults:
description: Defaults for creating tasks in this cluster.
type: object
properties:
LogDriver:
description: 'The log driver to use for tasks created in the orchestrator if
unspecified by a service.
Updating this value only affects new tasks. Existing tasks continue
to use their previously configured log driver until recreated.
'
type: object
properties:
Name:
description: 'The log driver to use as a default for new tasks.
'
type: string
example: json-file
Options:
description: 'Driver-specific options for the selected log driver, specified
as key/value pairs.
'
type: object
additionalProperties:
type: string
example:
max-file: '10'
max-size: 100m