Local development ​
This document covers building and testing the envoy-gateway extension on a developer machine.
Prerequisites ​
- Go 1.26 or newer.
helmv4 — used bymake check-helm.- GNU Make.
- (Optional)
docker— only required if you intend to build the container image withmake docker-build.
Build ​
make get # download and tidy Go modules
make build # compile bin/extension-envoy-gatewayThe resulting binary supports two subcommands:
bin/extension-envoy-gateway manager # runs the controller manager
bin/extension-envoy-gateway webhook # runs the admission webhookTests ​
make test # runs unit tests (race-enabled) under envtestLint ​
make lint # runs golangci-lint via the internal/tools toolchainHelm chart checks ​
make check-helm # lints all three Helm charts and validates rendered manifestsRefreshing the embedded CRDs ​
The Gateway API and Envoy Gateway CRDs are committed to the repository under pkg/envoygateway/assets/. The script downloads the upstream YAML manifests and renders the Envoy Gateway Helm chart, then writes the result under pkg/envoygateway/assets/. Commit the resulting files so the build stays reproducible offline.
The downloaded artifacts are pinned for integrity: the two Gateway API CRD YAMLs are checked against sha256 checksums and the Envoy Gateway chart against its OCI digest, all recorded in hack/crd-assets.sha256.
# Verify the committed assets against the recorded pins (no version change).
bash hack/update-crds.shA plain run re-downloads and verifies, aborting without touching the assets if anything fails to match the manifest. When you intentionally change the pinned versions, re-record the manifest instead:
# Adopt new versions: re-download, re-record the pins, skip verification.
REGENERATE_CHECKSUMS=1 bash hack/update-crds.shCommit the refreshed assets together with the updated hack/crd-assets.sha256.
Versioning ​
The image tag of the Envoy Gateway control plane is pinned in imagevector/images.yaml. Update the file, then refresh the embedded CRDs to match.
Bumping Envoy Gateway ​
Whenever the pinned Envoy Gateway or Gateway API release changes, run through this checklist. It codifies the drift-catching steps that a naïve version bump misses (RBAC in particular — the hand-authored ClusterRole in pkg/envoygateway/deployer.go is not derived from the upstream chart and must be reconciled by hand).
Bump the version pins.
GATEWAY_API_VERSIONandENVOY_GATEWAY_VERSIONinhack/update-crds.sh.tag:inimagevector/images.yaml.- The version rows in
README.md(Envoy Gateway / Gateway API versions and the compatibility matrix).
Refresh the embedded CRDs and re-record the pins. Because the versions just changed, re-record the integrity manifest rather than verifying against the old pins:
bashREGENERATE_CHECKSUMS=1 bash hack/update-crds.shReconcile the ClusterRole against upstream. The upstream Envoy Gateway helm chart defines its own
ClusterRole; ours is a rewritten copy. Compare and add anything missing:bashhelm template envoy-gateway oci://docker.io/envoyproxy/gateway-helm \ --version "${ENVOY_GATEWAY_VERSION}" \ --namespace kube-system \ | yq eval-all 'select(.kind == "ClusterRole")' -Common drift after a release: new Gateway API resources like
listenersets, new Envoy Gateway policy CRDs (SecurityPolicy,BackendTrafficPolicy, …). Anylist/watchverb missing from the GoclusterRole()will manifest asFailed to watch […] is forbiddenerrors in the Envoy Gateway control-plane logs — see usage/troubleshooting.md.Run the local checks.
bashmake test check-helm lintDeploy against a local Gardener (kind/dev landscape) and smoke-test:
GatewayClass envoy-gatewayreachesAccepted=True.- A demo
GatewayreachesProgrammed=True. - An
HTTPRouteroutes traffic through the LB (the flow described in usage/getting-started.md).
Update the compatibility matrix in
README.mdif the Envoy Proxy or supported Kubernetes range shifted (per the upstream compatibility matrix).Commit the version bump, the refreshed CRD assets, the updated
hack/crd-assets.sha256pin manifest, the RBAC updates, and the README diff as one changeset. Reviewers should be able to see everything the bump touched in one place.