Skip to content

Move envoy management to calico #4806

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
MichalFupso wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Move envoy management to calico #4806

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
329a6b4
Move envoy management to calico
MichalFupso May 13, 2026
6c3b50d
Update steps
MichalFupso May 27, 2026
50e32bc
Merge tigera/master into migrate-envoy; adapt envoy version sync
MichalFupso Jun 1, 2026
0df1036
Update helm variables
MichalFupso Jun 1, 2026
c2d9c50
Update helm variables
MichalFupso Jun 1, 2026
5bf3f0a
Update common tasks
MichalFupso Jun 1, 2026
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
35 changes: 28 additions & 7 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ HELM3_URL = https://get.helm.sh/helm-$(HELM3_VERSION)-$(NATIVE_OS)-$(BUILDARCH).
HELM_BUILDARCH_BINARY = $(HACK_BIN)/helm-$(BUILDARCH)
HELM_BUILDARCH_VERSIONED_BINARY = $(HELM_BUILDARCH_BINARY)-$(HELM3_VERSION)


# The directory into which we download binaries we need to run certain
# processes, e.g. generating bundles
HACK_BIN ?= hack/bin
Expand Down Expand Up @@ -244,10 +243,15 @@ $(ISTIO_RESOURCES_DIR)/%.tgz:
@echo "Downloading Istio chart $* version $(ISTIO_VERSION)..."
@curl -fsSL -o $@ $(ISTIO_HELM_REPO)/$*-$(ISTIO_VERSION).tgz

# To update the Envoy Gateway version, see "Updating the bundled version of
# Envoy Gateway" in docs/common_tasks.md.
# The Envoy Gateway version is owned by projectcalico/calico
# (third_party/envoy-gateway/Makefile) and bumped there by Renovate. `make
# gen-versions` (target: update-envoy-gateway-version) pins it into go.mod's
# github.com/envoyproxy/gateway; we derive ENVOY_GATEWAY_VERSION from that pin so
# there is a single source of truth and the embedded chart can never drift from
# the decoder types. See "Updating the bundled version of Envoy Gateway" in
# docs/common_tasks.md.
ENVOY_GATEWAY_HELM_CHART ?= oci://docker.io/envoyproxy/gateway-helm
ENVOY_GATEWAY_VERSION ?= v1.7.2
ENVOY_GATEWAY_VERSION ?= $(shell awk '/^[[:space:]]*github\.com\/envoyproxy\/gateway[[:space:]]+v/ {print $$2}' go.mod)
ENVOY_GATEWAY_CHART = pkg/render/gatewayapi/gateway-helm.tgz

$(ENVOY_GATEWAY_CHART): $(HACK_BIN)/helm-$(BUILDARCH)
Expand All @@ -266,7 +270,6 @@ $(HELM_BUILDARCH_VERSIONED_BINARY): | $(HACK_BIN)
@curl -fsSL --retry 5 $(HELM3_URL) | tar --extract --gzip -C $(HACK_BIN) --strip-components=1 $(NATIVE_OS)-$(BUILDARCH)/helm -O > $(HELM_BUILDARCH_VERSIONED_BINARY)
@chmod a+x $(HELM_BUILDARCH_VERSIONED_BINARY)


build: $(BINDIR)/operator-$(ARCH)
$(BINDIR)/operator-$(ARCH): $(SRC_FILES) $(ENVOY_GATEWAY_CHART) $(ISTIO_CHART_FILES)
mkdir -p $(BINDIR)
Expand Down Expand Up @@ -613,7 +616,7 @@ EE_VERSIONS?=config/enterprise_versions.yml

gen-versions: gen-versions-calico gen-versions-enterprise

gen-versions-calico: $(BINDIR)/gen-versions update-calico-crds
gen-versions-calico: $(BINDIR)/gen-versions update-calico-crds update-envoy-gateway-version
$(BINDIR)/gen-versions -os-versions=$(OS_VERSIONS) > pkg/components/calico.go

