envoy Documentation

1. Project Overview & Quickstart (envoyproxy/envoy) Copy Chapter

File: README.md Copy Chapter

Cloud-native high-performance edge/middle/service proxy

Envoy is hosted by the Cloud Native Computing Foundation (CNCF). If you are a
company that wants to help shape the evolution of technologies that are container-packaged,
dynamically-scheduled and microservices-oriented, consider joining the CNCF. For details about who's
involved and how Envoy plays a role, read the CNCF
announcement.

Documentation Copy Chapter

• Official documentation
• FAQ
• Example documentation
• Blog about the threading model
• Blog about hot restart
• Blog about stats architecture
• Blog about universal data plane API
• Blog on Lyft's Envoy dashboards

Related Copy Chapter

• data-plane-api: v2 API definitions as a standalone
  repository. This is a read-only mirror of api.
• envoy-perf: Performance testing framework.
• envoy-filter-example: Example of how to add new filters
  and link to the main repository.

Contact Copy Chapter

• envoy-announce: Low frequency mailing
  list where we will email announcements only.
• envoy-security-announce: Low frequency mailing
  list where we will email security related announcements only.
• envoy-users: General user discussion.
• envoy-dev: Envoy developer discussion (APIs,
  feature design, etc.).
• envoy-maintainers: Use this list
  to reach all core Envoy maintainers.
• Twitter: Follow along on Twitter!
• Slack: Slack, to get invited go here.
  • NOTE: Response to user questions is best effort on Slack. For a "guaranteed" response please email
    envoy-users@ per the guidance in the following linked thread.

Please see this email thread
for information on email list usage.

Contributing Copy Chapter

Contributing to Envoy is fun and modern C++ is a lot less scary than you might think if you don't
have prior experience. To get started:

• Contributing guide
• Beginner issues
• Build/test quick start using docker
• Developer guide
• Consider installing the Envoy development support toolchain, which helps automate parts of the development process, particularly those involving code review.
• Please make sure that you let us know if you are working on an issue so we don't duplicate work!

Community Meeting Copy Chapter

The Envoy team has a scheduled meeting time twice per month on Tuesday at 9am PT. The public
Google calendar is here. The meeting will only be held
if there are agenda items listed in the meeting
minutes. Any member of the community should be able to
propose agenda items by adding to the minutes. The maintainers will either confirm
the additions to the agenda, or will cancel the meeting within 24 hours of the scheduled
date if there is no confirmed agenda.

Security Copy Chapter

Security Audit Copy Section

There has been several third party engagements focused on Envoy security:

• In 2018 Cure53 performed a security audit, full report.
• In 2021 Ada Logics performed an audit on our fuzzing infrastructure with recommendations for improvements, full report.

Reporting security vulnerabilities Copy Section

If you've found a vulnerability or a potential vulnerability in Envoy, please
open a GitHub Security Advisory.
This is the preferred reporting channel, as the reports can be triaged directly on GitHub.

Alternatively, you may email [email protected].

For further details please see our complete security release process.

OSS fuzzing Copy Section

ppc64le builds Copy Section

Builds for the ppc64le architecture are not covered by the envoy security policy. The ppc64le architecture is currently best-effort and not maintained by the Envoy maintainers.

Other builds Copy Section

Releases Copy Chapter

For further details please see our release process.

File: docs/README.md Copy Chapter

Building documentation locally

There are two methods to build the documentation, described below.

In both cases, the generated output can be found in generated/docs.

Building in an existing Envoy development environment Copy Chapter

If you have an existing Envoy development environment, you should have the necessary dependencies and requirements and be able to build the documentation directly.

If using the Docker build container, you can run:

./ci/do_ci.sh docs

By default configuration examples are going to be validated during build. To disable validation,
set SPHINX_SKIP_CONFIG_VALIDATION environment variable to true:

SPHINX_SKIP_CONFIG_VALIDATION=true ./ci/do_ci.sh docs

If not using the Docker build container, you can run:

bazel run --@envoy//tools/tarball:target=//:html @envoy//tools/tarball:unpack "$PWD"/generated/docs/

Using the Docker build container to build the documentation Copy Chapter

