Services

Configuring the Docker services that work together to deliver your product.

Overview

Services run as containers in your cluster that are orchestrated by Docker. There are two types of services that are orchestrated in MedStack Control.

  • Managed services
  • Custom services

Types of services

Managed services

MedStack Control's managed services can be added to your Docker environment to leverage preconfigured services that offer important functionality and enforce compliance requirements.

In the product today, MedStack Control's managed service encompasses the load balancer, which is required to make your services available to the open internet.

Custom services

Custom services will encompass all other services you intend on deploying to Docker. You'll create a custom service when looking to deploy a service from a container image you've built or is publicly available. This could include:

  • Container images hosted on a private image registry, which will require registry credentials and added to the Docker configuration.
  • Container images hosted on a public registry.
  • Container images hosted on a public registry marketplace like Docker Hub.

Service information

An overview of the service configuration. You can click the Update button to see and modify the complete service configuration. The replica count indicates the number of containers of the service to spin up.

Service containers

Containers are service instances that run in your cluster. They are the result of successfully configuring a service to operate on your cluster.

You'll learn more about what you can do with containers in the next section of the guide on maintaining your applications.

Tasks / History

The state of containers, from their request to be created through their destruction, is captured in this table. Error messages contain the description for a container creation or runtime failure, and are also available in the logs for containers that have not yet been purged from the Docker environment.

You'll learn more about container logs in the guide on maintaining your applications.

Image update webhooks

When a webhook is called, Docker stops and restarts all service containers for the service which the webhook has been generated. Webhooks can be enabled or disabled, and there can be many webhooks for a single service to be used in different workflows and pipelines if desired.

Formatting a request

A webhook can be triggered by using a HTTP POST request. The body in curly braces is not used, but is added to the request for completion.

// Example 1: POST by default
curl --data `{}` $URL

// Example 2: POST explicit
curl -X POST $URL
// Success
{"warnings": null}

A successful response upon calling the webhook comes from Docker Swarm and reports no warnings.

Webhooks in CI/CD

When a service with the tag latest is started, the latest tag of that image in the registry will be pulled from the registry for deployment. The latest tag is also implied when no image tag is specified in the service configuration.

// Example 1: Private registry on GitLab
registry.gitlab.com/medstack-inc/flask-demo:latest

// Example 2: Docker Hub Marketplace container image
busybox:latest

// Example 3: Docker Hub Marketplace container image
busybox

In a simple CI/CD pipeline, you can use webhooks to stop and start a service after the image has been built and published to the container image registry. This will force Docker on MedStack Control to shut down the service and restart it with the latest image of the service in the registry.

📘

A common deployment pipeline

It's common for teams to set up CI/CD in this way when they use Github for source control and Docker Hub as their container image registry.

There is a Github Action to build and push Docker images that can be used in sequence with a service's webhook to set up a simple deployment pipeline.

Deployment mechanism

The default Swarm configuration for updating services is stop-start. This is the default configuration to mitigate complications that can occur when different versions of the same service are running at the same time.

You can expect the service downtime to elapse the duration of:

  • shutting down the service,
  • downloading the latest image to Docker, and
  • starting the service.

The time required to do this varies for each service.

❗️

In the case of deployment failure

After three failed attempts, the container will not attempt to deploy again. This means that there will be one less replica than configured in the service. To resolve this, update the service with a deployable configuration.

Actions

Create

In the Services tab you can click the New service button to configure and deploy a service.

Select to deploy a managed service or a custom service.

Update

  1. A service can be updated from the service's details page. This can be accessed in a few ways:

    • Click the container icon on the Control cluster overview page.
    • Click the service name in the Services tab for a cluster.
    • Click the View button in the Services tab for a cluster.
  1. In the service details page, click the Update button to edit the service configuration.
  1. Click Save at the bottom of the configuration form to save and roll out the new configuration.

Delete

A service can be deleted from the service's details page or the Services tab.

🚧

Would you rather just pause a service?

Sometimes it's preferable to simply pause a service by stopping its containers while preserving the service configuration in Docker. This can be done by updating the service configuration to have zero replicas.

Configuration

General

The general information about a service.

Field

Description

Name

The name for the service in the Docker network. Services can communicate internally using their name.

Image

The domain and path of the container image in the registry, e.g., registry.gitlab.com/medstack-inc/flask-demo:1.2

You may also deploy public Docker Hub market place container images by specifying the image and tag, e.g., rails:latest

Replicas

The number of containers to deploy of the service.

Advanced options
command -arguments [options]

Clicking advanced options exposes input boxes to issue a command and its arguments to execute at run time.

This overrides the commands executed in the Dockerfile built into the container image.

Domain mapping

The ingress and internal networking information for a service.

Field

Description

Domain

The domain at which service will serve requests. Multiple domains are supported using comma separated values, e.g., app1.test.com,app2.test.com

Internal port

The internal port the Docker container has been configured to listen on. This is often defined in the Dockerfile as the EXPOSE command.

Environment variables

You can add up to 20 environment variables to a service in the form of key-value pairs.

Configs

Configs are created in the Docker configuration and mapped to be used by a service. When a config mapping is created for a service, the config is mounted as a file at a specified path on the container's host node's disk.

You can see in this example in the container shell how the config_db.json file was created at the root directory on the disk.

Secrets

Secrets are created in the Docker configuration and can be exposed to a service. When a secret mapping is created for a service, the secret is mounted as an encrypted file at /var/run/secrets on the container's host node's disk using the filename specified.

You can see in this example in the container shell how the FB_TOKEN.secret file was created at the /var/run/secrets path on the disk.

Volumes

Volumes are created in the Docker configuration and can be mounted to a service. When a volume mapping is created for a service, the volume data is mounted to a specified path on the container's host node's disk.

The physical storage state data will exist on the node where the first container was deployed. This is Docker functionality and will be replaced in the future by persistent volume claims, anticipated late 2020.

You can see in this example in the container shell how the /my-photos path was created at the root directory and mounted the volume data on the disk.

Placement constraints

Placement constraints introduce conditions for a container to determine on which nodes to run. Two common examples of placement constraints are:

  • Labels, e.g. node.labels.{key} == {value} using the == comparator.
  • Labels, e.g. node.role != {role} using the != comparator. Roles can be worker or manager.

To get a better understanding of the types of conditions that can be used, you can read more about how to use placement constraints on the official Docker documentation.

👍

Use placement constraints with stateful services

Because Docker Swarm does not currently support persistent volume claims, we recommend using stringent placement constraints to pin stateful services, such as a cache or database, to specific machines.


What's next

Now that you have services running, you'll need to maintain and prepare them for production.

Did this page help you?