PEDAGOGICAL OBJECTIVES

• 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.

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:

1. Port: 2376 (input)
2. Port: 2377 (input)

These two ports are used by Docker.

Installing Docker and Docker-Compose

To install docker use: sudo apt install docker.io

Give permission to use the Docker socket:

• sudo groupadd docker

• sudo usermod -aG docker $USER

• newgrp docker

Then install Docker-Compose:

1. 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
2. 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

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

Where 192.168.0.32 is the master IP address.

This command will be executed on any VM or machine wishing to join the Swarm cluster. 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, Azure, Google or Exoscale and what the HES-SO will pay for you if you use SwitchEngine.

TASK 2 - Deploying the application

In this task you will deploy, on the Swarm cluster, the TO Do application represented in Figure 1. The Docker-Compose yaml file is composed of three containers (see the yaml file below).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 Figure 1.

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

Copy the Docker-Compose file provided below to the Master instance and complete it. 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.

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:

redis:    

     container_name: redis

     image: redis

     command: "redis-server --requirepass ccp2 --appendonly yes"

     restart: on-failure

     deploy: 

               placement: 

                            constraints: 

                                     “node.role==manager”

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>”

• “spec.labels.something”

• “spec.labels.something==value

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 3 - Add replicas

In this task you will update the Docker Compose file to add replicas to each service.

1. Have a look to the Docker-Compose reference: https://docs.docker.com/compose/compose-file/#deploy
2. Note that you are viewing the reference for version 3 of Compose file
3. Edit the services in such a way that you deploy 2 instances of the API and Frontend.
4. Take down the stack of services using: docker stack rm <name of stack>
5. Redeploy the new stack of services, with the replicas.
6. How does Swarm deal with the loss of a replica?
7. How can you update the numbers of replicas without re-deploying with the docker-compose file?
8. Is there a default way to auto-scale with Swarm?

CLEANUP

At the end of the lab session, delete all VMs.

Additional documentation

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/