Add initial "multi-stage" support in bashbrew

[tianon]

This allows bashbrew to properly handle cross-repository and cross-tag dependencies even in the face of multiple FROM instructions or COPY --from=.

This also provides the scaffolding necessary to implement this in scripts using bashbrew cat.

As fallback behavior, the *DockerFrom functions should return the FROM of the last stage in the Dockerfile (which is essentially the FROM of the final image).

Also, the output of bashbrew from is now a space-separated list.

This is the first step towards #3383 -- there's still a lot more shell script work to be done (which is frankly harder to find since we don't get compiler errors when they aren't updated), but this is the first step that makes that work possible to do. 👍

[tianon]

IMO this catch is worth pointing out explicitly here too -- we don't ever have a "local" copy of the context, and instead stream git archive directly to docker build, so even if docker build --target=N were possible to do for a numbered stage, we'd still have an optimization problem implementing it (and I'd love to at least tag named stages that way, but the git archive | docker build optimization makes that a little harder to swallow).

The practical implication of this is that build cache for these untagged stages will still be considered "ripe" by our tooling and thus we will end up spending extra time rebuilding things after each cleaning of "ripe" images on our build servers.

For this reason, I think that for the official images, we should plan to still discourage multi-stage image use unless the gains are clear and/or the final artifacts are reproducible (and thus can avoid unnecessary image updates), and even then encourage use of explicitly named stages so that we can hopefully tag them in the future to help avoid this issue.

[tianon]

For folks affected by the DockerFrom deprecation, in my experience porting my own scripts, this is the most common fix. (There was one place in the docs we needed to switch to .ArchLastStageFrom instead, but it's pretty rare.)

[tianon]

This one has me wondering if we should add an explicit .EnsureGitFetched function, since we use this function in a lot of places to mean that. 😅

(Room for future improvement -- I don't think we should block this on that.)

[yosifkit]

I approve except we first need to have a document that will provide the very limited set on which we would accept a multi-stage build.

---

The general idea is that if it can be reasonably done without multi-stage, it should be (long RUN lines or auto-excluding build dependencies is not a good enough excuse).

[yosifkit]

Initial rough list of allowable images (to help minimize problems due to #5929 (comment) / cache):

1. only has COPY --from=foo:tag ...
   • i.e. image that copies a built binary from another tagged official image
   • it is impossible or close-to-impossible to do within the image
   • there is only one FROM instruction in the Dockerfile
   • examples:
     • nanoserver copying from a windowsservercore-based image
       • rationale: nanoserver doesn't have System.Net.WebClient or Invoke-WebRequest to download things from the internet
     • tomcat:*jre variant that copies tomcat native from respective tomcat:*jdk image
       • rationale: since openjdk is now downloaded from the vanilla openjdk releases (see Move 8 and 11 to consume from https://adoptopenjdk.net/upstream.html openjdk#322), you cannot trivially install jre and jdk at the same time

Maybe:

1. two stage build where one builds a static binary and the other contains it
   • this should only be done if the build dependencies could not be reasonably installed and removed within a single build layer (i.e. the compiler exists in a supported official image but doesn't exist in Debian/Alpine packages)
   • It would be better if the upstream project just had published release binaries that could used instead of compiling in the build image since this will be subject to unknown number of rebuilds when the "ripe" images (and thus the build cache) are cleaned out
2. jlink to create a minimal jre for the specified application? (are there official images that could use this?)

Pitfalls:

• COPY --from doesn't preserve setuid (access permissions) moby/moby#37830 no sticky bits like setuid
• Fix COPY --from with userns and non zero uid/gid files moby/moby#38823 not applicable since we don't build with userns on
• Multi-stage COPY --from should preserve ownership/permissions moby/moby#37123 ownership/permissions preservation, not fixed until 19.03.0
• no ADD --from support to extract tar files

[tianon]

Initial documentation PR up at docker-library/faq#6. 👍 🎉 🍰