To deploy containers onto a Docker Swarm, you create Docker services. Creating a service is a little like creating a container – you specify the image to use and which commands to run inside the created containers. You can also specify other options including CPU and memory limits, the number of replicas of the image to run in the Swarm, the network to connect to, and ports to make the service available outside the Docker swarm. You can read about how docker services work here.
NOTE: All the commands used in this article are cluster management commands, and must be executed on a swarm manager node.
How to Create a Docker Service
You can create a single instance docker service (a container running on a single host in the docker swarm) by running the docker service create command on a swarm manager node:
$ docker service create nginx
This will create an NGINX container on one of the nodes in the docker swarm. We can create a docker service with multiple replicas by running the following:
docker service create --name nginx --replicas 3 -p 8080:80 nginx
This will create a service based on the NGINX image, with 3 replicas, and expose port 8080 on the host which will forward to port 80 on the container/service. Now, opening a browser session to any of the nodes on port 8080 will result in a connection to NGINX:
Listing Docker Services
You can list docker services running in the swarm with the docker service ls command:
$ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS uxxkfkak1xu2 eloquent_babbage replicated 1/1 nginx:lates
We can list the tasks for the service using:
docker service ps nginx
This shows the tasks (containers) that make up the service, their current state and the hosts upon which the tasks are running.
Inspect a Docker Service
We can get more information about a docker service by using the docker service inspect command. This command will display information about the service in JSON format:
$ docker service inspect nginx
The –pretty flag can be used to return an output that is easier to read:
$ docker service inspect --pretty nginx
ID: a2g4fwtzo3ge1d626q13rqfjf Name: nginx Service Mode: Replicated Replicas: 3 Placement: UpdateConfig: Parallelism: 1 On failure: pause Monitoring Period: 5s Max failure ratio: 0 Update order: stop-first RollbackConfig: Parallelism: 1 On failure: pause Monitoring Period: 5s Max failure ratio: 0 Rollback order: stop-first ContainerSpec: Image: Nginx:latest@sha256:21f32f6c08406306d822a0e6e8b7dc81f53f336570e852e25fbe1e3e3d0d0133 Init: false Resources: Endpoint Mode: vip Ports: PublishedPort = 8080 Protocol = tcp TargetPort = 80 PublishMode = ingress
Changing / Updating an Existing Docker Service
We can make changes to an existing service by using the docker service update command. For example, if we wanted to add a CPU limit to the service we could run:
$ docker service update --limit-cpu 1 nginx
Scaling a Docker Service
We can set the number of replicas for a docker service by running:
$ docker service update --replicas 2 nginx
Running docker service ls then displays the following. We can see there are two replicas for the NGINX service:
$ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS
uxxkfkak1xu2 eloquent_babbage replicated 1/1 nginx:latest
a2g4fwtzo3ge nginx replicated 2/2 nginx:latest *:8080->80/tcp
Now, updating the service to use 4 replicas:
$ docker service update --replicas 4 nginx
Running the docker service ls command now shows that we have 4 replicas for the NGINX service:
$ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS
uxxkfkak1xu2 eloquent_babbage replicated 1/1 nginx:latest
a2g4fwtzo3ge nginx replicated 2/2 nginx:latest *:8080->80/tcp
Note, you can also change the number of replicas by using the docker service scale command. For example:
docker service scale nginx=4
Replicated Services and Global Services
So far, all the examples I’ve used are working with replicated services. A replicated service is where the service runs the requested number of replica tasks across the swarm cluster, regardless of the number of docker nodes in the cluster.
A global service is where one task is ran on each node in the cluster. If there are 3 docker nodes in the swarm cluster, a task will be created on each. You can create a replicated service with a command such as:
$ docker service create --replicas 3 nginx
Or a global service with:
$ docker service create --mode global nginx
You can see what mode the service is from the docker service ls command:
$ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS
uxxkfkak1xu2 eloquent_babbage replicated 1/1 nginx:latest
a2g4fwtzo3ge nginx replicated 3/3 nginx:latest *:8080->80/tcp
uljrwtgvfonv web global 3/3 nginx:latest
Updating Docker Services
You can update a docker service by changing the image it is based on. Docker swarm lets you perform a rolling update on your running services. Rolling updates have the following benefits
- No downtime (Because it only updates a number of replicas at a time)
- Updates can be paused when an issue occurs
Before running an update there are some options to be aware of. You can choose whether to start the new container before deleting the old one, when running a rolling update. To do so, use:
docker service update -d --update-order start-first nginx
This flag will tell Swarm how many tasks it will update in parallel:
docker service update --update-parallelism 3 nginx
You can also set the service to roll back should an error be encountered:
docker service update --detach=false --update-failure-action rollback nginx
To update a service:
$ docker service update --image nginx:latest nginx
Now if we run the docker service ls command we can see that the service is using the latest image:
$ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS
pv4h84ck91mk nginx replicated 3/3 nginx:latest *:8080->80/tcp
You can manually roll back a service to the previous image by using the docker service rollback command:
$ docker service rollback nginx
Limiting Service Resources
You can limit the docker node resources consumed by a service. It’s possible to limit CPU and Memory resources assigned to a task, and it’s also possible to reserve host node resources for a task:
- –limit-cpu – limits the CPU resources of a service
- –limit-memory – limits the memory usage of a service
- –reserve-cpu – Reserves a specific amount of CPU
- –reserve-memory – Reserves a specific amount of memory
You can use these options with the docker service create or docker service update commands. For example:
docker service create --name=nginx --limit-cpu 0.1 --limit-memory 1G nginx:latest
Deleting a Docker Service
To delete a docker service, use the docker service rm command. For example:
docker service rm nginx
Learning Docker?
If you are starting out, then I highly recommend this book. Thirsty for more?
Then it’s time to take your Docker skills to the next level with this book (It’s my favorite). Also, check out my page on Docker Certification.