higress-update-envoy-gateway

name

higress-update-envoy-gateway

description

Update Higress Envoy binary and gateway image dependencies for e2e validation. Use when Codex needs to build Envoy packages from the current Higress branch, upload those packages to higress-group/proxy releases, update Makefile.core.mk ENVOY_PACKAGE_URL_PATTERN and ENVOY_LATEST_IMAGE_TAG, run make build-gateway-local, retag the generated proxy/proxyv2 image as gateway, push the gateway image, or prepare a signed-off PR that lets Higress e2e tests consume a new Envoy build.

Higress Envoy Gateway Dependency Update

Core Workflow

Run from the Higress repo root unless a step explicitly says otherwise.

1. Verify context:

   • Check git status --short --branch.
   • Do not remove unrelated user changes or generated artifacts.
   • Use gh for GitHub release/PR checks and always pass --repo for non-current repos.

2. Build Envoy packages from the current branch:

   git submodule update --init
   make build-envoy
   

   Expected artifacts land in external/package/, typically:

   • envoy-alpha-<proxy-sha>.tar.gz
   • envoy-symbol-<proxy-sha>.tar.gz
   • matching .sha256 and .dwp files

3. Publish Envoy package release in higress-group/proxy:

   • Create a new release tag by incrementing the requested RC/test tag, for example v2.2.4-rc.2-test-cpp-host.
   • Match the reference release asset names, even if local filenames include SHAs:
     • local envoy-alpha-<sha>.tar.gz uploads as envoy-amd64.tar.gz
     • local envoy-symbol-<sha>.tar.gz uploads as envoy-symbol-amd64.tar.gz
   • Use temporary renamed copies rather than renaming source artifacts:

     cp external/package/envoy-alpha-<sha>.tar.gz /tmp/envoy-amd64.tar.gz
     cp external/package/envoy-symbol-<sha>.tar.gz /tmp/envoy-symbol-amd64.tar.gz
     gh release create <release-tag> /tmp/envoy-amd64.tar.gz /tmp/envoy-symbol-amd64.tar.gz \
       --repo higress-group/proxy --target <target-branch> --title <release-tag> --generate-notes
     gh release view <release-tag> --repo higress-group/proxy --json tagName,targetCommitish,assets,url
     

   • If following an existing reference release, inspect it first with gh release view.

4. Update Higress Makefile dependencies:

   • In Makefile.core.mk, set:

     export ENVOY_PACKAGE_URL_PATTERN?=https://github.com/higress-group/proxy/releases/download/<release-tag>/envoy-symbol-ARCH.tar.gz
     

   • After building and pushing the gateway image, set:

     ENVOY_LATEST_IMAGE_TAG ?= <gateway-image-tag>
     

5. Build the local gateway image:

   make build-gateway-local
   

   Watch the log to confirm Envoy downloads from the new release URL. The build target may emit an image under a proxy-style repository/name, commonly:

   • higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/proxyv2:<tag>

6. Retag proxy image as gateway:

   docker tag higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/proxyv2:<tag> \
     higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:<tag>
   docker images --format '{{.Repository}}:{{.Tag}} {{.ID}} {{.CreatedSince}}' \
     higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway
   

   Verify the gateway:<tag> and proxyv2:<tag> image IDs match.

7. Push the gateway image when requested:

   docker push higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:<tag>
   

   Record the pushed digest in the final response.

8. Commit and push Makefile changes:

   • Commit only intended tracked files. Do not add plugins/golang-filter/golang-filter_amd64.so or other build outputs unless explicitly requested.
   • Use DCO sign-off:

     git add Makefile.core.mk
     git commit -s -m "Update gateway envoy dependencies"
     git push origin <branch>
     

   • If DCO fails after a previous unsigned commit:

     git commit --amend --no-edit --signoff
     git push --force-with-lease origin <branch>
     gh pr checks <pr-number> --repo higress-group/higress
     

Practical Notes

• make build-gateway-local may need Docker daemon access, network access, and write access to repo/submodule state.
• If sandboxed commands fail with read-only filesystem errors, Docker socket permission errors, or network failures, rerun the same important command with elevated permissions and a concrete justification.
• The default local gateway tag usually comes from the current Git revision shown in the build log as TAG=<sha>.
• For e2e validation, the point of this workflow is to make install-dev, install-dev-wasmplugin, and local image update targets use the newly pushed gateway image through ENVOY_LATEST_IMAGE_TAG.