Docker Engine API
  1. Service
Docker Engine API
  • System
    • Ping
      GET
    • Check auth configuration
      POST
    • Monitor events
      GET
    • Get system information
      GET
    • Get data usage information
      GET
    • Get version
      GET
  • Image
    • Build an image
      POST
    • Delete builder cache
      POST
    • Create a new image from a container
      POST
    • Create an image
      POST
    • Export several images
      GET
    • List Images
      GET
    • Import images
      POST
    • Delete unused images
      POST
    • Search images
      GET
    • Remove an image
      DELETE
    • Export an image
      GET
    • Get the history of an image
      GET
    • Inspect an image
      GET
    • Push an image
      POST
    • Tag an image
      POST
  • Config
    • List configs
    • Create a config
    • Delete a config
    • Inspect a config
    • Update a Config
  • Container
    • Create a container
    • List containers
    • Delete stopped containers
    • Remove a container
    • Get an archive of a filesystem resource in a container
    • Get information about files in a container
    • Extract an archive of files or folders to a directory in a container
    • Attach to a container
    • Attach to a container via a websocket
    • Get changes on a container’s filesystem
    • Export a container
    • Inspect a container
    • Kill a container
    • Get container logs
    • Pause a container
    • Rename a container
    • Resize a container TTY
    • Restart a container
    • Start a container
    • Get container stats based on resource usage
    • Stop a container
    • List processes running inside a container
    • Unpause a container
    • Update a container
    • Wait for a container
  • Exec
    • Create an exec instance
    • Inspect an exec instance
    • Resize an exec instance
    • Start an exec instance
  • Distribution
    • Get image information from the registry
  • Network
    • List networks
    • Create a network
    • Delete unused networks
    • Remove a network
    • Inspect a network
    • Connect a container to a network
    • Disconnect a container from a network
  • Node
    • List nodes
    • Delete a node
    • Inspect a node
    • Update a node
  • Plugin
    • List plugins
    • Create a plugin
    • Get plugin privileges
    • Install a plugin
    • Remove a plugin
    • Disable a plugin
    • Enable a plugin
    • Inspect a plugin
    • Push a plugin
    • Configure a plugin
    • Upgrade a plugin
  • Secret
    • List secrets
    • Create a secret
    • Delete a secret
    • Inspect a secret
    • Update a Secret
  • Service
    • List services
      GET
    • Create a service
      POST
    • Delete a service
      DELETE
    • Inspect a service
      GET
    • Get service logs
      GET
    • Update a service
      POST
  • Session (experimental)
    • Initialize interactive session
  • Swarm
    • Inspect swarm
    • Initialize a new swarm
    • Join an existing swarm
    • Leave a swarm
    • Unlock a locked manager
    • Get the unlock key
    • Update a swarm
  • Task
    • List tasks
    • Inspect a task
  • Volume
    • List volumes
    • Create a volume
    • Delete unused volumes
    • Remove a volume
    • Inspect a volume
  • Get task logs
    GET
  1. Service

Create a service

