Control what's in production using image digests

The most effective way to control the image deployed to a production service is by using image digests. Unlike tags which are mutable, digests are unique to an image. This means that there can only be one digest for one image.

Using digests

Images built on Docker have a content-addressable identifier called a digest. As long as the input used to generate the image is unchanged, the digest value is predictable. This makes it possible for teams to know exactly which version of a service is deployed to production.

In the Dashboard app

To update or deploy a service image with a digest:

1. Navigate to the service's details page (or create a new service)
2. In the "Image" field, enter the library, image and digest using the @ symbol to specify the image digest

In the API

To update or deploy a service image with a digest:

1. Use the appropriate request type for the /services endpoint
2. In the "image" value, enter the library, image and digest using the @ symbol to specify the image digest

// In a production system using the API request
// Using digests
// PATCH /services/service_id

{
    "image" : "medstackinc/particledemo@sha7243658hgsfduhgj2h7ygsdfg67htj094w7g"
}

The risk of using tags

When tags are used to control which service container images are deployed in production, teams run the risk of unintentionally running different versions of a service at the same time. How can this happen?

Say for example you're using the :latest tag to indicate the latest service production candidate. When you make a push to the container registry, the image tagged :latest on the registry is different that the image tagged :latest running on production.

Usually teams will update production shortly after a production candidate has been tagged :latest, but as teams grow and more developers are building and pushing production candidates, the version of what's deployed as latest and what's in the registry as latest diverges. It can then be difficult to know which branch of code is actually deployed to production at any given moment in time.

Mitigation strategies using tags

One strategy to mitigate disparity between versions of services deployed on production is to deploy tags that are only used by one image. An example of this would be a process change where developers tag an image with the git pull request hash.

// In a production system using the API request
// Using tags named after PR hashes
// PATCH /services/service_id

{
    "image" : "webapp:be724hks"
}