gen-versions-enterprise: $(BINDIR)/gen-versions update-enterprise-crds
Expand Down Expand Up @@ -675,7 +678,7 @@ define copy_admission_policies
endef

.PHONY: read-libcalico-version read-libcalico-enterprise-version
.PHONY: update-calico-crds update-enterprise-crds
.PHONY: update-calico-crds update-enterprise-crds update-envoy-gateway-version
.PHONY: fetch-calico-crds fetch-enterprise-crds
.PHONY: prepare-for-calico-crds prepare-for-enterprise-crds

Expand All @@ -694,6 +697,24 @@ update-calico-crds: fetch-calico-crds
$(call copy_k8s_policy_crds,"calico")
$(call copy_admission_policies, $(CALICO_CRDS_DIR),"calico")

# The Envoy Gateway version is owned by projectcalico/calico's
# third_party/envoy-gateway/Makefile (bumped there by Renovate). We pin
# go.mod's github.com/envoyproxy/gateway to that version; the operator's own
# Makefile derives ENVOY_GATEWAY_VERSION from this go.mod pin and pulls/embeds
# the matching gateway-helm chart at build time, so the chart and the Go decoder
# types are always at the same version. ENVOY_GATEWAY_VERSION lives in the calico
# clone that fetch-calico-crds prepares.
update-envoy-gateway-version: fetch-calico-crds
@new=$$(grep -E '^ENVOY_GATEWAY_VERSION=' $(CALICO_CRDS_DIR)/third_party/envoy-gateway/Makefile | cut -d= -f2 | tr -d ' '); \
cur=$$(awk '/^[[:space:]]*github\.com\/envoyproxy\/gateway[[:space:]]+v/ {print $$2}' go.mod); \
if [ -z "$$new" ]; then echo "Failed to parse ENVOY_GATEWAY_VERSION from calico Makefile" >&2; exit 1; fi; \
if [ "$$new" != "$$cur" ]; then \
echo "Bumping envoyproxy/gateway in go.mod: $$cur -> $$new"; \
$(CONTAINERIZED) $(CALICO_BUILD) sh -c '$(GIT_CONFIG_SSH) go mod edit -require=github.com/envoyproxy/gateway@'"$$new"' && go mod tidy'; \
else \
echo "envoyproxy/gateway already pinned at $$new in go.mod"; \
fi

prepare-for-calico-crds:
$(call prep_local_crds,"calico")

Expand Down
94 changes: 59 additions & 35 deletions docs/common_tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,38 +176,62 @@ spec:

### Updating the bundled version of Envoy Gateway

1. In `go.mod`, update the version for `github.com/envoyproxy/gateway`.

1. Run `make mod-tidy`. If this indicates needing other changes, e.g. bumping the go-build version, do that. (For example, for a possible move to Envoy Gateway v1.3.2 - not yet committed - I needed to update `GO_BUILD_VER` from `v0.95` to `1.23.6-llvm18.1.8-k8s1.31.5`, because Envoy Gateway v1.3.2 requires golang v1.23.6.)

1. In `Makefile`, update `ENVOY_GATEWAY_VERSION`.

1. Delete `pkg/render/gatewayapi/gateway-helm.tgz`.

1. Run `make build`. This will download the new version of the Envoy Gateway helm chart and build the operator image. The chart is embedded in the binary and rendered at runtime using the Helm SDK.

1. Address build issues if there are any.

1. Run `make ut`, and address issues if there are any.

1. Commit everything and post as a `tigera/operator` PR.

1. Identify the corresponding new versions of the `gateway`, `proxy` and `ratelimit` images.

