Adds flag modifying pull behavior for running and creating containers

[zmackie]

Should close issue moby/moby#34394

- What I did

• This PR adds a new --pull flag to docker run and docker create, following the proposal in (Proposal: add explicit "--pull" flag to "docker run" for controlling image pulling behavior moby/moby#34394)
• Per this proposal, the flag is tristate:
  1. --pull=missing (this is the current behaviour and will be the default.)
  2. --pull=never
  3. --pull=always

- How I did it

• Adds a new config field, createOptions.pull which forks the execution of container.createContainer to either pull the image if it does not exist at all locally --pull=missing, always try and update the image --pull=always, or never try and update the image, only using images that already exist on the local machine --pull=never

Both docker run and docker create can consume this flag.

- How to verify it

• Run docker run and docker create with the flag. Notice that pulls images or does not, depending on the behavior specified in the flag. Running those commands without the flag should maintain the current behavior.

- Description for the changelog

Adds flag modifying pull behavior for running and creating containers (Pull if Missing, Pull Always, Pull Never)

- A picture of a cute animal (not mandatory but encouraged)

[zmackie]

Hey docker folks. This is my first PR to the project (👋 ). It's likely deficient on tests (I especially wasn't sure about any kind of integration or e2e testing that needed to happen. Let me know what ya'll think.

[codecov-io]

Codecov Report

Merging #1498 into master will increase coverage by 0.01%.
The diff coverage is 61.11%.

@@ Coverage Diff @@## master #1498 +/- ##
==========================================
+ Coverage 56.75% 56.77% +0.01% 
==========================================
Files 309 309 Lines 21658 21668 +10 ==========================================
+ Hits 12292 12301 +9 + Misses 8469 8468 -1 - Partials 897 899 +2

[lanoxx]

Nice work. I hope the docker folks will merge this.

[GordonTheTurtle]

Please sign your commits following these rules:
https://github.com/moby/moby/blob/master/CONTRIBUTING.md#sign-your-work
The easiest way to do this is to amend the last commit:

$ git clone -b "34394-run-pull-flag" git@github.com:Zanadar/cli.git somewhere
$ cd somewhere
$ git rebase -i HEAD~842354135168editor openschange each 'pick' to 'edit'save the file and quit
$ git commit --amend -s --no-edit
$ git rebase --continue # and repeat the amend for each commit
$ git push -f

Amending updates the existing PR. You DO NOT need to open a new one.

[svenstaro]

What's the work remaining in order to get this merged?

[zmackie]

AFAIK nothing (but it’s been a while since I opened this so I may have forgotten). Maybe project folks have a different opinion?

[svenstaro]

@GordonTheTurtle could you take a look?

[Morl99]

@Zanadar can you try to increase the test coverage, you are slightly falling short, as per the above Check. I would love to see this feature merged, it is really useful!

[cpuguy83]

Overall this looks good, but I think we can clean up the implementation a bit.

[cpuguy83]

Also keep in mind pull-policy=always only really works for moving tags (such as latest).

[cpuguy83]

Should we error out early if pull=always and the pull failed?

[cpuguy83]

I think we can do this flow and it will clean up quite a bit:

warning, psuedo-code:

if PullImageAlways {
pull()
}
err := createContainer()
if IsNotfound(err) && PullImageMissing {
pull()
}
createContainer()

[zmackie]

Latest commit improves the flow per suggestion, but I'm not sure I've got it quite right...will work at it a bit.

[zmackie]

One thing I'm not certain on is whether we should error in the case that the image is not found locally and the "never pull" option is selected? In which case the flow becomes more like so:

if PullImageAlways {
pull()
}
err := createContainer()
if err {
if IsNotfound(err) && PullImageMissing {
pull()
createContainer()
}
return err // we won't be pulling so just return whatever err we got
}

This also saves trying to create the container twice in the "never pull" case (ie only try to create again in the case where we might pull).

[zmackie]

Also keep in mind pull-policy=always only really works for moving tags (such as latest).

That's probably something that would have to be left to users, though, right? We can't necessarily know whether a tag is moving or not.

[cpuguy83]

Right.

[zmackie]

Should we error out early if pull=always and the pull failed?

This is now handled in the first block: https://github.com/docker/cli/pull/1498/files#diff-477f60a1b609e77fdca573fd8bd7b0c9R210

[zmackie]

@cpuguy83 Okay I cleaned things up a fair bit. I'd love a review pass on the tests and your thoughts on how we handle the error case when "never pull" is selected (see above).

[robbaman]

Is there a reason why the latest version of Docker Desktop on Windows still has version 19.03 of the CLI? According to this thread it seems 19.09 should've been worked on/ready for about 6 months already.

[jcchavezs]

Could the default behaviour be overriden by an env var? I could come up with a PR.

[gitnik]

This is still not available in engine version 19.03.08 in Docker for Mac. Any estimate when this will be available?

[thaJeztah]

Next release (20.xx)

[nickgrealy]

Two (stupid?) questions:

1. Is it possible to have this work with docker pull <someimage> commands too?

e.g. docker pull --pull=always nginx

2. Is it possible to have --pull=newer - to pull the latest version of an image, only if it's newer in the repo?

[FernandoMiguel]

Two (stupid?) questions:

1. Is it possible to have this work with docker pull <someimage> commands too?

e.g. docker pull --pull=always nginx

2. Is it possible to have --pull=newer - to pull the latest version of an image, only if it's newer in the repo?

I don't understand your first one.
The second one is the behaviour of pull.

[robbaman]

Jut got a new version of Docker Desktop for Windows which includes a new version.... 19.03.13

Is 19.09 ever coming to Windows too?