Proposal: Change what is being output and pushed

[vladaionescu]

This proposal gives the user more control over what is being output and what is being pushed, and also it helps prevent pushes when they are not intended in monorepo setups.

Background

Today, the following are produced locally at the end of a successful build:

• All SAVE ARTIFACT ... AS LOCAL ..., with local Earthfiles
• All images with tag names (both local and remote Earthfiles)

The following is NOT produced:

• SAVE ARTIFACT ... AS LOCAL ... produced in remote targets

This strategy is meant to optimize for the situations where you actually need things locally, for local development iteration.

If an artifact of a remote target is needed, the user can issue a separate earthly command to output it.

earthly --artifact github.com/foo/bar+buz/artifact ./local/dest

Situations where this strategy falls short

Sometimes images are produced when they are not needed, thus slowing down the build, while other times the user expects remote artifacts to be output, but aren’t.

Examples where images are produced but are not needed:

• A common base image target is mentioned in a FROM to create a microservice. The user is interested only in producing the microservice image, not the base image too.
• A COPY artifact where the artifact happens to be generated by some logic that happens to include SAVE IMAGE (a common base image target, or a microservice that was used in the generation process).

Examples of situations where remote artifacts are expected locally:

• ? (@dchw had a use-case IIRC?)

Pushes background

Today, pushing (when enabled) takes place for all local targets.

This can create situations where a dependency is accidentally pushed when that’s not intended if the user uses a monorepo setup, where each sub-project has its own separate build.

Proposal

We change the logic s.t. output is only produced for the targets invoked either directly (mentioned directly on the command-line) or via calls to BUILD. FROM and COPY (and others e.g. WITH DOCKER --load) do not cause images to be output locally.

So chains like these will produce outputs:

• SAVE
• BUILD -> SAVE
• BUILD -> BUILD -> SAVE
• BUILD -> BUILD -> BUILD -> SAVE
  etc

While chains like these will NOT produce outputs:

• FROM -> SAVE
• COPY -> SAVE
• FROM -> BUILD -> SAVE
• BUILD -> FROM -> SAVE
• BUILD -> BUILD -> COPY -> SAVE
  etc

This ensures that outputs are produced only when they are intended. If the user wants to both output an image and use FROM on it, they can issue

BUILD +target
FROM +target

If a remote target is invoked via BUILD and it has SAVE ARTIFACT ... AS LOCAL ... outputs, then a local directory destination needs to be inferred. If the remote target had been executed in a local context, then that directory would be the directory of the Earthfile. To keep things as consistent as possible, the directory in such case will be

$EARTHLYPATH/github.com/foo/bar/deep/dir/<branch>

Where EARTHLYPATH defaults to ~/earthly/remote. This should match the default dir for a LOCALLY target called remotely)

Push mode

Furthermore, we also change the way pushes are influenced too:

If a target is invoked directly or via BUILD in push mode, then the push mode is passed on when building the target (SAVE IMAGE --push will be pushed, RUN --push will be executed). If a target is only mentioned in a FROM or a COPY, then push mode is not passed on when building that target - thus not triggering pushes for images or RUN --push execution in that case.

This helps with no accidentally triggering push on a dependency when really you’re only trying to push your own project.

Arguments against this we considered

(But still think the positives outweigh the negatives)

• SAVE IMAGE, when used extensively for caching will be less effective. User has to add more BUILDs.
• Generated files (eg go.sum) need to be saved more explicitly. COPY-ing them or FROM-ing is no longer enough. They have to be accompanies by a BUILD too.
• Not executing SAVE * can be surprising to the user. If user has a mental model of executing everything in the target when you FROM it, it can be surprising that SAVE ARTIFACT ... AS LOCAL ... has no effect in that case.
• It's a change that breaks compatibility to the Earthfile format.

Rollout

When this is made available, we should include a feature flag to switch back to the old way, in case anyone upgrading hasn't yet updated their Earthfiles and needs to stick with the old behavior. The feature flag will be removed after a long period of time (e.g. 2 years).

[vladaionescu]

This has been implemented and is now in experimental stage. To enable, use VERSION --referenced-save-only 0.5 at the top of the Earthfile.