How to use docker stack deploy command to manage swarm services

Introduction

In this lab, you will learn how to effectively manage Docker Swarm services using the docker stack deploy command. We will begin by preparing a simple docker-compose.yml file, which serves as the blueprint for our application stack.

Following the preparation, you will deploy this stack to your Docker Swarm, verify the successful deployment of the defined services, and then explore how to update the stack by modifying the compose file. Finally, you will learn how to prune services that are no longer referenced in the updated configuration, ensuring your Swarm remains clean and efficient.

Prepare a simple docker-compose file for swarm deployment

In this step, we will prepare a simple docker-compose.yml file that we will use to deploy a stack to a Docker Swarm. Before we can use docker-compose, we need to install it.

First, let's install docker-compose. We will download the binary and make it executable.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

This command downloads the docker-compose binary from the official GitHub releases page and saves it to /usr/local/bin/docker-compose. The $(uname -s) and $(uname -m) parts automatically detect your operating system and architecture. The chmod +x command makes the downloaded file executable.

Now, let's verify the installation by checking the version.

docker-compose --version

You should see the installed version of docker-compose printed to the console.

Next, we will create a simple docker-compose.yml file in the ~/project directory. This file will define a single service using the nginx image.

nano ~/project/docker-compose.yml

Paste the following content into the nano editor:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"

Let's break down this docker-compose.yml file:

• version: '3.8' specifies the Compose file format version. Version 3.8 is suitable for Swarm deployments.
• services: defines the services that make up your application.
• web: is the name of our service. You can choose any name you like.
• image: nginx:latest specifies the Docker image to use for this service. We are using the latest version of the official nginx image.
• ports: maps ports between the host and the container. "80:80" maps port 80 on the host to port 80 in the container.

Save the file by pressing Ctrl + X, then Y, and then Enter.

Before we can deploy this service, we need to make sure the nginx:latest image is available locally. We can pull the image using the docker pull command.

docker pull nginx:latest

This command downloads the nginx:latest image from Docker Hub to your local machine.

Now you have a simple docker-compose.yml file ready for deployment and the necessary image pulled.

Deploy a stack to the swarm using the compose file

In this step, we will deploy the stack defined in our docker-compose.yml file to a Docker Swarm. Before we can deploy a stack, we need to initialize a Docker Swarm.

First, let's initialize the Swarm. Since we are using a single VM, we will initialize it as a single-node Swarm.

docker swarm init

This command initializes a new Swarm and makes the current node a manager node. You should see output indicating that the Swarm has been initialized.

Now that the Swarm is initialized, we can deploy our stack using the docker stack deploy command. We will give our stack a name, for example, mywebstack.

docker stack deploy -c ~/project/docker-compose.yml mywebstack

Let's break down this command:

• docker stack deploy is the command used to deploy a stack to a Swarm.
• -c ~/project/docker-compose.yml specifies the Compose file to use for the deployment. We are using the file we created in the previous step.
• mywebstack is the name we are giving to our stack. This name will be used to identify the services and containers belonging to this stack within the Swarm.

After running this command, Docker Swarm will create the services defined in the docker-compose.yml file. You should see output indicating that the services are being created or updated.

To verify that the stack has been deployed, we can list the running stacks.

docker stack ls

This command will show you a list of all deployed stacks in your Swarm. You should see mywebstack listed.

We can also list the services running within our stack.

docker stack services mywebstack

This command will show you the services associated with the mywebstack stack. You should see the mywebstack_web service listed, along with information about its replicas and image.

Finally, let's check the status of the service tasks.

docker service ps mywebstack_web

This command shows the tasks (running containers) for the mywebstack_web service. You should see at least one task with a state of Running.

You have now successfully initialized a Docker Swarm and deployed a stack using a docker-compose.yml file.

Verify the deployed services

In this step, we will verify that the services deployed in the previous step are running correctly and are accessible. We deployed an Nginx web server, which should be listening on port 80.

First, let's use the docker service ls command to see the list of services running in the Swarm.

docker service ls

You should see the mywebstack_web service listed with 1/1 replicas, indicating that one instance of the service is running.

Next, we can use curl to access the Nginx web server running inside the container. Since we mapped port 80 on the host to port 80 in the container, we can access it via localhost on port 80.

curl localhost:80

This command sends an HTTP request to localhost on port 80. If the Nginx server is running correctly, you should receive the default Nginx welcome page HTML as the output. This confirms that the service is running and accessible from the host machine.

To further inspect the running container for the web service, we can use the docker ps command.

