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.

2028

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.

2008

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.

2018

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.

2002

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.

For more information and helpful tips on managing your CI/CD, please review our Ebook on CI/CD with MedStack Control.

📘

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.

821

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.

2022

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.
1970 2020
  1. In the service details page, click the Update button to edit the service configuration.
2028
  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.

FieldDescription
NameThe name for the service in the Docker network. Services can communicate internally using their name.
ImageThe 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
ReplicasThe 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.

FieldDescription
DomainThe domain at which service will serve requests. Multiple domains are supported using comma separated values, e.g., app1.test.com,app2.test.com
Internal portThe 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.

1060

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.

1140

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.

2030

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.

1148

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.

2016

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.

1346

The physical storage state data will exist on the node where the first container was deployed.

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.

2022

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.