If you do not have an existing development environment, you may wish to use the Docker build
image that is used in continuous integration.

This can be done as follows:

./ci/run_envoy_docker.sh './ci/do_ci.sh docs'

To use this method you will need a minimum of 4-5GB of disk space available to accommodate the build image.

Creating a Pull Request with documentation changes

When you create a Pull Request the documentation is rendered by Azure Pipelines.

To do this:

1. Open docs job in Azure Pipelines.
2. Navigate to "Upload Docs to GCS" log.
3. Click on the link there.

How the Envoy website and docs are updated

The docs are published dynamically by Netlify on every commit to main. This process is handled by the
envoy-website repo

For tagged commits the docs are built statically by the archive repo,
which in turn triggers a rebuild of the website.

2. Official Technical Reference & Guides (envoyproxy/envoy-website) Copy Chapter

Envoy website

This is the repo for the Envoy website.

The website is built with bazel using Pelican and Sphinx.

The site is deployed to Netlify.

Envoy's documentation for release versions is stored in https://github.com/envoyproxy/archive/.

Contribute content to the website Copy Chapter

Site data Copy Section

Site data is stored (or created) in yaml files in the site/data directory.

Add adopter logo Copy Section

Envoy is happy to recognize projects that use the software in production.

These are not intended to be an advertisement, but a show of support for the project.

All supporting organizations will be listed in alphabetical order.

To be added to our adopter list, you must meet at least 2 of these criteria:

• Be a participant and active contributor in the community, eg:
  • contributing code
  • raising or resolving issues
  • sponsoring EnvoyCon
• Publicly disclose your usage of Envoy, eg:
  • talk
  • blog
  • CNCF case study
  • social media
• Have an existing Envoy maintainer vouch for and approve your pull request

To add your logo, please send a pull request.

Envoy website development Copy Chapter

Sphinx is used to build the latest docs, and Pelican is used to assemble the static files into a site.

The build process is managed by bazel to ensure reproducible builds and manage external data.

All content, data and customizations are stored in the site directory

Build using Docker Copy Section

This is the recommended way to build the site.

The composition is designed to make use of a Bazel cache on your host system.

Docker: export your `UID`

By default Docker cannot see your user's UID, so you need to export it to run the container build.

This ensures that any files created inside the container - the site build and any cache files - are owned
by the host user.

$ export UID

Docker: build the website

$ docker compose up --build -d website

This will take some time on first run - you can tail the logs with:

$ docker compose logs -f

Once the build has completed the website should be available at http://localhost:8000.

If you are not running the automatic rebuild and you make changes you can rebuild the site with:

$ docker compose run build

Build the site on your host machine Copy Section

If you would prefer not to use Docker you can build directly on your host machine.

Host: install bazel

The expected version of Bazel can be seen in .bazelversion.

It is recommended to install Bazel with Bazelisk as this will pull in the
correct Bazel version.

If you have Yarn installed you can install Bazelisk with that.

From inside your local copy of the envoy-website repository, run:

$ yarn

Host: install a compiler

You will need a compiler (clang or GCC) and some related dev tools installed to build the docs.

For example, on a Debian-based system, these can be installed with:

$ apt get install build-essential

If you build without the docs, you can ignore this requirement.

Host: build the website

$ ./build-website.sh

Tips for site development Copy Section

Automatically rebuild during development

The site can be made to auto-rebuild when changes occur in the site/ directory.

If you are using Docker you can trigger this by setting the following in your environment,
before bringing up the Docker composition:

$ export BUILDER=live
$ docker compose up --build -d website

If you are building on your host you can just run the rebuild script directly:

$ ./rebuild.sh ./site ./build-website.sh

Build without the docs

If you only need the non-docs parts of the website to be built, set the following environment
variable.

Set this before building in Docker or on your host:

$ export BAZEL_BUILD_OPTIONS="--config=nodocs"

Debug build

You can enable richer logging.

Set the following environment variable before building in Docker or on your host:

$ export DEBUG=1

Put frequently used env vars in `.env`

Docker compose will source the .env file before running.

For example, if you always want the site to build "live", add the following to .env

export BUILDER=live