proposal: set GOTOOLCHAIN=local (or =path) in our image

[tianon]

Per https://go.dev/doc/toolchain, it might make sense for us to set GOTOOLCHAIN=local (or even GOTOOLCHAIN=path) by default in our images. I'll follow this up with a comment describing more long-form why I think this might be appropriate here, but wanted to get an issue open where it can be discussed properly.

[tianon]

@rsc I really hope you don't mind being pinged for your opinion (or help directing to the right folks for an opinion) on how we can best represent Go here; I've tried to make sure this has enough information for you help guide us without having to be totally well versed in how Go is commonly used in containers (just in case you aren't) ❤️ 😅 🙇

One of our highest goals in maintaining this image is to appropriately represent Go upstream in the way we believe they might represent themselves (https://github.com/docker-library/official-images/tree/78bad2f7ead1688af35d768fa1a23939fff77f89#what-are-official-images, bullet point 5). We're obviously not perfect at this (or balancing this with end user expectations/desires), but we do try very hard to do so unobtrusively.

This has come up most recently in the context of GOTOOLCHAIN (https://go.dev/doc/toolchain), with some users expecting/requesting that we set it explicitly to local in our images for 1.21+, and us hesitating to do so because the default was chosen explicitly and intentionally upstream (after some very long debates on the subject).

We do not want or intend to reopen those debates (and any unproductive comments attempting to do so here will be hidden as off topic), but we do think the way that users interact with this image currently perhaps does warrant a change in that default behavior.

Typically, users of this image will have a Dockerfile which looks something like this:

FROM golang:X.Y
# or
FROM golang:X.Y.Z
# ...
COPY my-code /some/path
RUN go build ...

As you can see, there is usually a very clear user intent that they desire Go version X.Y (or X.Y.Z), and the argument here is that it would be very surprising if a go.mod that contains a newer go X.Y+N were to not error, but rather download a newer toolchain (again, given the very clear user intent in the Dockerfile).

In short, the proposal is that we should set GOTOOLCHAIN=local (or perhaps GOTOOLCHAIN=path so that go get go@xxx still works appropriately and is used correctly, for users who might be mixing and matching multiple Go versions in a single image), but we want to make sure we're doing so in a way that is respectful to the origins of the default choice. ❤️

Any thoughts or opinions you might be willing to share would be deeply appreciated!! 🙇

[yosifkit]

I am in favor of at least setting local but leaning more toward path to force users to know that they need a newer image (or to override the GOTOOLCHAIN that we will set). Auto-upgrading the go toolchain does not make sense for the container images that we have.

[rsc]

It seems to me that it would be best to leave it at the default GOTOOLCHAIN=auto.
The upgrade only happens when the Go toolchain already running is older than what is required,
and if it does happen there will be a download line printed to standard error that will explain what's going on.

If you set GOTOOLCHAIN=local, then in the cases where a download would have happened,
the build will completely fail instead. That seems strictly worse and less helpful.

[neersighted]

I strongly object to GOTOOLCHAIN=auto because it can cause a relatively simple operation (e.g. go env) to take an unexpectedly long time/require network access, introduce a lengthy timeout, etc.

As the base image is rebuilt regularly, a FROM golang:1.y.z expresses a very strong intent to use a 1.y.z toolchain (as opposed to "the base image as it existed when 1.y.z was latest," which is what I am inferring your mental model is). It strikes me as very expected that I would get an error upon encountering a go.mod that requested a newer toolchain, and unexpected that I could (silently from the perspective of many automated usages of containers) download an entire toolchain independent of my intended version as expressed by my FROM line.

Especially in CI/semi-automated environments [scripts] (a large part of the use case for this base image), automatically upgrading the toolchain instead of failing early and informing the user what is wrong severely violates the principle of least surprise for me.

[rsc]

In that case, setting GOTOOLCHAIN=local makes sense.
Setting GOTOOLCHAIN=path does not really sense given that rationale.

[tianon]

Many belated thanks for your time/thoughts, Russ -- it's really appreciated (as is your upstream work) ❤️