General Concepts

The main Docker concepts are:

• Node - a VM that plays a role of a base for containers. A Node VM is created by Orchestrator on Docker Service activation.
• Master node (manager) - a Docker Engine host that handles cluster management tasks such as maintaining cluster state, scheduling services and serving swarm mode HTTP API endpoints.
• Worker Node - is a Docker Engine host that executes containers.
• Container - is a running instance of an image. It can be created, started, stopped, moved or deleted using API or CLI. It is possible to connect a container to one or more networks, attach storage to it, or even create a new image based on its current state.
• Container Image - is a read-only template with instructions to create a Docker container.
• Volume - a container directory mapped to a host directory and used to store and share data.
• Docker Registry - a repository service that allows to share VM images between nodes. Registry is hosted on a separate VM that is used as a storage for container images.
• Repository - an entity within a registry, in which the images are grouped. Typically, repository names are taken according to the OS family used on the images that will be stored in this or that repository (e.g., CentOS).
• Tag - images in repositories are referenced by tags, which are typically given according to image OS version (e.g., 6, 7, etc.).
• Service - the definition of tasks to execute on the manager or worker nodes. It is the central structure of the swarm system and the primary root of user interaction with the swarm.

To find out more details on Docker as a product, please visit the Official Docker Web-site.

Related CLI Commands

The table below provides the list of service-related commands and their descriptions:

Command	Short Command	Description
or2-manage-service ... -s docker -a	or2ms	Starts the service in the specified project and region
or2-manage-service ... -s docker-registry -a	or2ms	Starts a Docker Registry in the specified project and region
or2-docker-service	or2ds	Describes,runs,deletes and updates Docker services
or2-docker-volume	or2dv	Manipulates Docker volumes
or2-docker-image	or2di	Manipulates images available for containers creation
or2-describe-docker	or2dd	Gives the list of existing Docker elements and their details
or2-docker-registry-image	or2dri	Manipulates images in a registry

Further on this page, you can find the examples of the commands usage for Docker Service manipulation.

As Docker uses multiple clusters, all Docker-related commands should specify the cluster name as the -c or -cn parameter.

Starting the Docker Service

To activate Docker as EPAM Cloud platform service, use the or2-manage-service (or2ms) command with the following flags:

or2ms -p project -r region -s docker --activate -c cluster_name

Here, the -s parameter specifies the name of the service to manage (docker), and the --activate parameter indicates that the service should be activated. You can also use the --shape parameter to set a non-default shape for the new node.

The command runs a Maestro Stack that creates and configures a Docker Master VM.

To add additional node to your cluster just repeat the or2-manage-service (or2ms) command. Every next node activated in your cluster will be configured as Worker node.

To stop the service, use the or2-manage-service (or2ms) command and specify --deactivate and -i node_instance_id parameters.

If you have more than one node, they will be deactivated one by one, with the Docker Master being deactivated the last.

By default, Docker nodes are MEDIUM-shaped VM with Ubuntu 18.04 operating system. If needed, you can use the --shape parameter with the or2-manage-service command to run a node with a non-default shape.

Deployment and maintenance of an application

To deploy an application image when Docker Engine is in swarm mode, you need to create a service.

To deploy an application image when Docker Engine is in swarm mode, you need to create a service.

To create a service, specify which container image to use, the port where the swarm makes the service available outside the swarm and the number of replicas of the image to run in the swarm.

To run a new service, execute or2-docker-service (or2ds) command with the following parameters:

or2ds -p project -r region -cn cluster_name -a run -s service_name -i image

Here, the -a/--action parameter specifies the action to be performed (run), and -i/--image parameter specifies the container image to be used, and -s/--service stands for the service name.

When the service is deployed to the swarm, the swarm manager accepts your service definition as the desired state for the service.

With the next step the swarm manager schedules the service on nodes in the swarm as one or more replica tasks. Docker manager will automatically select the node with the lowest load and run the task there.

There are two types of service deployments: replicated and global. The replicated service deployment is used by default.

To use replicated service, specify the number of identical tasks you want to run. For example, to run service in replicated mode with 4 replicas, invoke the or2-docker-service (or2ds) command with the following parameters:

or2ds -p project -r region -cn cluster_name -a run -s service_name -i image -m replicated -n 4

A global service is a service that runs one task on every node. To run service in global mode, invoke the or2-docker-service (or2ds) command with the following parameters:

or2ds -p project -r region -cn cluster_name -a run -s service_name -i image -m global

To publish service’s ports externally to the swarm, use -t flag for TCP and -u flag for UPD protocols.

or2ds -p project -r region -cn cluster_name -a run -s service_name -i image -t published_port:service_port

To see the list of services, run the or2-docker-service (or2ds) command with -a/--action describe flag:

or2ds -p project -r region -cn cluster_name -a describe

To describe one service, add the -s/--service flag to the previous command:

or2ds -p project -r region -cn cluster_name -a describe -s service

Service name or service id can be used as service identifier.

You can change the configuration of an existing service specifying -a/--action update flag:

or2ds -p project -r region -cn cluster_name -a update -s service -i new_image -v version