docker ps

This command lists all running containers. You should see a container running the nginx image, with a name similar to mywebstack_web.1.<task_id>. The PORTS column should show 0.0.0.0:80->80/tcp, confirming the port mapping.

We can also inspect the details of the service using the docker service inspect command.

docker service inspect mywebstack_web

This command provides detailed information about the mywebstack_web service, including its configuration, tasks, and network settings. You can scroll through the output to see various details about the service.

By performing these checks, we have verified that our deployed Nginx service is running as expected and is accessible.

Update the stack with a modified compose file

In this step, we will modify our docker-compose.yml file to update the deployed stack. We will change the Nginx image version and add a second service.

First, let's edit the docker-compose.yml file.

nano ~/project/docker-compose.yml

Modify the file to include a second service, for example, an alpine service, and change the Nginx image version to 1.21.6. The updated file should look like this:

version: "3.8"
services:
  web:
    image: nginx:1.21.6
    ports:
      - "80:80"
  alpine:
    image: alpine:latest
    command: ["sleep", "infinity"]

Let's look at the changes:

• We changed the image for the web service from nginx:latest to nginx:1.21.6.
• We added a new service named alpine.
• The alpine service uses the alpine:latest image.
• The command: ["sleep", "infinity"] keeps the alpine container running indefinitely.

Save the modified file by pressing Ctrl + X, then Y, and then Enter.

Before deploying the updated stack, we need to pull the new nginx:1.21.6 and alpine:latest images.

docker pull nginx:1.21.6
docker pull alpine:latest

Now, we can deploy the updated stack using the same docker stack deploy command and the same stack name. Docker Swarm will detect the changes in the docker-compose.yml file and update the existing stack.

docker stack deploy -c ~/project/docker-compose.yml mywebstack

Docker Swarm will perform a rolling update for the web service, replacing the old nginx:latest container with a new one using nginx:1.21.6. It will also create the new alpine service and its corresponding container. You should see output indicating the services are being updated or created.

To verify the update, let's list the services in the stack again.

docker stack services mywebstack

You should now see both mywebstack_web and mywebstack_alpine services listed. The mywebstack_web service should show the updated image nginx:1.21.6.

You have successfully updated your deployed stack by modifying the docker-compose.yml file and redeploying it.

Prune services no longer referenced in the compose file

In this step, we will modify our docker-compose.yml file again, this time removing a service. When we redeploy the stack, Docker Swarm will detect that a service is no longer defined in the Compose file and will remove it. This process is sometimes referred to as "pruning" services.

First, let's edit the docker-compose.yml file to remove the alpine service.

nano ~/project/docker-compose.yml

Remove the entire alpine: section from the file. The file should revert back to its original state, defining only the web service:

version: "3.8"
services:
  web:
    image: nginx:1.21.6
    ports:
      - "80:80"

Save the modified file by pressing Ctrl + X, then Y, and then Enter.

Now, deploy the stack again using the modified docker-compose.yml file.

docker stack deploy -c ~/project/docker-compose.yml mywebstack

Docker Swarm will compare the current state of the mywebstack stack with the definition in the updated docker-compose.yml file. It will notice that the alpine service is no longer present in the file and will remove the corresponding service and its tasks from the Swarm. You should see output indicating that the alpine service is being removed.

To verify that the alpine service has been removed, list the services in the stack again.

docker stack services mywebstack

You should now only see the mywebstack_web service listed. The mywebstack_alpine service should be gone.

Finally, to clean up the Swarm environment, we can remove the entire stack.

docker stack rm mywebstack

This command removes the mywebstack stack, including all its services and tasks. You should see output confirming the removal.

To verify that the stack is removed, list the stacks again.

docker stack ls

The mywebstack should no longer be listed.

You have successfully pruned a service from your stack by removing it from the docker-compose.yml file and redeploying, and then cleaned up the environment by removing the entire stack.

Summary

In this lab, we learned how to use the docker stack deploy command to manage Docker Swarm services. We began by preparing a simple docker-compose.yml file, which is the standard way to define multi-service applications for Docker. This involved installing docker-compose and creating a basic YAML file defining a single Nginx service with port mapping.

Following the preparation, we deployed this stack to a Docker Swarm using docker stack deploy, verified the successful deployment of the service, and then practiced updating the stack by modifying the docker-compose.yml file and redeploying. Finally, we learned how to prune services that are no longer defined in the updated compose file, ensuring our Swarm environment remains clean and reflects the current application definition.