Skip to content
Was this page helpful?

Local development ​

This document covers building and testing the envoy-gateway extension on a developer machine.

Prerequisites ​

  • Go 1.26 or newer.
  • helm v4 — used by make check-helm.
  • GNU Make.
  • (Optional) docker — only required if you intend to build the container image with make docker-build.

Build ​

bash
make get          # download and tidy Go modules
make build        # compile bin/extension-envoy-gateway

The resulting binary supports two subcommands:

bash
bin/extension-envoy-gateway manager   # runs the controller manager
bin/extension-envoy-gateway webhook   # runs the admission webhook

Tests ​

bash
make test         # runs unit tests (race-enabled) under envtest

Lint ​

bash
make lint         # runs golangci-lint via the internal/tools toolchain

Helm chart checks ​

bash
make check-helm   # lints all three Helm charts and validates rendered manifests

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

bash
# Verify the committed assets against the recorded pins (no version change).
bash hack/update-crds.sh

A 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:

bash
# Adopt new versions: re-download, re-record the pins, skip verification.
REGENERATE_CHECKSUMS=1 bash hack/update-crds.sh

Commit 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).

  1. Bump the version pins.

    • GATEWAY_API_VERSION and ENVOY_GATEWAY_VERSION in hack/update-crds.sh.
    • tag: in imagevector/images.yaml.
    • The version rows in README.md (Envoy Gateway / Gateway API versions and the compatibility matrix).
  2. 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:

    bash
    REGENERATE_CHECKSUMS=1 bash hack/update-crds.sh
  3. Reconcile the ClusterRole against upstream. The upstream Envoy Gateway helm chart defines its own ClusterRole; ours is a rewritten copy. Compare and add anything missing:

    bash
    helm 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, …). Any list/watch verb missing from the Go clusterRole() will manifest as Failed to watch […] is forbidden errors in the Envoy Gateway control-plane logs — see usage/troubleshooting.md.

  4. Run the local checks.

    bash
    make test check-helm lint
  5. Deploy against a local Gardener (kind/dev landscape) and smoke-test:

    • GatewayClass envoy-gateway reaches Accepted=True.
    • A demo Gateway reaches Programmed=True.
    • An HTTPRoute routes traffic through the LB (the flow described in usage/getting-started.md).
  6. Update the compatibility matrix in README.md if the Envoy Proxy or supported Kubernetes range shifted (per the upstream compatibility matrix).

  7. Commit the version bump, the refreshed CRD assets, the updated hack/crd-assets.sha256 pin manifest, the RBAC updates, and the README diff as one changeset. Reviewers should be able to see everything the bump touched in one place.

Last updated: