- Become familiar with SWARM and its command-line tool
- Create and manage a SWARM cluster
- Define, deploy and run a web application using SWARM.
INTRODUCTION AND PREREQUISITES
In this lab you will perform a number of tasks. Each task specifies one or more deliverables to be produced.
You will create a Docker Swarm cluster, using the command line tool. Then, you will deploy an application (“stack of services” in Swarm terminology): Redis, backend and frontend.
The goal of the first part is to learn how to deploy and configure a Docker Swarm cluster. On the second part you’ll learn how to specify deployment instructions, and make the application resilient to failures. The application stack will be deployed using a docker-compose YAML file.
The following resources and tools are required for this lab:
- A web browser
- 3 Ubuntu 18.04 VM instances (We experimented this exercise on SwitchEngine)
- Docker and Docker-Compose installed on those instances
Each student group has to create a SSH Key that will be used on the 3 VM instances. This can be created on SwitchEngines, and stored locally.
The Docker-Compose file needed for this lab is provided at the end of this document.
Task 1 - Creating the Swarm cluster
To create the Swarm, first create 3 VM instances. One of these instances will be the Master (called also the manager) of the Swarm cluster, while the others will be the Workers. Be sure to give appropriate names to the instances you create. These names will be used to identify the nodes of your Swarm cluster. Also, be sure to use the same SSH key for all the instances.
In the security groups add the following rules:
- Port 2376 (input)
- Port 2377 (input)
These ports are used by Docker. Please take note that you will need to open additional ports according to the application you deploy.
Task 2 - Installing Docker and Docker-Compose
To install docker use: sudo apt update && sudo apt install docker.io
Give permission to use the Docker socket:
sudo groupadd docker
sudo usermod -aG docker $USER
Then install Docker-Compose:
- sudo curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
- sudo chmod +x /usr/local/bin/docker-compose
Test if docker-compose works: docker-compose --version
If it doesn’t: sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Task 3 - Creating the Swarm cluster
On the designated Master Instance do: docker swarm init.
This will create an empty Swarm cluster, where the Master is the current VM. The output from this command is a string representing a command:
docker swarm join --token SWMTKN-1-5g4u7dpjwf2wnms9tuix3zruo3affi1i5y02nbempdyvv3a6zn-9z47shhlb5cr0ql31rcvrlev1 192.168.0.32:2377
This command will be executed on any VM or machine wishing to join the Swarm cluster. In this case 192.168.0.32 is the IP address of the master. Any VM or machine having the token can apply to be a worker.
The result should be: This node joined a swarm as a worker.
On the master, check how the Swarm is composed by using the following command line: docker node ls
This will show you all the nodes in your Swarm cluster and their availability.
You can remove a node from your swarm by using: docker node rm <name of the node>
To view the command line to join the Swarm cluster as a worker, execute this command on the current manager: docker swarm join-token worker
Take note that we can have several managers in the same cluster. To get the command to execute in order to create a new manager, type: docker swarm join-token manager
You don't need more than 2 workers to do this exercise. Think about your credit if you use AWS Amazon what the HES-SO, HEPIA will pay for you if you use SwitchEngine.
TASK 4 - Deploying the application
In this task you will deploy, on the Swarm cluster the application represented in Figure 1. The goal of the provided example application is to store and edit a To Do list. The application consists of a simple Web UI (Frontend) that uses a REST API (API service) to access a Key Value storage service (Redis). Ports to be used for Pods and Services are shown in the figure.
Figure 1: TO DO Application
The required Docker images are provided on Docker Hub:
- Frontend: icclabcna/ccp2-k8s-todo-frontend
- API backend: icclabcna/ccp2-k8s-todo-api
- Redis: redis:3.2.10-alpine
The goal of this exercise is twofold:
- develop the Docker-Compose file related to the application represented in Figure 1.
- deploy the application on the SWARM cluster you have created in Task 1.
Type this command to deploy the TO DO application: docker stack deploy --compose-file <path to the compose file> <name for the stack>
To check the deployment: docker service ls
You can see the services created, the replicas and the placement of each service. It takes a few seconds for the replicas to be created and deployed.
You must be able to access the frontend in your browser: <IP of frontend VM>:8080
In this case the Master instance will place each service according to its scheduling policy. with each deployment you might have a different placement of services.
Task 5 - Specifying Deployment
In the Docker-Compose file we can specify where we want some or all of our services to be deployed.
In the Master instance: docker node inspect <name of the node to be inspected>
This command will display a JSON file representing the node to be inspected. This JSON file is created by the Master when a node enters the Swarm cluster, and we can use most of these fields to specify where we want the service to be deployed.
In the compose file, on the first service (redis), change the service so that it is as following:
command: "redis-server --requirepass ccp2 --appendonly yes"
With this we are asking the manager to deploy the redis service on a node that has a manager role.
Other placements can be specified by using different syntax:
- “node.hostname==<name of the node>”
See this URL for further details: https://docs.docker.com/compose/compose-file/#placement
We can also change or add these JSON fields on the nodes in our Swarm:
docker node update --label-add <label> <Node Name>
docker node update --label-add <key>:<value> <Node Name>
TASK 6 - Add replicas
In this task you will update the Docker Compose file to add replicas to each service.
- Have a look to the Docker-Compose reference: https://docs.docker.com/compose/compose-file/#deploy
- Note that you are viewing the reference for version 3 of Compose file
- Edit the services in such a way that you deploy 2 instances of the API and Frontend.
- Take down the stack of services using: docker stack rm <name of stack>
- Redeploy the new stack of services, with the replicas.
- How does Swarm deal with the loss of a replica?
- How can you update the numbers of replicas without re-deploying with the docker-compose file?
- Is there a default way to auto-scale with Swarm?
At the end of the lab session, delete all VMs.
Docker documentation can be found on the following pages:
- Docker CLI: https://docs.docker.com/engine/reference/commandline/docker/
- Docker Overview: https://docs.docker.com/get-started/overview/
- What is a Docker Service: https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/
- Docker Swarm Overview: https://docs.docker.com/engine/swarm/