Skip to content

chore: pin example Dockerfiles digests and simplify dynamic module bump workflow #8678

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shahar-h wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore: pin example Dockerfiles digests and simplify dynamic module bump workflow #8678

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/dependabot.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ updates:
directories:
- /tools/docker/envoy-gateway/
- /site
- "/examples/*"
schedule:
interval: weekly
- package-ecosystem: github-actions
Expand Down
4 changes: 2 additions & 2 deletions examples/backend-utilization/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM golang:1.26.1 AS builder
FROM golang:1.26.1@sha256:595c7847cff97c9a9e76f015083c481d26078f961c9c8dca3923132f51fe12f1 AS builder

ARG GO_LDFLAGS=""

Expand All @@ -14,7 +14,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/g
GOARCH=${TARGETARCH} \
go build -o /bin/backend-utilization -ldflags "${GO_LDFLAGS}" .

FROM gcr.io/distroless/static-debian11
FROM gcr.io/distroless/static-debian11@sha256:1dbe426d60caed5d19597532a2d74c8056cd7b1674042b88f7328690b5ead8ed
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/backend-utilization /

Expand Down
10 changes: 3 additions & 7 deletions examples/dynamic-module-test/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,4 @@
# ENVOY_VERSION must match the SDK version in go.mod to ensure ABI compatibility.
# Update both together when changing the target Envoy version.
ARG ENVOY_VERSION=dev

FROM golang:1.26.1 AS builder
FROM golang:1.26.1@sha256:595c7847cff97c9a9e76f015083c481d26078f961c9c8dca3923132f51fe12f1 AS builder

WORKDIR /build
COPY go.mod go.sum ./
Expand All @@ -13,6 +9,6 @@ COPY . ./
RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/go/pkg/mod \
CGO_ENABLED=1 go build -buildmode=c-shared -o /build/libheader_mutation.so .

ARG ENVOY_VERSION
FROM docker.io/envoyproxy/envoy:distroless-${ENVOY_VERSION}
# Envoy image tag and digest are updated by tools/hack/bump-envoy-dynamic-modules.sh during releases.
FROM docker.io/envoyproxy/envoy:distroless-dev@sha256:1679d1bb44c7f90aca4a0f5e33f7c7c5723e96a90b38f9ad5a5b158ed4c95a40
Comment on lines +12 to +13
Copy link
Copy Markdown
Contributor

@jukie jukie Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Won't this be fairly noisy? This will change with every envoy commit

Copy link
Copy Markdown
Contributor

@arkodg arkodg Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

Copy link
Copy Markdown
Contributor

@jukie jukie Apr 6, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we pin here to a specific dev commit and we manually bump like go-control-plane?

We'd still want release branches to target a release envoy version though.

Copy link
Copy Markdown
Contributor Author

@shahar-h shahar-h Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point — the noise concern applies equally to the github.com/envoyproxy/envoy/source/extensions/dynamic_modules Go module in examples/dynamic-module-test/go.mod, which uses a pseudo-version pinned to a commit. However, Dependabot doesn't support updating Go pseudo-versions (see dependabot/dependabot-core#2028), so the Go module is currently stuck on a month-old commit with no automatic updates. Meanwhile, the distroless-dev Docker tag is mutable and always resolves to the latest envoy build, so every image pull gets the newest commit — creating a growing version skew between the Docker image and the Go module.

I see two options:

Option 1: Use envoy per-commit image tags
Switch from distroless-dev to commit-tagged images (e.g. distroless-dev-6f94ab127f45cf93a29da0a740c7e84d466d14fb). This lets us pin both the Go module and the Docker image to the exact same envoy commit. Dependabot won't try to update commit-based tags (they're not semver-comparable), so there's no noise. We can either update both manually as needed, or create a dedicated weekly workflow that bumps both to the latest envoy main commit in a single PR. During releases, the bump script would still override both — the image to a specific release tag (e.g. distroless-v1.37.0) and the Go module to a commit from the corresponding release branch.

Option 2: Keep using distroless-dev tag
Keep the current distroless-dev tag with a digest pin. Dependabot handles weekly digest updates automatically. For the Go module, we'd need a separate workflow to bump the pseudo-version since Dependabot can't do it. The downside is that the Docker image and Go module are updated independently and may point to different envoy commits.

Please share your thoughts.

