Improve UX of run-image-mirrors

[jromero]

Description

This is a loaded issue but in general there are a few issues we've heard from run-image-mirrors feature:

1. It's obscure: It's not clear why certain images were chosen based on the output
2. There is no option to ignore mirrors
3. It's not well documented: There is no clear documentation on why and how to use run-image-mirrors

Proposed solution

1. Change the wording to be more explicit and provide a link to docs when a mirror is selected.
2. A new flag to build: --ignore-mirrors
3. Document:
   • How run image mirrors work? app developer guide

Describe alternatives you've considered

Additional context

• This feature should be documented somewhere: see proposed solution

[dfreilich]

Looking into this - with regards to point 3 (it not being well documented), there is documentation here, though it's in an obscure location. Is there something specific that should be added, to spruce it up?

[dfreilich]

Looking into this, I see that there are a few different elements in play here:

1. A builder defines a run image, and a list of mirrors
2. A user can explicitly add a mirror for a specific run-image by running pack set-run-image-mirrors
3. When a user runs pack build <app>, we first look for a run image that is on the same registry as the image we are building (so if a person just says app, we will look for a run-image-mirror for docker, whereas if a user says gcr.io/app, we will look for a mirror for gcr.io), and if no mirrors are on the same registry, we pick another mirror (either the first mirror in the .pack/config.toml, or the run-image for the builder)

With that in mind, how should --ignore-mirrors work? Should it ignore all mirrors (both 1 and 2), and just pick the default run-image on the builder? Should it ignore the config.toml mirrors, but respect the builder's run-image-mirrors (assuming one of them matches the registry of the image)? Or should we do something else entirely?

cc @ryanmoran (feedback on what you'd like to see/what you think makes sense would be fantastic)

[ryanmoran]

@dfreilich I think that the confusing part is the lever by which a user influences the run-image that is picked. It is surprising that the name of the image being built is that lever. Instead of making that slightly more confusing with a --ignore-mirrors flag, I would propose adding a set-default-run-image command at the top-level. This is symmetrical to the existing set-default-builder command. It also aligns with the pack build command flags --builder and --run-image. This means the user can override a run-image at the pack build level and also globally, just like they can for builders.

[jromero]

Relevant conversation over slack:

[dfreilich]

Clarifying the discussion on Slack, this issue is to rework the current run-image selection logic so that:

• with --publish (a.k.a non-daemon) → default to using the run-image mirror in the registry you are publishing the image to
• local (a.k.a daemon case) → defaults to using the run-image mirror in the same registry (colocated) as the builder
• I assume in all cases, if you pass in pack build --run-image it should use that run-image/mirror

And preference for run image would be:

• --run-image flag
• default run image mirror, as discussed in the --publish/daemon cases above
• mirrors set using pack set-run-image-mirrors
• mirrors defined on the builder