Description

This is a bit of a combination of #10693 and #13331 (and was discussed briefly during the maintainer meeting today with @thaJeztah and @cpuguy83, where we determined that we ought to have a new, clean proposal).

The TL;DR of the problem is that currently, the Docker CLI will automatically perform a docker pull if the image does not exist, and will not ever perform a pull if the specified image does exist. This is especially irritating because docker build has a --pull flag which will always-pull, and docker service (and friends) will do digest-resolution, which results in the same general effect as doing a pull-before-run (although in a cluster-wide deterministic way).

Use Cases

We discussed a few use cases, and in the context of docker run, there are three main use cases that we feel would be useful to accommodate:

1. pull if missing (current behavior, likely what users expect at this point, and necessary for backwards compatibility anyhow)
2. do not pull (useful for systems where "pulling" is something that administrators often want tight control over to ensure they don't ever run an image from an unexpected source, or as an atomic "run-if-available-but-not-otherwise" which is complicated to get right without something like this)
3. always pull (just like service update, etc -- usefulness here speaks for itself)

Proposed Solution

What we discussed is a new --pull flag on docker run, but with a tri-state instead of a simple boolean like docker build's (perhaps choosing a new name so that docker build can grow the new flag and eventually phase out --pull as well?):

1. --pull=missing
2. --pull=never
3. --pull=always

Since this pulling behavior isn't currently part of the API, this should be reasonably simple to implement, and would be a CLI-only feature (just like the existing pulling behavior is).

There is some precedent for this with docker stack deploy's --resolve-image flag, which is one of always, changed, or never. We also discussed the possibility of doing digest resolution during docker run (as docker service does), but determined that it's likely going to be too big of a surprise for users to take that leap as well (since then the digest ends up in the container metadata, where users are likely already fairly used to doing things like docker run some-image:some-version and then docker ps | grep some-image:some-version, or similar).

Picture of a Cute Animal