Note: We should also consider migrating to Renovate, which natively supports both Go pseudo-version updates and tool directive dependency updates (see envoyproxy/gateway#6213 (comment)). That would eliminate the need for a custom workflow entirely, but it's a larger migration that should be evaluated separately.

Copy link
Copy Markdown
Contributor Author

@shahar-h shahar-h Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@arkodg @jukie

COPY --from=builder /build/libheader_mutation.so /usr/local/lib/libheader_mutation.so
3 changes: 1 addition & 2 deletions examples/dynamic-module-test/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@
IMAGE_PREFIX ?= envoyproxy/gateway-
APP_NAME ?= dynamic-module-test
TAG ?= latest
ENVOY_VERSION ?= dev

.PHONY: docker-buildx
docker-buildx:
docker buildx build . --build-arg ENVOY_VERSION=$(ENVOY_VERSION) -t $(IMAGE_PREFIX)$(APP_NAME):$(TAG) --load
docker buildx build . -t $(IMAGE_PREFIX)$(APP_NAME):$(TAG) --load
4 changes: 2 additions & 2 deletions examples/envoy-ext-auth/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM golang:1.26.1 AS builder
FROM golang:1.26.1@sha256:595c7847cff97c9a9e76f015083c481d26078f961c9c8dca3923132f51fe12f1 AS builder

ARG GO_LDFLAGS=""

Expand All @@ -15,7 +15,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/g
go build -o /bin/envoy-ext-auth -ldflags "${GO_LDFLAGS}" .

# Make our production image
FROM gcr.io/distroless/static-debian11:nonroot
FROM gcr.io/distroless/static-debian11:nonroot@sha256:63ebe035fbdd056ed682e6a87b286d07d3f05f12cb46f26b2b44fc10fc4a59ed
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/envoy-ext-auth /

Expand Down
4 changes: 2 additions & 2 deletions examples/grpc-ext-proc/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM golang:1.26.1 AS builder
FROM golang:1.26.1@sha256:595c7847cff97c9a9e76f015083c481d26078f961c9c8dca3923132f51fe12f1 AS builder

ARG GO_LDFLAGS=""

Expand All @@ -15,7 +15,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/g
go build -o /bin/grpc-ext-proc -ldflags "${GO_LDFLAGS}" .

# Need root user for UDS
FROM gcr.io/distroless/static-debian11
FROM gcr.io/distroless/static-debian11@sha256:1dbe426d60caed5d19597532a2d74c8056cd7b1674042b88f7328690b5ead8ed
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/grpc-ext-proc /

Expand Down
4 changes: 2 additions & 2 deletions examples/preserve-case-backend/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM golang:1.26.1 AS builder
FROM golang:1.26.1@sha256:595c7847cff97c9a9e76f015083c481d26078f961c9c8dca3923132f51fe12f1 AS builder

ARG GO_LDFLAGS=""

Expand All @@ -15,7 +15,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/g
go build -o /bin/preserve-case-backend -ldflags "${GO_LDFLAGS}" .

# Need root user for UDS
FROM gcr.io/distroless/static-debian11
FROM gcr.io/distroless/static-debian11@sha256:1dbe426d60caed5d19597532a2d74c8056cd7b1674042b88f7328690b5ead8ed
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/preserve-case-backend /

Expand Down
4 changes: 2 additions & 2 deletions examples/simple-extension-server/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM golang:1.26.1 AS builder
FROM golang:1.26.1@sha256:595c7847cff97c9a9e76f015083c481d26078f961c9c8dca3923132f51fe12f1 AS builder

ARG GO_LDFLAGS=""

Expand All @@ -15,7 +15,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/g
go build -o /bin/simple-extension-server -ldflags "${GO_LDFLAGS}" .

# Need root user for UDS
FROM gcr.io/distroless/static-debian11
FROM gcr.io/distroless/static-debian11@sha256:1dbe426d60caed5d19597532a2d74c8056cd7b1674042b88f7328690b5ead8ed
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/simple-extension-server /

Expand Down
4 changes: 2 additions & 2 deletions examples/static-file-server/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM golang:1.26.1 AS builder
FROM golang:1.26.1@sha256:595c7847cff97c9a9e76f015083c481d26078f961c9c8dca3923132f51fe12f1 AS builder

ARG GO_LDFLAGS=""

Expand All @@ -15,7 +15,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/g
go build -o /bin/static-file-server -ldflags "${GO_LDFLAGS}" .

# Need root user for UDS
FROM gcr.io/distroless/static-debian11
FROM gcr.io/distroless/static-debian11@sha256:1dbe426d60caed5d19597532a2d74c8056cd7b1674042b88f7328690b5ead8ed
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/static-file-server /
COPY files/ files/
Expand Down
2 changes: 1 addition & 1 deletion site/content/en/contributions/RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ export GITHUB_REMOTE=origin
(+v1.8.x only) After updating the Envoy proxy image tag, update the dynamic module SDK and example dependencies:

```shell
make update-dynamic-module-deps ENVOY_VERSION=v${ENVOY_PROXY_VERSION}
make update-dynamic-module-deps
```

10. Sign, commit, and push your changes to your fork.
Expand Down
33 changes: 21 additions & 12 deletions tools/hack/bump-envoy-dynamic-modules.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,16 @@

set -euo pipefail

ENVOY_VERSION="${1:?Usage: $0 <envoy-version, e.g. v1.37.0>}"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
ROOT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"

# Read envoy version from DefaultEnvoyProxyImage in source code.
# On main this is "distroless-dev" (no version), on release branches it's "distroless-vX.Y.Z".
ENVOY_VERSION=$(grep 'DefaultEnvoyProxyImage' "${ROOT_DIR}/api/v1alpha1/shared_types.go" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || true)
if [ -z "${ENVOY_VERSION}" ]; then
echo "No envoy release version found in DefaultEnvoyProxyImage (dev image?) — skipping." >&2
exit 0
fi

# Extract major.minor from version (e.g., v1.37.0 -> 1.37)
MAJOR_MINOR=$(echo "${ENVOY_VERSION}" | sed 's/^v//' | cut -d. -f1,2)
Expand All @@ -26,28 +35,28 @@ echo "Resolved ${ENVOY_VERSION} (release/v${MAJOR_MINOR}) to commit ${COMMIT_SHA
GNU_SED=$(sed --version >/dev/null 2>&1 && echo "yes" || echo "no")

# Find all dynamic module example directories
DYNAMIC_MODULE_DIRS=$(find examples -name "go.mod" \
DYNAMIC_MODULE_DIRS=$(find "${ROOT_DIR}/examples" -name "go.mod" \
-exec grep -l "envoy/source/extensions/dynamic_modules" {} \; \
| xargs -I{} dirname {})

for dir in $DYNAMIC_MODULE_DIRS; do
echo "Updating ${dir}..."

# Update Dockerfile ARG ENVOY_VERSION
# Update Dockerfile envoy image FROM line
if [ -f "${dir}/Dockerfile" ]; then
if [ "$GNU_SED" = "yes" ]; then
sed -i'' "s/^ARG ENVOY_VERSION=.*/ARG ENVOY_VERSION=${ENVOY_VERSION}/" "${dir}/Dockerfile"
else
sed -i '' "s/^ARG ENVOY_VERSION=.*/ARG ENVOY_VERSION=${ENVOY_VERSION}/" "${dir}/Dockerfile"
ENVOY_IMAGE="docker.io/envoyproxy/envoy:distroless-${ENVOY_VERSION}"
ENVOY_DIGEST=$(docker buildx imagetools inspect "${ENVOY_IMAGE}" 2>/dev/null | grep -m1 'Digest:' | awk '{print $2}')
if [ -z "${ENVOY_DIGEST}" ]; then
echo "Error: Could not resolve digest for ${ENVOY_IMAGE}" >&2
exit 1
fi
fi

# Update Makefile ENVOY_VERSION
if [ -f "${dir}/Makefile" ]; then
NEW_FROM="FROM ${ENVOY_IMAGE}@${ENVOY_DIGEST}"

if [ "$GNU_SED" = "yes" ]; then
sed -i'' "s/^ENVOY_VERSION ?=.*/ENVOY_VERSION ?= ${ENVOY_VERSION}/" "${dir}/Makefile"
sed -i'' "s|^FROM docker.io/envoyproxy/envoy:distroless.*|${NEW_FROM}|" "${dir}/Dockerfile"
else
sed -i '' "s/^ENVOY_VERSION ?=.*/ENVOY_VERSION ?= ${ENVOY_VERSION}/" "${dir}/Makefile"
sed -i '' "s|^FROM docker.io/envoyproxy/envoy:distroless.*|${NEW_FROM}|" "${dir}/Dockerfile"
fi
fi

Expand Down
12 changes: 2 additions & 10 deletions tools/make/examples.mk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@ EXAMPLE_APPS := simple-extension-server extension-server envoy-ext-auth grpc-ext
EXAMPLE_IMAGE_PREFIX ?= envoyproxy/gateway-
EXAMPLE_TAG ?= latest

# Extract envoy proxy version from DefaultEnvoyProxyImage (e.g., "distroless-v1.37.0" -> "v1.37.0").
# Empty on main branch where the image is "distroless-dev".
ENVOY_PROXY_VERSION := $(shell grep 'DefaultEnvoyProxyImage' api/v1alpha1/shared_types.go | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+')

kube-generate-examples:
@$(LOG_TARGET)
@pushd $(ROOT_DIR)/examples/extension-server; \
Expand All @@ -17,11 +13,7 @@ kube-build-examples-image:
@$(LOG_TARGET)
@for app in $(EXAMPLE_APPS); do \
pushd $(ROOT_DIR)/examples/$$app; \
if [ -n "$(ENVOY_PROXY_VERSION)" ]; then \
make docker-buildx ENVOY_VERSION=$(ENVOY_PROXY_VERSION); \
else \
make docker-buildx; \
fi; \
make docker-buildx; \
popd; \
done

Expand All @@ -44,4 +36,4 @@ go.mod.tidy.examples:
.PHONY: update-dynamic-module-deps
update-dynamic-module-deps: ## Update dynamic module SDK and envoy version in examples
@$(LOG_TARGET)
@tools/hack/bump-envoy-dynamic-modules.sh $(ENVOY_VERSION)
@tools/hack/bump-envoy-dynamic-modules.sh
Loading