Instantiate docker containers using custom docker-compose files (sys-admin nomination required)¶

Table of Contents

Instantiate docker containers using custom docker-compose files (sys-admin nomination required)

Prerequisites ¶

Make sure you are registered to the IAM system of INFN-CLOUD, https://iam.cloud.infn.it. Only registered users can login into the INFN-CLOUD dashboard, https://my.cloud.infn.it.

Access to the INFN-CLOUD dashboard enables users to exploit the “docker compose” solution.

The solution described in this guide consists on instantiation of a Virtual Machine, using Ubuntu 20.04 operating system, with docker engine and docker-compose pre-installed, and optionally run a docker compose file fetched from a specified URL. The instantiation of a VM comes with the responsibility of maintaining it and all the services it hosts.

Please read the INFN Cloud AUP in order to understand the responsibilities you have in managing this service.

How to deploy and access services instantiated using docker-compose ¶

Docker-compose allows the instantiation of fully functional production level services by using a set of coordinated dockers. The public IP Address of the VM hosting the docker containers is made available to the docker-compose file as an environment variable: HOST_PUBLIC_IP.

Step 1 - Connecting and authenticating to the INFN-CLOUD dashboard ¶

Connect to the INFN-CLOUD dashboard (https://my.cloud.infn.it/). You can authenticate with the credentials used for the IAM account (https://iam.cloud.infn.it/login) in order to access the dashboard.

Fig 1: INFN-CLOUD welcome dashboard

Fig2: INFN-CLOUD IAM login

Step 2 - Selection of the Deployment type ¶

After login into the dashboard, select the “Docker compose” card in the service catalog and click on the Configure button.

Fig3: Dashboard

A menu is made available, as in the figure below, and you have to choose the configuration of the docker storage:

Fig4: Storage options

The first choice gives the possibility to configure the docker storage on the VM root filesystem, while the second one gives the possibility to attach a volume of a specified size and configure the docker storage to use it. Select the one you are interested in and follow the corresponding sections below, in order to understand what parameters need to be set for each use case.

Case 1: docker storage on the VM root filesystem ¶

All deployments have a mandatory field Description that needs to be defined before submitting the deployment.

Fig5: VM configuration parameters

The deployment settings window consists of three tabs:

“General” TAB

Here one needs to fill the following required mandatory fields:

ports: one or more TCP or UDP ports or port ranges can be defined to be open towards the VM running the dockers. They must match the ports that the services inside the docker-compose exposes. Please consult INFN Cloud Rules of participation the “Networking” section in order to see what are the ports that you can specify in this field. If the port you intend to use is in the list of closed-ports, you have to formally request its opening and motivate the request by following the How To: Request to open ports on deployed VMs Also consider that SSH port (22) is already bound to the VM SSH server and thus cannot be used.

Important

INFN Cloud has a clearly defined list of open ports (see_reference in the Networking section). The opening of any port that is not present in the above mentioned list must be formally requested through the INFN Cloud ServiceDesk.

Fig6: Adding new ports

Flavor: resources needed in terms of CPUs and RAM for the new VM.

Fig7: Flavor selection

Run a docker-compose file: start or not a docker container (Default value is yes).

Fig8: Run or not the containers

“Services” TAB

environment_variables: variables to be made available to the docker container at runtime, to be specified on the form of “key:value”. Multiple variables can be specified using the “ADD” button.

Fig9: environment variables definition

docker_compose_file_url: URL from which of the docker compose file to deploy will be downloaded. An example docker-compose file is available here.

Fig10: Docker-compose file URL

project_name: name of the project. This name will be used to create a folder under /opt to store the docker compose file.

Fig11: project name

“Advanced” TAB

Some advanced parameters can be configured here:

Scheduling: set automatic (recommended) or manual (perform a direct submission towards one of the providers available) scheduling

Creation timeout (minutes): amount of time to wait until the deployment should be considered failed

Failure policy: delete, or not, the deployment in case of failure

E-mail: send, or not, a confirmation email when deployment is complete

Fig12: Advanced Tab

After configuring all the parameters proceed with “Continue” and then “Submit” your deployment.

Case 2: docker storage on an external volume attached to the VM ¶

If you requested an external volume (2nd option shown in Fig4), in the “General” tab will be shown an option to select the additional storage size. The external volume will be mounted on the /var/lib/docker instead of the root directory of the VM hosting docker.

Fig13: Additional storage definition

Step 3 - Submitting the Docker-compose deployment ¶

After submitting your application, you are redirected to the list of your deployments where you can follow the evolution of the new deployment.

Step 4 - Access your application ¶

On successful completion (“CREATE_COMPLETE”), you can check your deployment outputs by clicking on the “Details” button and then on the “Output values” Tab.

Use the reported IP address (see figure below) and the ports you defined at submission time to connect to the services you deployed. In order to check the status of the containers use “sudo”.

In case you used the docker-demo example, that installs a Worpress service with a MaridDB backend, the link to use in order to connect to the frontend is https://wp.<node_ip>.myip.cloud.infn.it, where <node_ip> is the value published in the Output details tab.