This is a proposal to add a top-level type of object - the “service” - to Docker, along with CLI commands and remote API endpoints for managing services.

1. A service is a group of containers which optionally specifies a default image and configuration overrides (portable configuration only, not hostconfig).
2. At any given time, a service has zero or more containers.
3. A container can belong to zero or one service.
4. A service’s containers can be started, stopped and removed as a unit.

Summary of changes

Three new commands will be implemented:

• docker services - list services
• docker services create NAME [CONFIG] [IMAGE] [COMMAND] - create a service
• docker services rm NAME - remove a service

A --service NAME option will be added to the following commands: ps, run, start, stop, kill, rm

The remote API extensions necessary to support this work are still to be designed.

Usage

Services can be created at the command line with docker services create, whose signature is like docker run’s:

$ docker services create NAME [CONFIG] [IMAGE] [COMMAND...]

However, only portable configuration (of the kind that you can put in a Dockerfile) can be specified: -p 8000 is allowed, -p 80:8000 isn’t.

$ docker services create web --command "python app.py" -p 8000 myimage

$ docker services
NAME  IMAGE    CONTAINERS
web   myimage  0

Then containers can be created inside a service with docker run. Overrides to configuration can be passed in. If a service has a default image specified, docker run does not require it to be specified again.

$ docker run -d --service web
$ docker run -d --service web -p 80:8000
$ docker run -d --service web differentimage

$ docker services list
NAME  IMAGE    CONTAINERS
web   myimage  3

$ docker ps --service web
CONTAINER ID   IMAGE           COMMAND         PORTS       
696d99b4b84f   myimage         python app.py
b54e9449c72a   myimage         python app.py   80->8000
84caf0ebf6e7   differentimage  python app.py

A service’s containers can be started, stopped, killed and removed as a unit:

$ docker stop --service web
$ docker start --service web
$ docker kill --service web
$ docker rm --service web

The service itself can be removed if it has no containers.

$ docker services rm web

Future thoughts

• Nesting of services and encapsulation of their component containers
• How services interact with links
• Serializing/deserializing service configuration to/from a file