/v1.33
/v1.33
/v1.33
/v1.33
POST
/services/create
Service
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/v1.33/services/create' \
--header 'Content-Type: application/json' \
--data-raw '{
    "EndpointSpec": {
        "Mode": "vip",
        "Ports": [
            {
                "Name": "string",
                "Protocol": "tcp",
                "PublishedPort": 8080,
                "TargetPort": 80
            }
        ]
    },
    "Labels": {
        "property1": "string",
        "property2": "string",
        "foo": "bar"
    },
    "Mode": {
        "Global": {},
        "Replicated": {
            "Replicas": 4
        }
    },
    "Name": "web",
    "Networks": [
        {
            "Aliases": [
                "string"
            ],
            "Target": "string"
        }
    ],
    "RollbackConfig": {
        "Delay": 1000000000,
        "FailureAction": "pause",
        "MaxFailureRatio": 0.15,
        "Monitor": 15000000000,
        "Order": "stop-first",
        "Parallelism": 1
    },
    "TaskTemplate": {
        "ContainerSpec": {
            "Args": [
                "string"
            ],
            "Command": [
                "string"
            ],
            "Configs": [
                {
                    "ConfigID": "string",
                    "ConfigName": "string",
                    "File": {
                        "GID": "string",
                        "Mode": 0,
                        "Name": "string",
                        "UID": "string"
                    }
                }
            ],
            "DNSConfig": {
                "Nameservers": [
                    "8.8.8.8"
                ],
                "Options": [
                    "timeout:3"
                ],
                "Search": [
                    "example.org"
                ]
            },
            "Dir": "string",
            "Env": [
                "string"
            ],
            "Groups": [
                "string"
            ],
            "HealthCheck": {
                "Interval": 0,
                "Retries": 0,
                "StartPeriod": 0,
                "Test": [
                    "string"
                ],
                "Timeout": 0
            },
            "Hostname": "string",
            "Hosts": [
                "10.10.10.10 host1",
                "ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
            ],
            "Image": "nginx:alpine",
            "Labels": {
                "property1": "string",
                "property2": "string"
            },
            "Mounts": [
                {
                    "BindOptions": {
                        "Propagation": "private"
                    },
                    "Consistency": "string",
                    "ReadOnly": true,
                    "Source": "web-data",
                    "Target": "/usr/share/nginx/html",
                    "TmpfsOptions": {
                        "Mode": 0,
                        "SizeBytes": 0
                    },
                    "Type": "volume",
                    "VolumeOptions": {
                        "DriverConfig": {
                            "Name": "string",
                            "Options": {
                                "property1": "string",
                                "property2": "string"
                            }
                        },
                        "Labels": {
                            "property1": "string",
                            "property2": "string",
                            "com.example.something": "something-value"
                        },
                        "NoCopy": false
                    }
                }
            ],
            "OpenStdin": true,
            "Privileges": {
                "CredentialSpec": {
                    "File": "string",
                    "Registry": "string"
                },
                "SELinuxContext": {
                    "Disable": true,
                    "Level": "string",
                    "Role": "string",
                    "Type": "string",
                    "User": "string"
                }
            },
            "ReadOnly": true,
            "Secrets": [
                {
                    "File": {
                        "GID": "33",
                        "Mode": 384,
                        "Name": "www.example.org.key",
                        "UID": "33"
                    },
                    "SecretID": "fpjqlhnwb19zds35k8wn80lq9",
                    "SecretName": "example_org_domain_key"
                }
            ],
            "StopGracePeriod": 0,
            "StopSignal": "string",
            "TTY": true,
            "User": "33"
        },
        "ForceUpdate": 0,
        "LogDriver": {
            "Name": "json-file",
            "Options": {
                "property1": "string",
                "property2": "string",
                "max-file": "3",
                "max-size": "10M"
            }
        },
        "Networks": [
            {
                "Aliases": [
                    "string"
                ],
                "Target": "string"
            }
        ],
        "Placement": {
            "Constraints": [
                "node.hostname!=node3.corp.example.com",
                "node.role!=manager",
                "node.labels.type==production"
            ],
            "Platforms": [
                {
                    "Architecture": "x86_64",
                    "OS": "linux"
                }
            ],
            "Preferences": [
                {
                    "Spread": {
                        "SpreadDescriptor": "node.labels.datacenter"
                    }
                },
                {
                    "Spread": {
                        "SpreadDescriptor": "node.labels.rack"
                    }
                }
            ]
        },
        "PluginSpec": {
            "Disabled": true,
            "Name": "string",
            "PluginPrivilege": [
                {
                    "Description": "string",
                    "Name": "string",
                    "Value": [
                        "string"
                    ]
                }
            ],
            "Remote": "string"
        },
        "Resources": {
            "Limits": {
                "GenericResources": [
                    {
                        "DiscreteResourceSpec": {
                            "Kind": "SSD",
                            "Value": 3
                        }
                    },
                    {
                        "NamedResourceSpec": {
                            "Kind": "GPU",
                            "Value": "UUID1"
                        }
                    },
                    {
                        "NamedResourceSpec": {
                            "Kind": "GPU",
                            "Value": "UUID2"
                        }
                    }
                ],
                "MemoryBytes": 104857600,
                "NanoCPUs": 4000000000
            },
            "Reservation": {
                "GenericResources": [
                    {
                        "DiscreteResourceSpec": {
                            "Kind": "SSD",
                            "Value": 3
                        }
                    },
                    {
                        "NamedResourceSpec": {
                            "Kind": "GPU",
                            "Value": "UUID1"
                        }
                    },
                    {
                        "NamedResourceSpec": {
                            "Kind": "GPU",
                            "Value": "UUID2"
                        }
                    }
                ],
                "MemoryBytes": 8272408576,
                "NanoCPUs": 4000000000
            },
            "Reservations": {}
        },
        "RestartPolicy": {
            "Condition": "on-failure",
            "Delay": 10000000000,
            "MaxAttempts": 10,
            "Window": 0
        },
        "Runtime": "string"
    },
    "UpdateConfig": {
        "Delay": 1000000000,
        "FailureAction": "pause",
        "MaxFailureRatio": 0.15,
        "Monitor": 15000000000,
        "Order": "stop-first",
        "Parallelism": 2
    }
}'
Response Response Example
201 - Example 1
{
    "ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
    "Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}

Request

Header Params
X-Registry-Auth
string 
optional
A base64-encoded auth configuration for pulling from private registries. See the authentication section for details.
Body Params application/json
User modifiable configuration for a service.
EndpointSpec
object 
EndpointSpec
optional
Properties that can be configured to access and load balance a service.
Mode
enum<string> 
optional
The mode of resolution to use for internal load balancing between tasks.
Allowed values:
vipdnsrr
Default:
vip
Ports
array[object (EndpointPortConfig) {4}] 
optional
List of exposed ports that this service is accessible on from the outside. Ports can only be provided if vip resolution mode is used.
Labels
object 
optional
User-defined key/value metadata.
Mode
object 
optional
Scheduling mode for the service.
Global
object 
optional
Replicated
object 
optional
Name
string 
optional
Name of the service.
Networks
array [object {2}] 
optional
Array of network names or IDs to attach the service to.
Aliases
array[string]
optional
Target
string 
optional
RollbackConfig
object 
optional
Specification for the rollback strategy of the service.
Delay
integer <int64>
optional
Amount of time between rollback iterations, in nanoseconds.
FailureAction
enum<string> 
optional
Action to take if an rolled back task fails to run, or stops running during the rollback.
Allowed values:
continuepause
MaxFailureRatio
number 
optional
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.
Default:
0
Monitor
integer <int64>
optional
Amount of time to monitor each rolled back task for failures, in nanoseconds.
Order
enum<string> 
optional
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.
Allowed values:
stop-firststart-first
Parallelism
integer <int64>
optional
Maximum number of tasks to be rolled back in one iteration (0 means unlimited parallelism).
TaskTemplate
object 
TaskSpec
optional
User modifiable task configuration.
ContainerSpec
object 
optional
Invalid when specified with PluginSpec.
ForceUpdate
integer 
optional
A counter that triggers an update even if no relevant parameters have been changed.
LogDriver
object 
optional
Specifies the log driver to use for tasks created from this spec. If not present, the default one for the swarm will be used, finally falling back to the engine default if not specified.
Networks
array [object {2}] 
optional
Placement
object 
optional
PluginSpec
object 
optional
Invalid when specified with ContainerSpec. (Experimental release only.)
Resources
object 
optional
Resource requirements which apply to each individual container created as part of the service.
RestartPolicy
object 
optional
Specification for the restart policy which applies to containers created as part of this service.
Runtime
string 
optional
Runtime is the type of runtime specified for the task executor.
UpdateConfig
object 
optional
Specification for the update strategy of the service.
Delay
integer <int64>
optional
Amount of time between updates, in nanoseconds.
FailureAction
enum<string> 
optional
Action to take if an updated task fails to run, or stops running during the update.
Allowed values:
continuepauserollback
MaxFailureRatio
number 
optional
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.
Default:
0
Monitor
integer <int64>
optional
Amount of time to monitor each updated task for failures, in nanoseconds.
Order
enum<string> 
optional
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.
Allowed values:
stop-firststart-first
Parallelism
integer <int64>
optional
Maximum number of tasks to be updated in one iteration (0 means unlimited parallelism).
Examples

Responses

🟢201no error
application/json
Body
ID
string 
optional
The ID of the created service.
Warning
string 
optional
Optional warning message
🟠400bad parameter
🟠403network is not eligible for services
🟠409name conflicts with an existing service
🔴500server error
🔴503node is not part of a swarm
Modified at 2022-09-10 17:56:07
Previous
List services
Next
Delete a service
Built with