Skip to content

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

Closed

Description

@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.

Activity

  1. tianon commented on Jun 27, 2023

    @tianon
    MemberAuthor

    @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!! 🙇

  2. yosifkit commented on Sep 15, 2023

    @yosifkit
    Member

    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.

  3. rsc commented on Sep 15, 2023

    @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.

  4. neersighted commented on Sep 15, 2023

    @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.

  5. rsc commented on Sep 15, 2023

    @rsc

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

  6. tianon commented on Dec 9, 2023

    @tianon
    MemberAuthor

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

  7. added a commit that references this issue on Aug 14, 2024
  8. added a commit that references this issue on Aug 28, 2024
  9. added a commit that references this issue on Sep 3, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions