docker-lock

About

docker-lock is a cli tool that automates managing image digests by tracking them in a separate Lockfile (think package-lock.json or Pipfile.lock). With docker-lock, you can refer to images in Dockerfiles or docker-compose files by mutable tags (as in python:3.6) yet receive the same benefits as if you had specified immutable digests (as in python:3.6@sha256:25a189a536ae4d7c77dd5d0929da73057b85555d6b6f8a66bfbcc1a7a7de094b).

Note: If you are unsure about the differences between tags and digests, refer to this quick summary.

docker-lock ships with 3 commands that take you from development to production:

• docker lock generate finds base images in your Dockerfiles and docker-compose files and generates a Lockfile containing digests that correspond to their tags.
• docker lock verify lets you know if there are more recent digests than those last recorded in the Lockfile.
• docker lock rewrite rewrites Dockerfiles and docker-compose files to include digests.

docker-lock ships with support for Docker Hub, Azure Container Registry, internal registries, and a variety of other registries. If your registry is not supported out of the box, do not worry. docker-lock was designed to be easily extensible to any container registry.

docker-lock is most commonly used as a cli-plugin for docker so lock can be used as subcommand of docker as in docker lock. However, docker-lock does not require docker at all. Instead, it can be called manually as in docker-lock lock. This is especially convenient if the proper version of docker is unavailable or you would prefer to use another container technology such as podman.

Demo

Consider a project with a multi-stage build Dockerfile at its root:

FROM ubuntu AS base
# ...
FROM mperel/log:v1
# ...
FROM python:3.6
# ...

Running docker lock generate from the root queries each images' registry to produce a Lockfile, docker-lock.json.

Note that the Lockfile records image digests so you do not have to manually specify them.

Running docker lock verify ensures that the image digests are the same as those on the registry for the same tags.

Now, assume that a change to mperel/log:v1 has been pushed to the registry.

Running docker lock verify shows that the image digest in the Lockfile is out-of-date because it differs from the newer image's digest on the registry.

While developing, it can be useful to generate a Lockfile, commit it to source control, and verify it periodically (for instance on PR merges). In this way, developers can be notified when images change, and if a bug related to a change in an image crops up, it will be easy to identify.

Finally, lets assume the Dockerfile is ready to be built and shared.

Running docker lock rewrite will add digests from the Lockfile to all of the images.

At this point, the Dockerfile will contain all of the digest information from the Lockfile, so it will always maintain the same, known behavior in the future.

Install

docker-lock can be run as a

• cli-plugin for docker
• standalone executable without docker
• prebuilt image from Dockerhub

Cli-plugin

Ensure docker cli version >= 19.03 is installed by running docker --version.

Linux / Mac

$ mkdir -p ~/.docker/cli-plugins
$ curl -fsSL "https://github.com/safe-waters/docker-lock/releases/download/v${VERSION}/docker-lock_${VERSION}_${OS}_${ARCH}.tar.gz" | tar -xz -C "${HOME}/.docker/cli-plugins"
$ chmod +x "${HOME}/.docker/cli-plugins/docker-lock"

Windows

• Create the folder %USERPROFILE%\.docker\cli-plugins
• Download the Windows release from the releases page.
• Unzip the release.
• Move docker-lock.exe into %USERPROFILE%\.docker\cli-plugins

Standalone tool

• Follow the same instructions as in the cli-plugin section except place the docker-lock executable in your PATH.
• To use docker-lock, replace any docker command such as docker lock with the name of the executable, docker-lock, as in docker-lock lock.
• To verify that docker-lock was installed, run:

$ docker-lock lock --help

Docker image

• docker-lock can be run in a docker container, as below. If you leave off the ${VERSION} tag, you will use the latest, nightly build from the master branch.

Note: If your host machine uses a credential helper such as osxkeychain, wincred, or pass, the credentials will not be available to the container even if you pass in your docker config.

Linux / Mac

• Without your docker config:

$ docker run -v "${PWD}":/run safewaters/docker-lock:${VERSION} [commands]

• With your docker config:

$ docker run -v "${HOME}/.docker/config.json":/.docker/config.json:ro -v "${PWD}":/run safewaters/docker-lock:${VERSION} [commands]

Windows

• Without your docker config:

