Update build image and add docs (#6983)

.drone/drone.yml

@@ -10,7 +10,7 @@ steps:
   - docker login -u $DOCKER_LOGIN -p $DOCKER_PASSWORD
   - docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
   - docker buildx create --name multiarch --driver docker-container --use
-  - docker buildx build --build-arg="GO_RUNTIME=golang:1.22.1-bullseye" --push --platform
+  - docker buildx build --build-arg="GO_RUNTIME=golang:1.22.5-bullseye" --push --platform
     linux/amd64,linux/arm64 -t grafana/agent-build-image:$IMAGE_TAG ./build-image
   environment:
     DOCKER_LOGIN:
@@ -44,7 +44,7 @@ steps:
   - docker login -u $DOCKER_LOGIN -p $DOCKER_PASSWORD
   - docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
   - docker buildx create --name multiarch --driver docker-container --use
-  - docker buildx build --build-arg="GO_RUNTIME=mcr.microsoft.com/oss/go/microsoft/golang:1.22.1-bullseye"
+  - docker buildx build --build-arg="GO_RUNTIME=mcr.microsoft.com/oss/go/microsoft/golang:1.22.5-bullseye"
     --push --platform linux/amd64,linux/arm64 -t grafana/agent-build-image:$IMAGE_TAG
     ./build-image
   environment:

.drone/pipelines/build_images.jsonnet

@@ -32,7 +32,7 @@ local locals = {
         'docker login -u $DOCKER_LOGIN -p $DOCKER_PASSWORD',
         'docker run --rm --privileged multiarch/qemu-user-static --reset -p yes',
         'docker buildx create --name multiarch --driver docker-container --use',
-        'docker buildx build --build-arg="GO_RUNTIME=golang:1.22.1-bullseye" --push --platform linux/amd64,linux/arm64 -t grafana/agent-build-image:$IMAGE_TAG ./build-image',
+        'docker buildx build --build-arg="GO_RUNTIME=golang:1.22.5-bullseye" --push --platform linux/amd64,linux/arm64 -t grafana/agent-build-image:$IMAGE_TAG ./build-image',
       ],
     }],
     volumes: [{
@@ -55,7 +55,7 @@ local locals = {
         'docker login -u $DOCKER_LOGIN -p $DOCKER_PASSWORD',
         'docker run --rm --privileged multiarch/qemu-user-static --reset -p yes',
         'docker buildx create --name multiarch --driver docker-container --use',
-        'docker buildx build --build-arg="GO_RUNTIME=mcr.microsoft.com/oss/go/microsoft/golang:1.22.1-bullseye" --push --platform linux/amd64,linux/arm64 -t grafana/agent-build-image:$IMAGE_TAG ./build-image',
+        'docker buildx build --build-arg="GO_RUNTIME=mcr.microsoft.com/oss/go/microsoft/golang:1.22.5-bullseye" --push --platform linux/amd64,linux/arm64 -t grafana/agent-build-image:$IMAGE_TAG ./build-image',
       ],
     }],
     volumes: [{

build-image/README.md

@@ -3,25 +3,51 @@
 The Grafana Agent build images are used for CI workflows to manage builds of
 Grafana Agent.
 
-There are two images:
+There are three [images][agent-build-image-dockerhub]:
 
-* `grafana/agent-build-image:X.Y.Z` (for building Linux containers)
-* `grafana/agent-build-image:X.Y.Z-windows` (for building Windows containers)
+* `grafana/agent-build-image:X.Y.Z` (for building targeting Linux, including Linux boringcrypto)
+* `grafana/agent-build-image:X.Y.Z-windows` (for builds targeting Windows)
+* `grafana/agent-build-image:X.Y.Z-boringcrypto` (for building targeting Windows boringcrypto)
 
 (Where `X.Y.Z` is replaced with some semantic version, like 0.14.0).
 
-## Pushing new images
+[agent-build-image-dockerhub]:https://hub.docker.com/repository/docker/grafana/agent-build-image/general
 
-Once a commit is merged to main which updates the build-image Dockerfiles, a
-maintainer must push a tag matching the pattern `build-image/vX.Y.Z` to the
-grafana/agent repo. For example, to create version v0.15.0 of the build images,
-a maintainer would push the tag `build-image/v0.15.0`.
+## Creating new images
+
+### Step 1: Update the main branch
+
+Open a PR to update the build images. 
+See [this][example-pr] pull request for an example.
+You need to change the following files:
+ * `build-image/Dockerfile`
+ * `build-image/windows/Dockerfile`
+ * `.drone/drone.yaml`
+ * `.drone/pipelines/build_images.jsonnet`
+ * `.github/workflows/check-linux-build-image.yml`
+
+[example-pr]:https://github.com/grafana/agent/pull/6650/files
+
+### Step 2: Create a Git tag
+
+After the PR is merged to `main`, a maintainer must push a tag matching the pattern 
+`build-image/vX.Y.Z` to the `grafana/agent` repo. 
+For example, to create version `0.41.0` of the build images,
+a maintainer would push the tag `build-image/v0.41.0`:
+
+```
+git checkout main
+git pull
+git tag -s build-image/v0.41.0
+git push origin build-image/v0.41.0
+```
 
 > **NOTE**: The tag name is expected to be prefixed with `v`, but the pushed
-> images have the v prefix removed.
+> images have the `v` prefix removed.
+
+> **NOTE**: The tag name doesn't have to correspond to an Agent version.
 
 Automation will trigger off of this tag being pushed, building and pushing the
 new build images to Docker Hub.
 
 A follow-up commit to use the newly pushed build images must be made.
-

docs/developer/updating-go.md

@@ -0,0 +1,22 @@
+# Updating Agent to a new Go version
+
+There is more to updating Go than simply updating the `go.mod` file.
+You will need to submit two pull requests:
+
+1. [Create a new build image.][build-image-instructions]
+2. Update Agent to use the new Go version, and the new build image.
+   See [this][example-pr] pull request for an example.
+   At this point you can just search and replace all instances of the old version with the new one.
+   For example, "1.22.1" would be replaced with "1.22.5".
+
+The Go image which is used may sometimes have a name, like "bullseye". 
+The origins of the name are explained in more detail in [Go's DockerHub repository][go-dockerhub]:
+
+> Some of these tags may have names like bookworm or bullseye in them. 
+> These are the suite code names for releases of Debian⁠ and indicate which release the image is based on. 
+> If your image needs to install any additional packages beyond what comes with the image, 
+> you'll likely want to specify one of these explicitly to minimize breakage when there are new releases of Debian.
+
+[build-image-instructions]:../../build-image/README.md
+[go-dockerhub]:https://hub.docker.com/_/golang
+[example-pr]:https://github.com/grafana/agent/pull/6646/files