General Concepts

The main Docker concepts are:

• Master - a Docker host with a Docker manager (swarm) that performs Docker cluster health check, load balancing on containers creation, and collects information on existing images, containers, configuration, statuses etc.
• Node - A VM that plays the role of a base for containers. A Node VM is created by Orchestrator on Docker Service activation
• Container - A node-hosted resource that uses a part of node capacities and can be used as a typical virtual server.
• Container Image - An image stored on the node and used for containers creation
• Docker Registry - a repository service that allows you 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.).

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-container	or2dc	Manipulates Docker containers
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 start the Docker 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 (to stop the service, use --deactivate and -i node_instance_id). 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.

If you need a new node to be added to your Docker cluster, just repeat the or2-manage-service command.

To stop the service, use --deactivate and -i node_instance_id to deactivate nodes one by one, with the Docker Master being deactivated the last.

Working with Containers

The node plays a role of a base for containers that use the node resources but remain independent VMs. To run and terminate the containers, the or2-docker-container (or2dc) command is used.

To run a new container, call the or2dc command with the following parameters:

or2dc -p project -r region -a run -i image_id -cn cluster_name

Here, the -a parameter specifies the action to be performed (run), and -i parameter specifies the container image to be used.

Docker manager will automatically select the node with the lowest load and run the container there.

To see the list of available images, run the or2di command with the -a describe flag:

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

While running a new container, you can specify an entry point command by setting it in the --cmd parameter:

or2dc -p project -r region -a run -i image_id --cmd "/bin/bash" -cn clustser_name

To stop or start a container, call the or2dc command with the following parameters:

or2dc -p project -r region -a stop[or start] -c container_name -cn cluster_name

The stop command shuts down the container and releases some of the resources occupied by it. The start command re-launches the stopped container.

To remove a container, call the or2dc command with the following parameters:

or2dc -p project -r region -a terminate -c container_name -cn cluster_name

Here, the -a parameter specifies the action to be performed (terminate) and -c specifies the container name or ID.

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.

EPAM-DKR Region

In addition to other virtualization regions available in EPAM Cloud, there is also a dedicated Docker region, EPAM-DKR. This region is based on OpenStack, is designed specifically for Docker clusters management, and has some specifics:

• The region is restricted for running services and resources other than those related to the Docker service
• This region supports Docker 1.9 and Docker Swarm 1.0.0
• Each Docker Service instance is hosted on a separate hardware server
• Only the Large shape is available for Docker instances
• In EPAM-DKR region, Docker VMs are run under KVM and use CoreOS guest operating system.

VMs in the EPAM-DKR region are billed for electricity consumption only at the rate of $33 per month.

Docker service in EPAM-DKR region is manipulated in the same way as in any other region. For example, to start the service, run:

or2ms -p project -r EPAM-DKR -s docker -a -c cluster_name

Please note, that currently more than one cluster becomes available for each project in any region. Thus, Docker-related commands now require -c/--cluster-name parameter to be specified. For more details on Docker service manipulations, please refer to EPAM Cloud Services Guide.

There is some specifics in Docker service performance:

• Login to Docker VMs can be performed only with SSH key and 'core' user
• Docker commands can be performed either via Docker toolset or after login to any node via SSH
• Each node in Docker Swarm cluster is a master
• Swarm API endpoint can be reached at any_cluster_ip_address:4000. For example:

docker -H hostname:4000 --tlsverify --tlscacert=/etc/docker/ca.crt --tlscert=/etc/docker/host.crt --tlskey=/etc/docker/host.key info

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 Open vSwitch technology used to provide software-defined networks. For EPAM-DKR region, the same solution is implemented using the flannel technology 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: Ubuntu14.04_64-bit

Therefore, the approximate monthly cost of a Docker Server usage in case of 100% and 24/7 load is about $58.59 in EPAM-BY1 region (as to 11/09/2015). 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.