Deploying with Docker Containers

Introduction

Running ScaleOut StateServer in a containerized environment allows for the reliable and scalable deployment of VM-based environments, but with reduced process and management overhead. ScaleOut StateServer supports deployment within a Docker-based container environment starting with version 5.6. Usage of ScaleOut StateServer in containerized environment is licensed identically to an on-premise bare metal or virtual environment and requires a purchase of a valid ScaleOut StateServer license.

Terminology

The following terms defined by Docker are used in this help file and defined here for your convenience:

  • Container: A container is a runtime instance of a docker image. A Docker container consists of: a Docker image, an execution environment, and a standard set of instructions.
  • Docker Hub: The Docker Hub is a cloud-based service that acts as a centralized resource for working with Docker and its components. It provides the following services: Docker image hosting, user authentication, automated image builds and work-flow tools such as build triggers and web hooks, and integration with GitHub and Bitbucket.
  • Image: Docker images are the basis of containers. An Image is an ordered collection of root filesystem changes and the corresponding execution parameters for use within a container runtime. An image typically contains a union of layered filesystems stacked on top of each other. An image does not have state and it never changes.
  • Repository: A repository is a set of Docker images. A repository can be shared by pushing it to a registry server. The different images in the repository can be labeled using tags.
  • Tag: A tag is a label applied to a Docker image in a repository. Tags are how various images in a repository are distinguished from each other.
  • Virtual machine: A virtual machine is a program that emulates a complete computer and imitates dedicated hardware. It shares physical hardware resources with other users but isolates the operating system. The end user has the same experience on a Virtual Machine as they would have on dedicated hardware. Compared to containers, a virtual machine is heavier to run, provides more isolation, gets its own set of resources and does minimal sharing.
  • Volume: A volume is a specially-designated directory within one or more containers that bypasses the Union File System. Volumes are designed to persist data, independent of the container’s life cycle. Docker therefore never automatically delete volumes when you remove a container, nor will it “garbage collect” volumes that are no longer referenced by a container.

Prerequisites

ScaleOut StateServer is best run as a single container instance per container host to avoid network conflicts and to maintain high availability. Deploying more than one ScaleOut StateServer container instance requires as many container hosts as container instances, and also requires that all container hosts are connected on a single network that allows each container host to be able to communicate to the other container hosts.

Container Networking

By default, Docker launches containers into a locally-isolated bridge network which is only accessible from/by other containers on the same host and the container host itself. For a multi-host store, host networking mode is required (i.e., the container shares the same network subnet as its container host).

Managing Docker Containers Using the Docker Command-Line

ScaleOut StateServer is published to the public Docker Hub repository in the “scaleout” namespace. The Docker Hub repository is the default repository in most environments, so it is sufficient to pull the “scaleout/soss” image. For non-default Docker environments, follow the instructions for configuring a new repository for your environment to add https://hub.docker.com/r/scaleout/soss/ image location. In addition to the latest published version of ScaleOut StateServer available under the “latest” (default) tag, each public release is tagged in MAJOR.MINOR.REVISION-BUILD format (e.g., 5.6.0-315).

Configuration Parameters

Example (Bridge networking mode): Start a new Docker container instance in the background, using the default Docker network, and expose all SOSS ports (including the REST APIs) explicitly to the host. The ScaleOut host will have an IP address internal to the default Docker network:

docker run --detach --publish 2720:2720 --publish 2720:2720/udp --publish 2721:2721 --publish 2722:2722 --publish 2723:2723 --publish 2724:2724 --publish 4000:4000 --publish 4001:4001 scaleout/soss

Note

Ports exposed to the Docker host must match the internal SOSS ports exactly. Mapping a container port to a mismatched host port is not currently supported.

Example (Host networking mode): Start a new Docker container instance in the background using the host network, and expose all SOSS ports (including the REST APIs) explicitly. The ScaleOut host will inherit the host’s IP address(es):

docker run --detach --net=host scaleout/soss

Volumes

The following volumes are automatically mapped from the container to the Docker host’s filesystem such that its contents are shared between the container and the container host:

  • /var/log/soss: The /var/log/soss volume mountpoint contains important log files useful to the ScaleOut Software Support Team if a support incident occurs.

Ports

The following ports are exposed to the Docker host and can optionally be mapped to the Docker host such that all network traffic to the Docker host on the specified port is automatically forwarded to the container:

  • 2720 (TCP & UDP): Exposed mgt_port. See mgt_port in soss_params.txt for more detail.
  • 2721 (TCP): Exposed svr_port. See svr_port in soss_params.txt for more detail.
  • 2722 (TCP): Exposed int_port. See int_port in soss_params.txt for more detail.
  • 2723 (TCP): Exposed secure_mgt_port. See secure_mgt_port in soss_params.txt for more detail.
  • 2724 (TCP): Exposed secure_svr_port. See secure_svr_port in soss_params.txt for more detail.
  • 4001 (TCP): Exposed TCP port for the ScaleOut StateServer REST API Service. See the REST API service documentation for more details.

Note

The default service ports in a Docker container environment are 2720-2724, as opposed to the 720-724 of a standard installation. This allows the Docker container to run without privileged access.