- The `gateway` version can be found in the Envoy Gateway release notes ([for example](https://github.com/envoyproxy/gateway/releases/tag/v1.3.2)). It should be the same as the nominal Envoy Gateway version that you're updating to.

- The `proxy` version can be found in the Envoy Gateway release notes, or by referring to [this compatibility matrix](https://gateway.envoyproxy.io/news/releases/matrix/).

- The `ratelimit` version can be found in the Envoy Gateway release notes.

1. Switching to the `projectcalico/calico` repo, update the code under `third_party/envoy-{gateway,proxy,ratelimit}` to build those new image versions. In each case:

- Update the relevant version (e.g. `ENVOY_GATEWAY_VERSION`) in `Makefile`.

- Review if any existing patches are still required, and remove them if not.

- Review if any existing patches still apply cleanly, and update them if not.

1. Commit everything and post as a `projectcalico/calico` PR.

1. Review, address issues, merge, monitor hashrelease builds, address any further issues, etc.
The Envoy Gateway version pin and the source-built images all live in
`projectcalico/calico` (`third_party/envoy-{gateway,proxy,ratelimit}`). The
operator embeds the upstream `gateway-helm` chart — fetched at build time and
rendered at runtime via the Helm SDK — and pins `go.mod`'s
`github.com/envoyproxy/gateway` (the chart decoder types) to the same version.
`make gen-versions` copies that single version pin out of a calico clone into
`go.mod`; the operator Makefile then derives `ENVOY_GATEWAY_VERSION` from
`go.mod`, so the embedded chart and the decoder types can never drift. A version
bump therefore lands in two PRs — calico first, operator second.

**In `projectcalico/calico`:**

1. Bump `ENVOY_GATEWAY_VERSION` in `third_party/envoy-gateway/Makefile`. (Renovate
normally does this automatically — see `renovate.json`.) Note that Renovate
only handles envoy-gateway *patch* bumps; it does not touch the matching
envoy-proxy/envoy-ratelimit versions or refresh the patch stacks, so
minor/major bumps still need the next steps by hand.

1. Update `third_party/envoy-proxy/Makefile` and
`third_party/envoy-ratelimit/Makefile` to the matching `proxy` and
`ratelimit` versions. Versions are listed in the Envoy Gateway release notes
([for example](https://github.com/envoyproxy/gateway/releases/tag/v1.3.2))
and the [compatibility matrix](https://gateway.envoyproxy.io/news/releases/matrix/).

1. For each of `third_party/envoy-{gateway,proxy,ratelimit}`: review whether
existing patches still apply cleanly and remain required; update or drop
them as needed.

1. Commit and post as a `projectcalico/calico` PR.

**In `tigera/operator` (after the calico PR merges):**

> **Normally you don't run these by hand.** The hourly `sync-versions` workflow
> (`.github/workflows/sync-versions.yml`) runs `make gen-versions`, so within ~an hour of the calico PR
> merging an **"Auto: sync versions"** PR appears with the `go.mod` envoy-gateway
> pin already applied (step 1); CI on that PR rebuilds the embedded chart from the
> pin (the `.tgz` is gitignored and a build prerequisite, so step 2 is
> local-only). Run the steps below by hand only for an out-of-cycle bump.
> The parts the sync **can't** do are
> the `gateway_api.go` changes for new CRD kinds (step 3) and any test fixes
> (step 4) — those show up as red CI on the auto-sync PR.

1. Run `make gen-versions`. The `update-envoy-gateway-version` target it invokes
reads calico's `ENVOY_GATEWAY_VERSION` pin and, when it differs from `go.mod`,
runs `go mod edit -require=github.com/envoyproxy/gateway@<new> && go mod tidy`
to pin the Go decoder types. If `go mod tidy` surfaces other changes (e.g. a
`GO_BUILD_VER` bump), address them.

1. Delete `pkg/render/gatewayapi/gateway-helm.tgz` and run `make build`. This
re-downloads the chart at the version now pinned in `go.mod` (the Makefile
derives `ENVOY_GATEWAY_VERSION` from it), embeds it in the operator binary,
and renders it at runtime using the Helm SDK.

1. If the chart introduced new CRDs or resource kinds, update
`pkg/render/gatewayapi/gateway_api.go` to parse them.

1. Run `make ut`, address issues.

1. Commit and post as a `tigera/operator` PR.
Loading