Here, the version parameter represents the version number of the service object being updated. This parameter should be specified to avoid conflicting writes. The version number should be the value as currently set on the service before the update.

When you update a service, Docker stops its containers and restarts them with the new configuration.

To remove a service, run the or2-docker-service (or2ds) command with -a/--action delete flag:

or2ds -p project -r region -cn cluster_name -a delete -s service

Docker Volumes

When a container is used, changes to its data are not stored and may be lost if the container is deleted. Running a container from an image will not include any modified data.

In order to save the data and share it between the Docker containers, Docker Swarm volumes are used. A volume is a directory within a container mapped to a directory on a host. The data is stored in the volume and can be used later.

Volume management is performed with the or2-docker-volume (or2dv) command.

To create a Docker volume, run the or2dv command with the following parameters:

or2dv -p project -r region -a create -cn cluster_name -v volume

To view the list of all volumes available on the Docker Swarm for the specified project and region, run the or2dv command with the following parameters:

or2dv -p project -r region -a describe –cn cluster_name

To delete the specified Docker volume, run the or2dv command with the following parameters:

or2dv -p project -r region -a delete –cn cluster_name –v volume

Docker Swarm volumes are available only in OpenStack-based regions.

Docker volumes are mapped to host directories by means of binding performed during the or2dc command execution. To bind a volume, run the or2dc command with the -v (--volume) parameter.

Docker Info

The or2-describe-docker (or2dd) command allows to get the list of the existing Docker elements and their details.

For example, to get a general overview of the Docker service resources with their details and roles, run:

or2dd -p project -r region -cn cluster_name

To get the details on the Docker cluster, run:

or2dd -p project -r region -t cluster -cn cluster_name

Networking

All Docker containers have access to each other irrespectively of the parent host they are located on. The solution is based on the flannel technology used to provide software-defined networks. The picture below illustrates the overall scheme of connection between hosts within one Docker cluster.

The picture above also shows the basic rule of internal IPs generation. Each container includes a marker of its host switch (Ethernet bridge docker0), and a specific identifier, unique within the host.

Please note that the static part of the address can change during the service further development.

In case you need to get the details on any container, run the or2-docker-container (or2dc) command to find the list of the containers in your Docker cluster, their IDs, status and connection details.

or2dc -p project -r region -cn cluster_name

Sometimes, in troubleshooting and performance analysis purposes, you may need to know more details about the containers than the or2dc command response provides. In this case, you can login to the host VM using your domain credentials, and run the following command:

docker inspect [container_id]

The command will return a full detailed information on the selected container.

The provided solution allows to create up to 40 hosts within one cluster.

Web UI

The Docker service does not have any web UI. All the manipulations are to be performed via CLI.

REST API

Docker manipulations are performed via CLI.

However, there is a REST API you can use for your needs. The connection details can be found in or2dser command response.

Access to the REST API is established via SSL and requires the CA certificate, the host certificate signed by the same CA certificate and the host private key:

/etc/docker/ca.crt /etc/docker/host.crt /etc/docker/host.key

For Docker Swarm, use the following request:

curl --cacert /etc/docker/ca.crt --cert /etc/docker/host.crt --key /etc/docker/host.key https://{INSTANCE_PUBLIC_IP}:4000/info

For Docker host, use the following request:

curl --cacert /etc/docker/ca.crt --cert /etc/docker/host.crt --key /etc/docker/host.key https://{INSTANCE_PUBLIC_IP}:2376/info

Working with Docker Images via Docker Registry

Docker service is provided together with the Docker Registry facilities - a repository service that allows you to share images within the Docker service.

Docker Registry allows you to store images created from Docker Containers, and distribute them between nodes. A Registry is created on a separate VM and is used as a storage for images. Images in a registry are organized as a catalog: they are grouped in repositories and tagged.

The typical Docker images manipulation flow can be described in the following steps:

1. Create a new Docker Registry using the or2-manage-service (or2ms) command with the -s docker-registry parameter.

2. Create a new image from an existing container, using or2-docker-image (or2di) command with -a commit property.

3. Push the new image to an existing Registry, using or2-docker-image (or2di) command with -a push property.

4. Pull the image from the Registry to other nodes, using or2-docker-image (or2di) command with -a pull property

5. To delete a repository with all included images (tags) from a registry, run the or2dri command with the -a delete parameter.

For more details on Docker Registry usage, please see EPAM Cloud Services Guide.

Pricing

The service usage price is defined by the price of the Docker node VM.

The default parameters of a Docker node VM are:

• Shape: MEDIUM
• Image: Ubuntu 18.04

Therefore, the approximate monthly cost of a Docker Server usage in case of 100% and 24/7 load is about $41.53 in EPAM-BY2 region (as to 08/07/2018). The price can vary depending on the region and the shape you select for the Docker node. To get more detailed estimations, please, use our Cost Estimator tool.

References

To find out more details on Docker as a product, please visit the Official Docker Web-Site.

More information on the Docker Service can be found in the EPAM Cloud Services Guide. For detailed description of the Maestro CLI commands used to manage the Docker Service, refer to the Maestro CLI User Guide.

Documentation

Below is a list of documents related to this section. You can find the full list of our documents in the Documentation Storage.