This is the multi-page printable view of this section. Click here to print.
Get Involved
1 - Roadmap
This document serves as a high-level reference for Envoy Gateway users and contributors to understand the direction of the project.
Contributing to the Roadmap
- To add a feature to the roadmap, create an issue or join a community meeting to discuss your use case. If your feature is accepted, a maintainer will assign your issue to a release milestone and update this document accordingly.
- To help with an existing roadmap item, comment on or assign yourself to the associated issue.
- If a roadmap item doesn’t have an issue, create one, assign yourself to the issue, and reference this document. A maintainer will submit a pull request to add the feature to the roadmap. Note: The feature should be discussed in an issue or a community meeting before implementing it.
If you don’t know where to start contributing, help is needed to reduce technical, automation, and documentation debt.
Look for issues with the help wanted
label to get started.
Details
Roadmap features and timelines may change based on feedback, community contributions, etc. If you depend on a specific roadmap item, you’re encouraged to attend a community meeting to discuss the details, or help us deliver the feature by contributing to the project.
Last Updated: April 2023
v0.2.0: Establish a Solid Foundation
- Complete the core Envoy Gateway implementation- Issue #60.
- Establish initial testing, e2e, integration, etc- Issue #64.
- Establish user and developer project documentation- Issue #17.
- Achieve Gateway API conformance (e.g. routing, LB, Header transformation, etc.)- Issue #65.
- Setup a CI/CD pipeline- Issue #63.
v0.3.0: Drive Advanced Features through Extension Mechanisms
- Support extended Gateway API fields Issue #707.
- Support experimental Gateway APIs such as TCPRoute Issue #643, UDPRoute Issue #641 and GRPCRoute Issue #642.
- Establish guidelines for leveragaing Gateway API extensions Issue #675.
- Rate Limiting Issue #670.
- Authentication Issue #336.
v0.4.0: Customizing Envoy Gateway
- Extending Envoy Gateway control plane Issue #20
- Helm based installation for Envoy Gateway Issue #650
- Customizing managed Envoy Proxy Kubernetes resource fields Issue #648
- Configuring xDS Bootstrap Issue #31
v0.5.0: Observability and Scale
- Observability for control plane and data plane Issue #701.
- Compute and document Envoy Gateway performance Issue #1365.
- Allow users to configure xDS Resources Issue #24.
v0.6.0: Preparation for GA
- Envoy Gateway meets readiness criteria Issue #1160.
2 - Developer Guide
Envoy Gateway is built using a make-based build system. Our CI is based on Github Actions using workflows.
Prerequisites
go
- Version: 1.20
- Installation Guide: https://go.dev/doc/install
make
- Recommended Version: 4.0 or later
- Installation Guide: https://www.gnu.org/software/make
docker
- Optional when you want to build a Docker image or run
make
inside Docker. - Recommended Version: 20.10.16
- Installation Guide: https://docs.docker.com/engine/install
python3
- Need a
python3
program - Must have a functioning
venv
module; this is part of the standard library, but some distributions (such as Debian and Ubuntu) replace it with a stub and require you to install apython3-venv
package separately.
Quickstart
- Run
make help
to see all the available targets to build, test and run Envoy Gateway.
Building
- Run
make build
to build all the binaries. - Run
make build BINS="envoy-gateway"
to build the Envoy Gateway binary. - Run
make build BINS="egctl"
to build the egctl binary.
Note: The binaries get generated in the bin/$OS/$ARCH
directory, for example, bin/linux/amd64/
.
Testing
Run
make test
to run the golang tests.Run
make testdata
to generate the golden YAML testdata files.
Running Linters
- Run
make lint
to make sure your code passes all the linter checks. Note: Thegolangci-lint
configuration resides here.
Building and Pushing the Image
- Run
IMAGE=docker.io/you/gateway-dev make image
to build the docker image. - Run
IMAGE=docker.io/you/gateway-dev make push-multiarch
to build and push the multi-arch docker image.
Note: Replace IMAGE
with your registry’s image name.
Deploying Envoy Gateway for Test/Dev
- Run
make create-cluster
to create a Kind cluster.
Option 1: Use the Latest gateway-dev Image
- Run
TAG=latest make kube-deploy
to deploy Envoy Gateway in the Kind cluster using the latest image. Replacelatest
to use a different image tag.
Option 2: Use a Custom Image
- Run
make kube-install-image
to build an image from the tip of your current branch and load it in the Kind cluster. - Run
IMAGE_PULL_POLICY=IfNotPresent make kube-deploy
to install Envoy Gateway into the Kind cluster using your custom image.
Deploying Envoy Gateway in Kubernetes
- Run
TAG=latest make kube-deploy
to deploy Envoy Gateway using the latest image into a Kubernetes cluster (linked to the current kube context). Preface the command withIMAGE
or replaceTAG
to use a different Envoy Gateway image or tag. - Run
make kube-undeploy
to uninstall Envoy Gateway from the cluster.
Note: Envoy Gateway is tested against Kubernetes v1.24.0.
Demo Setup
- Run
make kube-demo
to deploy a demo backend service, gatewayclass, gateway and httproute resource (similar to steps outlined in the Quickstart docs) and test the configuration. - Run
make kube-demo-undeploy
to delete the resources created by themake kube-demo
command.
Run Gateway API Conformance Tests
The commands below deploy Envoy Gateway to a Kubernetes cluster and run the Gateway API conformance tests. Refer to the
Gateway API conformance homepage to learn more about the tests. If Envoy Gateway is already installed, run
TAG=latest make run-conformance
to run the conformance tests.
On a Linux Host
- Run
TAG=latest make conformance
to create a Kind cluster, install Envoy Gateway using the latest gateway-dev image, and run Gateway API conformance tests.
On a Mac Host
Since Mac doesn’t support directly exposing the Docker network to the Mac host, use one of the following workarounds to run conformance tests:
- Deploy your own Kubernetes cluster or use Docker Desktop with Kubernetes support and then run
TAG=latest make kube-deploy run-conformance
. This will install Envoy Gateway using the latest gateway-dev image to the Kubernetes cluster using the current kubectl context and run the conformance tests. Usemake kube-undeploy
to uninstall Envoy Gateway. - Install and run Docker Mac Net Connect and then run
TAG=latest make conformance
.
Note: Preface commands with IMAGE
or replace TAG
to use a different Envoy Gateway image or tag. If TAG
is unspecified, the short SHA of your current branch is used.
Debugging the Envoy Config
An easy way to view the envoy config that Envoy Gateway is using is to port-forward to the admin interface port
(currently 19000
) on the Envoy deployment that corresponds to a Gateway so that it can be accessed locally.
Get the name of the Envoy deployment. The following example is for Gateway eg
in the default
namespace:
export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')
Port forward the admin interface port:
kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000
Now you are able to view the running Envoy configuration by navigating to 127.0.0.1:19000/config_dump
.
There are many other endpoints on the Envoy admin interface that may be helpful when debugging.
JWT Testing
An example JSON Web Token (JWT) and JSON Web Key Set (JWKS) are used for the request authentication
user guide. The JWT was created by the JWT Debugger, using the RS256
algorithm. The public key from the JWTs
verify signature was copied to JWK Creator for generating the JWK. The JWK Creator was configured with matching
settings, i.e. Signing
public key use and the RS256
algorithm. The generated JWK was wrapped in a JWKS structure
and is hosted in the repo.
3 - Contributing
We welcome contributions from the community. Please carefully review the project goals and following guidelines to streamline your contributions.
Communication
- Before starting work on a major feature, please contact us via GitHub or Slack. We will ensure no one else is working on it and ask you to open a GitHub issue.
- A “major feature” is defined as any change that is > 100 LOC altered (not including tests), or changes any user-facing behavior. We will use the GitHub issue to discuss the feature and come to agreement. This is to prevent your time being wasted, as well as ours. The GitHub review process for major features is also important so that affiliations with commit access can come to agreement on the design. If it’s appropriate to write a design document, the document must be hosted either in the GitHub issue, or linked to from the issue and hosted in a world-readable location.
- Small patches and bug fixes don’t need prior communication.
Inclusivity
The Envoy Gateway community has an explicit goal to be inclusive to all. As such, all PRs must adhere to the following guidelines for all code, APIs, and documentation:
- The following words and phrases are not allowed:
- Whitelist: use allowlist instead.
- Blacklist: use denylist or blocklist instead.
- Master: use primary instead.
- Slave: use secondary or replica instead.
- Documentation should be written in an inclusive style. The Google developer documentation contains an excellent reference on this topic.
- The above policy is not considered definitive and may be amended in the future as industry best practices evolve. Additional comments on this topic may be provided by maintainers during code review.
Submitting a PR
- Fork the repo.
- Hack
- DCO sign-off each commit. This can be done with
git commit -s
. - Submit your PR.
- Tests will automatically run for you.
- We will not merge any PR that is not passing tests.
- PRs are expected to have 100% test coverage for added code. This can be verified with a coverage build. If your PR cannot have 100% coverage for some reason please clearly explain why when you open it.
- Any PR that changes user-facing behavior must have associated documentation in the docs folder of the repo as well as the changelog.
- All code comments and documentation are expected to have proper English grammar and punctuation. If you are not a fluent English speaker (or a bad writer ;-)) please let us know and we will try to find some help but there are no guarantees.
- Your PR title should be descriptive, and generally start with type that contains a subsystem name with
()
if necessary and summary followed by a colon. formatchore/docs/feat/fix/refactor/style/test: summary
. Examples:- “docs: fix grammar error”
- “feat(translator): add new feature”
- “fix: fix xx bug”
- “chore: change ci & build tools etc”
- Your PR commit message will be used as the commit message when your PR is merged. You should update this field if your PR diverges during review.
- Your PR description should have details on what the PR does. If it fixes an existing issue it should end with “Fixes #XXX”.
- If your PR is co-authored or based on an earlier PR from another contributor,
please attribute them with
Co-authored-by: name <name@example.com>
. See GitHub’s multiple author guidance for further details. - When all tests are passing and all other conditions described herein are satisfied, a maintainer will be assigned to review and merge the PR.
- Once you submit a PR, please do not rebase it. It’s much easier to review if subsequent commits are new commits and/or merges. We squash and merge so the number of commits you have in the PR doesn’t matter.
- We expect that once a PR is opened, it will be actively worked on until it is merged or closed. We reserve the right to close PRs that are not making progress. This is generally defined as no changes for 7 days. Obviously PRs that are closed due to lack of activity can be reopened later. Closing stale PRs helps us to keep on top of all the work currently in flight.
Maintainer PR Review Policy
- See CODEOWNERS.md for the current list of maintainers.
- A maintainer representing a different affiliation from the PR owner is required to review and approve the PR.
- When the project matures, it is expected that a “domain expert” for the code the PR touches should review the PR. This person does not require commit access, just domain knowledge.
- The above rules may be waived for PRs which only update docs or comments, or trivial changes to tests and tools (where trivial is decided by the maintainer in question).
- If there is a question on who should review a PR please discuss in Slack.
- Anyone is welcome to review any PR that they want, whether they are a maintainer or not.
- Please make sure that the PR title, commit message, and description are updated if the PR changes significantly during review.
- Please clean up the title and body before merging. By default, GitHub fills the squash merge title with the original title, and the commit body with every individual commit from the PR. The maintainer doing the merge should make sure the title follows the guidelines above and should overwrite the body with the original commit message from the PR (cleaning it up if necessary) while preserving the PR author’s final DCO sign-off.
Decision making
This is a new and complex project, and we need to make a lot of decisions very quickly. To this end, we’ve settled on this process for making (possibly contentious) decisions:
- For decisions that need a record, we create an issue.
- In that issue, we discuss opinions, then a maintainer can call for a vote in a comment.
- Maintainers can cast binding votes on that comment by reacting or replying in another comment.
- Non-maintainer community members are welcome to cast non-binding votes by either of these methods.
- Voting will be resolved by simple majority.
- In the event of deadlocks, the question will be put to steering instead.
DCO: Sign your work
The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below (from developercertificate.org):
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
then you just add a line to every git commit message:
Signed-off-by: Joe Smith <joe@gmail.com>
using your real name (sorry, no pseudonyms or anonymous contributions.)
You can add the sign-off when creating the git commit via git commit -s
.
If you want this to be automatic you can set up some aliases:
git config --add alias.amend "commit -s --amend"
git config --add alias.c "commit -s"
Fixing DCO
If your PR fails the DCO check, it’s necessary to fix the entire commit history in the PR. Best practice is to squash the commit history to a single commit, append the DCO sign-off as described above, and force push. For example, if you have 2 commits in your history:
git rebase -i HEAD^^
(interactive squash + DCO append)
git push origin -f
Note, that in general rewriting history in this way is a hindrance to the review process and this should only be done to correct a DCO mistake.
4 - Code of Conduct
Envoy Gateway follows the CNCF Code of Conduct.
5 - Maintainers
The following maintainers, listed in alphabetical order, own everything
- @AliceProxy
- @arkodg
- @Xunzhuo
- @zirain
- @qicz
Emeritus Maintainers
- @danehans
- @alexgervais
- @skriss
- @youngnick
6 - Release Process
This document guides maintainers through the process of creating an Envoy Gateway release.
Release Candidate
The following steps should be used for creating a release candidate.
Prerequisites
- Permissions to push to the Envoy Gateway repository.
Set environment variables for use in subsequent steps:
export MAJOR_VERSION=0
export MINOR_VERSION=3
export RELEASE_CANDIDATE_NUMBER=1
export GITHUB_REMOTE=origin
Clone the repo, checkout the
main
branch, ensure it’s up-to-date, and your local branch is clean.Create a topic branch for adding the release notes and updating the VERSION file with the release version. Refer to previous release notes and VERSION for additional details.
Sign, commit, and push your changes to your fork.
Submit a Pull Request to merge the changes into the
main
branch. Do not proceed until your PR has merged and the Build and Test has successfully completed.Create a new release branch from
main
. The release branch should be namedrelease/v${MAJOR_VERSION}.${MINOR_VERSION}
, e.g.release/v0.3
.git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION}
Push the branch to the Envoy Gateway repo.
git push ${GITHUB_REMOTE} release/v${MAJOR_VERSION}.${MINOR_VERSION}
Create a topic branch for updating the Envoy proxy image to the tag supported by the release. Reference PR #958 for additional details on updating the image tag.
Sign, commit, and push your changes to your fork.
Submit a Pull Request to merge the changes into the
release/v${MAJOR_VERSION}.${MINOR_VERSION}
branch. Do not proceed until your PR has merged into the release branch and the Build and Test has completed for your PR.Ensure your release branch is up-to-date and tag the head of your release branch with the release candidate number.
git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} Release Candidate'
Push the tag to the Envoy Gateway repository.
git push ${GITHUB_REMOTE} v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER}
This will trigger the release GitHub action that generates the release, release artifacts, etc.
Confirm that the release workflow completed successfully.
Confirm that the Envoy Gateway image with the correct release tag was published to Docker Hub.
Confirm that the release was created.
Note that the Quickstart Guide references are not updated for release candidates. However, test the quickstart steps using the release candidate by manually updating the links.
Generate the GitHub changelog.
Ensure you check the “This is a pre-release” checkbox when editing the GitHub release.
If you find any bugs in this process, please create an issue.
Setup cherry picker action
After release branch cut, RM (Release Manager) should add job cherrypick action for target release.
Configuration looks like following:
cherry_pick_release_v0_4:
runs-on: ubuntu-latest
name: Cherry pick into release-v0.4
if: ${{ contains(github.event.pull_request.labels.*.name, 'cherrypick/release-v0.4') && github.event.pull_request.merged == true }}
steps:
- name: Checkout
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
with:
fetch-depth: 0
- name: Cherry pick into release/v0.4
uses: carloscastrojumo/github-cherry-pick-action@a145da1b8142e752d3cbc11aaaa46a535690f0c5 # v1.0.9
with:
branch: release/v0.4
title: "[release/v0.4] {old_title}"
body: "Cherry picking #{old_pull_request_id} onto release/v0.4"
labels: |
cherrypick/release-v0.4
# put release manager here
reviewers: |
AliceProxy
Replace v0.4
with real branch name, and AliceProxy
with the real name of RM.
Minor Release
The following steps should be used for creating a minor release.
Prerequisites
- Permissions to push to the Envoy Gateway repository.
- A release branch that has been cut from the corresponding release candidate. Refer to the Release Candidate section for additional details on cutting a release candidate.
Set environment variables for use in subsequent steps:
export MAJOR_VERSION=0
export MINOR_VERSION=3
export GITHUB_REMOTE=origin
Clone the repo, checkout the
main
branch, ensure it’s up-to-date, and your local branch is clean.Create a topic branch for adding the release notes, release announcement, and versioned release docs.
- Create the release notes. Reference previous release notes for additional details. Note: The release notes should be an accumulation of the release candidate release notes and any changes since the release candidate.
- Create a release announcement. Refer to PR #635 as an example release announcement.
- Include the release in the compatibility matrix. Refer to PR #1002 as an example.
- Generate the versioned release docs:
make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION}
Sign, commit, and push your changes to your fork.
Submit a Pull Request to merge the changes into the
main
branch. Do not proceed until all your PRs have merged and the Build and Test has completed for your final PR.Checkout the release branch.
git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} $GITHUB_REMOTE/release/v${MAJOR_VERSION}.${MINOR_VERSION}
If the tip of the release branch does not match the tip of
main
, perform the following:Create a topic branch from the release branch.
Cherry-pick the commits from
main
that differ from the release branch.Run tests locally, e.g.
make lint
.Sign, commit, and push your topic branch to your Envoy Gateway fork.
Submit a PR to merge the topic from of your fork into the Envoy Gateway release branch.
Do not proceed until the PR has merged and CI passes for the merged PR.
If you are still on your topic branch, change to the release branch:
git checkout release/v${MAJOR_VERSION}.${MINOR_VERSION}
Ensure your local release branch is up-to-date:
git pull $GITHUB_REMOTE release/v${MAJOR_VERSION}.${MINOR_VERSION}
Tag the head of your release branch with the release tag. For example:
git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0 -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0 Release'
Note: The tag version differs from the release branch by including the
.0
patch version.Push the tag to the Envoy Gateway repository.
git push origin v${MAJOR_VERSION}.${MINOR_VERSION}.0
This will trigger the release GitHub action that generates the release, release artifacts, etc.
Confirm that the release workflow completed successfully.
Confirm that the Envoy Gateway image with the correct release tag was published to Docker Hub.
Confirm that the release was created.
Confirm that the steps in the Quickstart Guide work as expected.
Generate the GitHub changelog and include the following text at the beginning of the release page:
# Release Announcement
Check out the [v${MAJOR_VERSION}.${MINOR_VERSION} release announcement]
(https://gateway.envoyproxy.io/releases/v${MAJOR_VERSION}.${MINOR_VERSION}.html) to learn more about the release.
If you find any bugs in this process, please create an issue.
Announce the Release
It’s important that the world knows about the release. Use the following steps to announce the release.
Set the release information in the Envoy Gateway Slack channel. For example:
Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION} has been released: https://github.com/envoyproxy/gateway/releases/tag/v${MAJOR_VERSION}.${MINOR_VERSION}.0
Send a message to the Envoy Gateway Slack channel. For example:
On behalf of the entire Envoy Gateway community, I am pleased to announce the release of Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}. A big thank you to all the contributors that made this release possible. Refer to the official v${MAJOR_VERSION}.${MINOR_VERSION} announcement for release details and the project docs to start using Envoy Gateway. ...
Link to the GitHub release and release announcement page that highlights the release.
7 - Working on Envoy Gateway Docs
The documentation for the Envoy Gateway lives in the docs/
directory. Any
individual document can be written using either reStructuredText or Markdown,
you can choose the format that you’re most comfortable with when working on the
documentation.
Documentation Structure
We supported the versioned Docs now, the directory name under docs represents
the version of docs. The root of the latest site is in docs/latest/index.rst
.
This is probably where to start if you’re trying to understand how things fit together.
Note that the new contents should be added to docs/latest
and will be cut off at
the next release. The contents under docs/v0.2.0
are auto-generated,
and usually do not need to make changes to them, unless if you find the current release pages have
some incorrect contents. If so, you should send a PR to update contents both of docs/latest
and docs/v0.2.0
.
It’s important to note that a given document must have a reference in some
.. toctree::
section for the document to be reachable. Not everything needs
to be in docs/index.rst
’s toctree
though.
You can access the website which represents the current release in default, and you can access the website which contains the latest version changes in Here or at the footer of the pages.
Documentation Workflow
To work with the docs, just edit reStructuredText or Markdown files in docs
,
then run
make docs
This will create docs/html
with the built HTML pages. You can view the docs
either simply by pointing a web browser at the file://
path to your
docs/html
, or by firing up a static webserver from that directory, e.g.
make docs-serve
If you want to generate a new release version of the docs, like v0.3.0
, then run
make docs-release TAG=v0.3.0
This will update the VERSION file at the project root, which records current release version,
and it will be used in the pages version context and binary version output. Also, this will generate
new dir docs/v0.3.0
, which contains docs at v0.3.0 and updates artifact links to v0.3.0
in all files under docs/v0.3.0/user
, like quickstart.md
, http-routing.md
and etc.
Publishing Docs
Whenever docs are pushed to main
, CI will publish the built docs to GitHub
Pages. For more details, see .github/workflows/docs.yaml
.