Docker Service API
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
OpenAPI Specification
swagger: '2.0'
info:
title: Docker Engine Config Service 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: Service
x-displayName: Services
description: 'Services are the definitions of tasks to run on a swarm. Swarm mode must
be enabled for these endpoints to work.
'
paths:
/services:
get:
summary: List services
operationId: ServiceList
responses:
200:
description: no error
schema:
type: array
items:
$ref: '#/definitions/Service'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: filters
in: query
type: string
description: 'A JSON encoded value of the filters (a `map[string][]string`) to
process on the services list.
Available filters:
- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"|"global"]`
- `name=<service name>`
'
- name: status
in: query
type: boolean
description: 'Include service status, with count of running and desired tasks.
'
tags:
- Service
/services/create:
post:
summary: Create a service
operationId: ServiceCreate
consumes:
- application/json
produces:
- application/json
responses:
201:
description: no error
schema:
$ref: '#/definitions/ServiceCreateResponse'
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
403:
description: network is not eligible for services
schema:
$ref: '#/definitions/ErrorResponse'
409:
description: name conflicts with an existing service
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:
allOf:
- $ref: '#/definitions/ServiceSpec'
- type: object
example:
Name: web
TaskTemplate:
ContainerSpec:
Image: nginx:alpine
Mounts:
- ReadOnly: true
Source: web-data
Target: /usr/share/nginx/html
Type: volume
VolumeOptions:
DriverConfig: {}
Labels:
com.example.something: something-value
Hosts:
- 10.10.10.10 host1
- ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2
User: '33'
DNSConfig:
Nameservers:
- 8.8.8.8
Search:
- example.org
Options:
- timeout:3
Secrets:
- File:
Name: www.example.org.key
UID: '33'
GID: '33'
Mode: 384
SecretID: fpjqlhnwb19zds35k8wn80lq9
SecretName: example_org_domain_key
OomScoreAdj: 0
LogDriver:
Name: json-file
Options:
max-file: '3'
max-size: 10M
Placement: {}
Resources:
Limits:
MemoryBytes: 104857600
Reservations: {}
RestartPolicy:
Condition: on-failure
Delay: 10000000000
MaxAttempts: 10
Mode:
Replicated:
Replicas: 4
UpdateConfig:
Parallelism: 2
Delay: 1000000000
FailureAction: pause
Monitor: 15000000000
MaxFailureRatio: 0.15
RollbackConfig:
Parallelism: 1
Delay: 1000000000
FailureAction: pause
Monitor: 15000000000
MaxFailureRatio: 0.15
EndpointSpec:
Ports:
- Protocol: tcp
PublishedPort: 8080
TargetPort: 80
Labels:
foo: bar
- name: X-Registry-Auth
in: header
description: 'A base64url-encoded auth configuration for pulling from private
registries.
Refer to the [authentication section](#section/Authentication) for
details.
'
type: string
tags:
- Service
/services/{id}:
get:
summary: Inspect a service
operationId: ServiceInspect
responses:
200:
description: no error
schema:
$ref: '#/definitions/Service'
404:
description: no such service
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: id
in: path
description: ID or name of service.
required: true
type: string
- name: insertDefaults
in: query
description: Fill empty fields with default values.
type: boolean
default: false
tags:
- Service
delete:
summary: Delete a service
operationId: ServiceDelete
responses:
200:
description: no error
404:
description: no such service
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: id
in: path
description: ID or name of service.
required: true
type: string
tags:
- Service
/services/{id}/update:
post:
summary: Update a service
operationId: ServiceUpdate
consumes:
- application/json
produces:
- application/json
responses:
200:
description: no error
schema:
$ref: '#/definitions/ServiceUpdateResponse'
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
404:
description: no such service
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: id
in: path
description: ID or name of service.
required: true
type: string
- name: body
in: body
required: true
schema:
allOf:
- $ref: '#/definitions/ServiceSpec'
- type: object
example:
Name: top
TaskTemplate:
ContainerSpec:
Image: busybox
Args:
- top
OomScoreAdj: 0
Resources:
Limits: {}
Reservations: {}
RestartPolicy:
Condition: any
MaxAttempts: 0
Placement: {}
ForceUpdate: 0
Mode:
Replicated:
Replicas: 1
UpdateConfig:
Parallelism: 2
Delay: 1000000000
FailureAction: pause
Monitor: 15000000000
MaxFailureRatio: 0.15
RollbackConfig:
Parallelism: 1
Delay: 1000000000
FailureAction: pause
Monitor: 15000000000
MaxFailureRatio: 0.15
EndpointSpec:
Mode: vip
- name: version
in: query
description: 'The version number of the service object being updated. This is
required to avoid conflicting writes.
This version number should be the value as currently set on the
service *before* the update. You can find the current version by
calling `GET /services/{id}`
'
required: true
type: integer
- name: registryAuthFrom
in: query
description: 'If the `X-Registry-Auth` header is not specified, this parameter
indicates where to find registry authorization credentials.
'
type: string
enum:
- spec
- previous-spec
default: spec
- name: rollback
in: query
description: 'Set to this parameter to `previous` to cause a server-side rollback
to the previous service spec. The supplied spec will be ignored in
this case.
'
type: string
- name: X-Registry-Auth
in: header
description: 'A base64url-encoded auth configuration for pulling from private
registries.
Refer to the [authentication section](#section/Authentication) for
details.
'
type: string
tags:
- Service
/services/{id}/logs:
get:
summary: Get service logs
description: 'Get `stdout` and `stderr` logs from a service. See also
[`/containers/{id}/logs`](#operation/ContainerLogs).
**Note**: This endpoint works only for services with the `local`,
`json-file` or `journald` logging drivers.
'
produces:
- application/vnd.docker.raw-stream
- application/vnd.docker.multiplexed-stream
operationId: ServiceLogs
responses:
200:
description: logs returned as a stream in response body
schema:
type: string
format: binary
404:
description: no such service
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such service: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the service
type: string
- name: details
in: query
description: Show service context and extra details provided to logs.
type: boolean
default: false
- name: follow
in: query
description: Keep connection after returning logs.
type: boolean
default: false
- name: stdout
in: query
description: Return logs from `stdout`
type: boolean
default: false
- name: stderr
in: query
description: Return logs from `stderr`
type: boolean
default: false
- name: since
in: query
description: Only return logs since this time, as a UNIX timestamp
type: integer
default: 0
- name: timestamps
in: query
description: Add timestamps to every log line
type: boolean
default: false
- name: tail
in: query
description: 'Only return this number of log lines from the end of the logs.
Specify as an integer or `all` to output all log lines.
'
type: string
default: all
tags:
- Service
definitions:
HealthConfig:
description: 'A test to perform to check that the container is healthy.
Healthcheck commands should be side-effect free.
'
type: object
properties:
Test:
description: 'The test to perform. Possible values are:
- `[]` inherit healthcheck from image or parent image
- `["NONE"]` disable healthcheck
- `["CMD", args...]` exec arguments directly
- `["CMD-SHELL", command]` run command with system''s default shell
A non-zero exit code indicates a failed healthcheck:
- `0` healthy
- `1` unhealthy
- `2` reserved (treated as unhealthy)
- other values: error running probe
'
type: array
items:
type: string
Interval:
description: 'The time to wait between checks in nanoseconds. It should be 0 or at
least 1000000 (1 ms). 0 means inherit.
'
type: integer
format: int64
Timeout:
description: 'The time to wait before considering the check to have hung. It should
be 0 or at least 1000000 (1 ms). 0 means inherit.
If the health check command does not complete within this timeout,
the check is considered failed and the health check process is
forcibly terminated without a graceful shutdown.
'
type: integer
format: int64
Retries:
description: 'The number of consecutive failures needed to consider a container as
unhealthy. 0 means inherit.
'
type: integer
StartPeriod:
description: 'Start period for the container to initialize before starting
health-retries countdown in nanoseconds. It should be 0 or at least
1000000 (1 ms). 0 means inherit.
'
type: integer
format: int64
StartInterval:
description: 'The time to wait between checks in nanoseconds during the start period.
It should be 0 or at least 1000000 (1 ms). 0 means inherit.
'
type: integer
format: int64
ServiceSpec:
description: User modifiable configuration for a service.
type: object
properties:
Name:
description: Name of the service.
type: string
Labels:
description: User-defined key/value metadata.
type: object
additionalProperties:
type: string
TaskTemplate:
$ref: '#/definitions/TaskSpec'
Mode:
description: Scheduling mode for the service.
type: object
properties:
Replicated:
type: object
properties:
Replicas:
type: integer
format: int64
Global:
type: object
ReplicatedJob:
description: 'The mode used for services with a finite number of tasks that run
to a completed state.
'
type: object
properties:
MaxConcurrent:
description: 'The maximum number of replicas to run simultaneously.
'
type: integer
format: int64
default: 1
TotalCompletions:
description: 'The total number of replicas desired to reach the Completed
state. If unset, will default to the value of `MaxConcurrent`
'
type: integer
format: int64
GlobalJob:
description: 'The mode used for services which run a task to the completed state
on each valid node.
'
type: object
UpdateConfig:
description: Specification for the update strategy of the service.
type: object
properties:
Parallelism:
description: 'Maximum number of tasks to be updated in one iteration (0 means
unlimited parallelism).
'
type: integer
format: int64
Delay:
description: Amount of time between updates, in nanoseconds.
type: integer
format: int64
FailureAction:
description: 'Action to take if an updated task fails to run, or stops running
during the update.
'
type: string
enum:
- continue
- pause
- rollback
Monitor:
description: 'Amount of time to monitor each updated task for failures, in
nanoseconds.
'
type: integer
format: int64
MaxFailureRatio:
description: 'The fraction of tasks that may fail during an update before the
failure action is invoked, specified as a floating point number
between 0 and 1.
'
type: number
default: 0
Order:
description: 'The order of operations when rolling out an updated task. Either
the old task is shut down before the new task is started, or the
new task is started before the old task is shut down.
'
type: string
enum:
- stop-first
- start-first
RollbackConfig:
description: Specification for the rollback strategy of the service.
type: object
properties:
Parallelism:
description: 'Maximum number of tasks to be rolled back in one iteration (0 means
unlimited parallelism).
'
type: integer
format: int64
Delay:
description: 'Amount of time between rollback iterations, in nanoseconds.
'
type: integer
format: int64
FailureAction:
description: 'Action to take if an rolled back task fails to run, or stops
running during the rollback.
'
type: string
enum:
- continue
- pause
Monitor:
description: 'Amount of time to monitor each rolled back task for failures, in
nanoseconds.
'
type: integer
format: int64
MaxFailureRatio:
description: 'The fraction of tasks that may fail during a rollback before the
failure action is invoked, specified as a floating point number
between 0 and 1.
'
type: number
default: 0
Order:
description: 'The order of operations when rolling back a task. Either the old
task is shut down before the new task is started, or the new task
is started before the old task is shut down.
'
type: string
enum:
- stop-first
- start-first
Networks:
description: 'Specifies which networks the service should attach to.
Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead.
'
type: array
items:
$ref: '#/definitions/NetworkAttachmentConfig'
EndpointSpec:
$ref: '#/definitions/EndpointSpec'
ServiceCreateResponse:
type: object
description: 'contains the information returned to a client on the
creation of a new service.
'
properties:
ID:
description: The ID of the created service.
type: string
x-nullable: false
example: ak7w3gjqoa3kuz8xcpnyy0pvl
Warnings:
description: 'Optional warning message.
FIXME(thaJeztah): this should have "omitempty" in the generated type.
'
type: array
x-nullable: true
items:
type: string
example:
- 'unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found'
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
GenericResources:
description: 'User-defined resources can be either Integer resources (e.g, `SSD=3`) or
String resources (e.g, `GPU=UUID1`).
'
type: array
items:
type: object
properties:
NamedResourceSpec:
type: object
properties:
Kind:
type: string
Value:
type: string
DiscreteResourceSpec:
type: object
properties:
Kind:
type: string
Value:
type: integer
format: int64
example:
- DiscreteResourceSpec:
Kind: SSD
Value: 3
- NamedResourceSpec:
Kind: GPU
Value: UUID1
- NamedResourceSpec:
Kind: GPU
Value: UUID2
TaskSpec:
description: User modifiable task configuration.
type: object
properties:
PluginSpec:
type: object
description: 'Plugin spec for the service. *(Experimental release only.)*
<p><br /></p>
> **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are
> mutually exclusive. PluginSpec is only used when the Runtime field
> is set to `plugin`. NetworkAttachmentSpec is used when the Runtime
> field is set to `attachment`.
'
properties:
Name:
description: The name or 'alias' to use for the plugin.
type: string
Remote:
description: The plugin image reference to use.
type: string
Disabled:
description: Disable the plugin once scheduled.
type: boolean
PluginPrivilege:
type: array
items:
$ref: '#/definitions/PluginPrivilege'
ContainerSpec:
type: object
description: 'Container spec for the service.
<p><br /></p>
> **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are
> mutually exclusive. PluginSpec is only used when the Runtime field
> is set to `plugin`. NetworkAttachmentSpec is used when the Runtime
> field is set to `attachment`.
'
properties:
Image:
description: The image name to use for the container
type: string
Labels:
description: User-defined key/value data.
type: object
additionalProperties:
type: string
Command:
description: The command to be run in the image.
type: array
items:
type: string
Args:
description: Arguments to the command.
type: array
items:
type: string
Hostname:
description: 'The hostname to use for the container, as a valid
[RFC 1123](https://tools.ietf.org/html/rfc1123) hostname.
'
type: string
Env:
description: 'A list of environment variables in the form `VAR=value`.
'
type: array
items:
type: string
Dir:
description: The working directory for commands to run in.
type: string
User:
description: The user inside the container.
type: string
Groups:
type: array
description: 'A list of additional groups that the container process will run as.
'
items:
type: string
Privileges:
type: object
description: Security options for the container
properties:
CredentialSpec:
type: object
description: CredentialSpec for managed service account (Windows only)
properties:
Config:
type: string
example: 0bt9dmxjvjiqermk6xrop3ekq
description: 'Load credential spec from a Swarm Config with the given ID.
The specified config must also be present in the Configs
field with the Runtime property set.
<p><br /></p>
> **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`,
> and `CredentialSpec.Config` are mutually exclusive.
'
File:
type: string
example: spec.json
description: 'Load credential spec from this file. The file is read by
the daemon, and must be present in the `CredentialSpecs`
subdirectory in the docker data directory, which defaults
to `C:\ProgramData\Docker\` on Windows.
For example, specifying `spec.json` loads
`C:\ProgramData\Docker\CredentialSpecs\spec.json`.
<p><br /></p>
> **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`,
> and `CredentialSpec.Config` are mutually exclusive.
'
Registry:
type: string
description: 'Load credential spec from this value in the Windows
registry. The specified registry value must be located in:
`HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs`
<p><br /></p>
> **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`,
> and `CredentialSpec.Config` are mutually exclusive.
'
SELinuxContext:
type: object
description: SELinux labels of the container
properties:
Disable:
type: boolean
description: Disable SELinux
User:
type: string
description: SELinux user label
Role:
type: string
description: SELinux role label
Type:
type: string
description: SELinux type label
Level:
type: string
description: SELinux level label
Seccomp:
type: object
description: Options for configuring seccomp on the container
properties:
Mode:
type: string
enum:
- default
- unconfined
- custom
Profile:
description: The custom seccomp profile as a json object
type: string
AppArmor:
type: object
description: Options for configuring AppArmor on the container
properties:
Mode:
type: string
enum:
- default
- disabled
NoNewPrivileges:
type: boolean
description: Configuration of the no_new_privs bit in the container
TTY:
description: Whether a pseudo-TTY should be allocated.
type: boolean
OpenStdin:
description: Open `stdin`
type: boolean
ReadOnly:
description: Mount the container's root filesystem as read only.
type: boolean
Mounts:
description: 'Specification for mounts to be added to containers created as part
of the service.
'
type: array
items:
$ref: '#/definitions/Mount'
StopSignal:
description: Signal to stop the container.
type: string
StopGracePeriod:
description: 'Amount of time to wait for the container to terminate before
forcefully killing it.
'
type: integer
format: int64
HealthCheck:
$ref: '#/definitions/HealthConfig'
Hosts:
type: array
description: "A l
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-service-api-openapi.yml