Proposal: Add version/format information to Dockerfiles

[thaJeztah]

TL;DR; The Dockerfile format does not contain information about the version of docker used when creating the Dockerfile. (future) versions of Docker will introduce new features in the Dockerfile that can cause older versions of docker to break when using a Dockerfile.

Validating a Dockerfile for 'unknown' or 'outdated' instructions should already be possible, however, adding version-information will lead to greater flexibility on how to treat a Dockferfile in case of changes in the format that are not-so-easy to detect.

Additionally, it will be possible to inform the user which version of docker is required to use the Dockerfile.

Add version information to Dockerfiles

Add a simple version/format to Dockerfiles enable identifying which version of docker / Dockerfile-format was used for the Dockerfile;

DOCKERFILE-VERSION 0.9.1 or DOCKER-VERSION 0.9.1

Should the Dockerfile-format get its own versioning or follow the version of Docker? Use Both?

Not sure what the best approach is here;

Use the same version as Docker

Using the version of docker is convenient; people can simply fill-in the version of docker they're using without having to look-up what the current version of the Docker_file_ is. On the other hand, this may lead to 'faux' warnings that the docker version used is 'too old', while effectively there have been no actual changes in the format.

Use separate versioning for Dockerfiles

Using a separate versioning of Dockerfile-format will require the writer of a Dockerfile to look-up what the current version is. On the plus side, changes in the Dockerfile-format so far have been less frequent than in docker itself; in most cases, the maintainer of a Dockerfile won't have to change the version. Since this approach is more explicit, my vote goes to this one.

Use both

Including both may be considered; The maintainer of a Dockerfile can add this information (just for informational purposes) to indicate what version of docker was used to test the Dockerfile, for example;

DOCKERFILE-VERSION 0.2
DOCKER-VERSION 0.9.1

This would give some insight into what version of Docker the Dockerfile was tested on (and worked)

Possible uses

Validation of Dockerfiles

Quickly check a Dockerfile for possible issues, without actually performing the build. Validation can be performed automatically during build, but also be triggered manually, e.g. via docker build --validate-only. Validation will check the Dockerfile for deprecated and unsupported instructions and/or formatting of arguments.

Informing the user that a newer version of docker is required

Warn the user that a newer version of docker may be required to run the Dockerfile. The minimum required version of docker can be based on the version-information

Treat commands differently or do(n't) support commands

e.g. (just for illustration);

• Dockerfile < 1.0 – don't support COPY
• Dockerfile < 1.0 – ENTRYPOINT accepts both 'string' and 'json'.
• Dockerfile > 2.0 – ENTRYPOINT only accepts 'json'
• Dockerfile < 1.0 – ADD will automatically extract .tar.gz by default. Building it on a 2.0 docker will either automatically add the EXPAND option, or warn the user that the Dockerfile needs updating (linking to a migration-page in the docs)
• Dockerfile > 2.0 – ADD won't automatically extract .tar.gz, unless EXPAND is added
• Dockerfile > 2.0 on a Docker 1.x system – "Error; this Dockerfile requires a newer version of Docker"

(Automatic) migration of Dockerfiles to a newer version

I'm not very fond of 'silently' / 'automagically' converting older commands. Pointing users to the right part of the documentation will be a good starting point. If some (third-party) is willing to, a Dockerfile migration-tool may be possible.

Implementation

Initial implementation;

• Notify users that the Dockerfile is missing a DOCKERFILE-VERSION and that this will be expected in future versions of docker.

Future releases;

• If a Dockerfile does not contain DOCKERFILE-VERSION, warn the user that it's missing and the Dockerfile will be executed it in 'quirks mode / compatibility mode'; Effectively, treat the Dockerfile according to the last format that didn't require DOCKERFILE-VERSION (e.g. docker 0.9.1 ?)
• Automated builds on docker hub should be enforced to include a DOCKERFILE-VERSION

Back-porting

This feature may be especially useful for older versions of docker. Some parts may be back-ported as a minor update to older versions of docker (e.g. 0.9.1 / 0.11-dev) so that users not yet ready to upgrade to newer versions can still be informed that a Dockerfile they're trying to use may be incompatible with their version of docker.

[cyphar]

+1 for this (or something like it) because it will allow for backward compatibility with the Dockerfile interface without making changes impossible.

[thaJeztah]

@cyphar thanks for backing my idea. This is really just an initial idea, some things may not be possible (technically) or unwanted (out of scope), so any thought or suggestion is welcome

[jessfraz]

Hello!
We are no longer accepting patches to the Dockerfile syntax as you can read about here: https://github.com/docker/docker/blob/master/ROADMAP.md#22-dockerfile-syntax

Mainly:

Allowing the Builder to be implemented as a separate utility consuming the Engine's API will open the door for many possibilities, such as offering alternate syntaxes or DSL for existing languages without cluttering the Engine's codebase

Then from there, patches/features like this can be re-thought. Hope you can understand.

[jakirkham]

Any chance we might see this somewhere. If reaping will become part of docker ( #11529 ), it would be nice to remove home built things like tini ( https://github.com/krallin/tini/ ). This is hardly the only use case that I can see for this feature.