This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Get Involved

This section includes contents related to Contributions

1 - Roadmap

This section records the roadmap of Envoy Gateway.

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: October 2022

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

  • Global Rate Limiting
  • AuthN/AuthZ- Issue #336.
  • Lets Encrypt Integration

v0.4.0: Manageability and Scale

  • Tooling for devs/infra admins to aid in managing/maintaining EG
  • Support advanced provisioning use cases (e.g. multi-cluster, serverless, etc.)
  • Perf testing (EG specifically)
  • Support for Chaos engineering?

2 - Developer Guide

This section tells how to develop Envoy Gateway.

Envoy Gateway is built using a make-based build system. Our CI is based on Github Actions using workflows.

Prerequisites

go

make

docker

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 a python3-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: The golangci-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. Replace latest 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 with IMAGE or replace TAG 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 the make 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. Use make 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

This section tells how to contribute to Envoy Gateway.

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. format chore/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

This section includes Code of Conduct of Envoy Gateway.

Envoy Gateway follows the CNCF Code of Conduct.

5 - Maintainers

This section includes Maintainers of Envoy Gateway.

The following maintainers, listed in alphabetical order, own everything

  • @AliceProxy
  • @arkodg
  • @Xunzhuo
  • @zirain
  • @qicz

Emeritus Maintainers

  • @danehans
  • @alexgervais
  • @skriss
  • @youngnick

6 - Release Process

This section tells the release process of Envoy Gateway.

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

  1. Clone the repo, checkout the main branch, ensure it’s up-to-date, and your local branch is clean.

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

  3. Sign, commit, and push your changes to your fork.

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

  5. Create a new release branch from main. The release branch should be named release/v${MAJOR_VERSION}.${MINOR_VERSION}, e.g. release/v0.3.

    git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION}

  6. Push the branch to the Envoy Gateway repo.

    git push ${GITHUB_REMOTE} release/v${MAJOR_VERSION}.${MINOR_VERSION}

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

  8. Sign, commit, and push your changes to your fork.

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

  10. 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'

  11. Push the tag to the Envoy Gateway repository.

    git push ${GITHUB_REMOTE} v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER}

  12. This will trigger the release GitHub action that generates the release, release artifacts, etc.

  13. Confirm that the release workflow completed successfully.

  14. Confirm that the Envoy Gateway image with the correct release tag was published to Docker Hub.

  15. Confirm that the release was created.

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

  17. Generate the GitHub changelog.

  18. Ensure you check the “This is a pre-release” checkbox when editing the GitHub release.

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

  1. Clone the repo, checkout the main branch, ensure it’s up-to-date, and your local branch is clean.

  2. Create a topic branch for adding the release notes, release announcement, and versioned release docs.

    1. 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.
    2. Create a release announcement. Refer to PR #635 as an example release announcement.
    3. Include the release in the compatibility matrix. Refer to PR #1002 as an example.
    4. Generate the versioned release docs:
       make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION}

  3. Sign, commit, and push your changes to your fork.

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

  5. Checkout the release branch.

    git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} $GITHUB_REMOTE/release/v${MAJOR_VERSION}.${MINOR_VERSION}

  6. If the tip of the release branch does not match the tip of main, perform the following:

    1. Create a topic branch from the release branch.

    2. Cherry-pick the commits from main that differ from the release branch.

    3. Run tests locally, e.g. make lint.

    4. Sign, commit, and push your topic branch to your Envoy Gateway fork.

    5. Submit a PR to merge the topic from of your fork into the Envoy Gateway release branch.

    6. Do not proceed until the PR has merged and CI passes for the merged PR.

    7. If you are still on your topic branch, change to the release branch:

      git checkout release/v${MAJOR_VERSION}.${MINOR_VERSION}

    8. Ensure your local release branch is up-to-date:

      git pull $GITHUB_REMOTE release/v${MAJOR_VERSION}.${MINOR_VERSION}

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

  8. Push the tag to the Envoy Gateway repository.

    git push origin v${MAJOR_VERSION}.${MINOR_VERSION}.0

  9. This will trigger the release GitHub action that generates the release, release artifacts, etc.

  10. Confirm that the release workflow completed successfully.

  11. Confirm that the Envoy Gateway image with the correct release tag was published to Docker Hub.

  12. Confirm that the release was created.

  13. Confirm that the steps in the Quickstart Guide work as expected.

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

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

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

This section tells the development of Envoy Gateway Documents.

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.