$ docker run -v "%cd%":/run safewaters/docker-lock:${VERSION} [commands]

• With your docker config:

$ docker run -v "%USERPROFILE%\.docker\config.json":/.docker/config.json:ro -v "%cd%":/run safewaters/docker-lock:${VERSION} [commands]

Use

Command line flags

docker-lock supports a variety of command line flags to customize behavior.

For instance, by default, docker-lock looks for files named Dockerfile, docker-compose.yaml, and docker-compose.yml in the directory from which the command is run. However, you may want docker-lock to find all Dockerfiles in your project.

To do so, you could specify the command line flag, --dockerfile-recursive, to the generate command as in:

$ docker lock generate --dockerfile-recursive

To see available command line flags, run commands with --help. For instance:

$ docker lock --help
$ docker lock generate --help
$ docker lock verify --help
$ docker lock rewrite --help
$ docker lock version --help

Configuration File

Instead of specifying command line flags, you can specify flags in a configuration file, .docker-lock.yml, in the directory from which the command will be run. The root of this repo has an example, .docker-lock.yml.example.

Registries

docker-lock can use credentials from ${HOME}/.docker/config.json to retrieve digests from private repositories. It supports credential helpers such as wincred, osxkeychain, and pass, so it should work in most cases.

As a fallback, you can specify auth credentials as environment variables.

Dockerhub

Login:

$ docker login --username "${DOCKERHUB_USERNAME}" --password "${DOCKERHUB_PASSWORD}"

Run docker-lock:

$ docker lock generate

If this fails, specify credentials in a .env file in the directory from which the command will be run (this location can also be specified with the flag --env-file):

DOCKER_USERNAME=<your docker username>
DOCKER_PASSWORD=<your docker password>

or export those same variables:

$ export DOCKER_USERNAME=<your docker username>
$ export DOCKER_PASSWORD=<your docker password>

Run docker-lock:

$ docker lock generate

Azure Container Registry

Login:

$ docker login --username "${ACR_USERNAME}" --password "${ACR_PASSWORD}" "${ACR_REGISTRY_NAME}.azurecr.io"

Note: az acr login is not yet supported

Either specify the ACR_REGISTRY_NAME in a .env file or as an exported environment variable:

ACR_REGISTRY_NAME=<your registry name>

or

$ export ACR_REGISTRY_NAME=<your registry name>

Run docker-lock:

$ docker lock generate

If this fails, specify your credentials in a .env file or as exported environment variables, as in the Dockerhub example.

Other registries

Currently, docker-lock also supports Microsoft Container Registry and the Elastic Search registry. These will just work -- no extra configuration is required.

If you would like to add support for your own registry, see Bring Your Own Registry.

If you would like to use an internal registry, see Using Internal Registries.

Contributing

Development Environment

A development container based on ubuntu:bionic has been provided, so ensure docker is installed and the docker daemon is running.

• Open the project in VSCode.
• Install VSCode's Remote Development Extension - Containers.
• In the command palette (ctrl+shift+p on Windows/Linux, command+shift+p on Mac), type "Reopen in Container".
• In the command palette type: "Go: Install/Update Tools" and select all.
• When all tools are finished installing, in the command palette type: "Developer: Reload Window".
• The docker daemon is mapped from the host into the dev container, so you can use docker and docker-compose commands from within the container as if they were run on the host.

Build From Source

From the root of the project:

$ go build ./cmd/docker-lock

If on Mac or Linux, make the output binary executable:

$ chmod +x docker-lock

Finally, move the binary to the cli-plugins folder or add it to your PATH, as described in the installation section.

If you would like to cross-compile for another operating system or architecture, from the root of the project, run:

$ CGO_ENABLED=0 GOOS=<your os> GOARCH=<your arch> go build ./cmd/docker-lock

Code Quality and Correctness

Unit tests, integration tests, and linting run in the CI pipeline on pull requests. Locally, you can run quality checks for everything except for integration tests.

• To format your code: ./scripts/format.sh
• To lint your code: ./scripts/lint.sh
• To run unit tests: ./scripts/unittest.sh
• To generate a coverage report: ./scripts/coverage.sh
• To view the coverage report on your browser, open a console, but not in docker, run:

$ go tool cover -html=coverage.out

Tutorials

• Tags Vs. Digests