Project: Envoy (Orchestration & Management / Service Proxy)
File: REPO_LAYOUT.md

This is a high level overview of how the repository is laid out to both aid in code investigation, as well as to clearly specify how extensions are added to the repository. The top level directories are: : Configuration for . : Envoy data plane API. : Configuration for Envoy's use of . : Scripts used both during CI as well as to build Docker containers. : Example Envoy configurations. : End user facing Envoy proxy and data plane API documentation as well as scripts for publishing final docs during releases. : Larger Envoy examples using Docker and Docker Compose. : "Public" interface headers for "core" Envoy. In general, these are almost entirely 100% abstract classes. There are a few cases of not-abstract classes in the "public" headers, typically for performance reasons. Note that "core" includes some "extensions" such as the HTTP connection manager filter and associated functionality which are so fundamental to Envoy that they will likely never be optional from a compilation perspective. : Envoy's hot restart wrapper Python script. : Some templates for reporting security issues of Envoy. Historical security issues can also be found here. : Source code for core Envoy as well as extensions. The layout of this directory is discussed in further detail below. : Development support scripts (pre-commit Git hooks, etc.) : Test code for core Envoy as well as extensions. The layout of this directory is discussed in further detail below. : Miscellaneous tools that have not found a home somewhere else. : Core Envoy code (not specific to extensions) that is also not specific to a standalone server implementation. I.e., this is the code that could be used if Envoy were eventually embedded as a library. : Miscellaneous developer/design documentation that is not relevant for the public user documentation. : Code specific to building the final production Envoy server binary. This is the only code that is not shared by integration and unit tests. : Extensions to the core Envoy code. The layout of this directory is discussed in further detail below. : Code specific to running Envoy as a standalone server. E.g, configuration, server startup, workers, etc. Over time, the line between `common/` and `server/` has become somewhat blurred. Use best judgment as to where to place something. Not every directory within test is described below, but a few highlights: Unit tests are found in directories matching their equivalents. E.g., , , and . Extension unit tests also match their source equivalents in . holds end-to-end integration tests using roughly the real Envoy server code, fake downstream clients, and fake upstream servers. Integration tests also test some of the extensions found in the

Note that in the future, we would like to allow integration tests that are specific to extensions and are not required for covering "core" Envoy functionality. Those integration tests will likely end up in the directory but further work and thinking is required before we get to that point. contains mock implementations of all of the core Envoy interfaces found in . Other directories include tooling used for configuration testing, coverage testing, fuzz testing, common test code, etc. We maintain a very specific code and namespace layout for extensions. This aids in discovering code/extensions, and allows us specify extension owners in . All extensions are either registered in or . The former is for extensions that cannot be removed from the primary Envoy build. The latter is for extensions that can be removed on a site specific basis. See for how to compile out extensions on a site specific basis. Note that by default extensions should be removable from the build unless there is a very good reason. These are the top level extension directories and associated namespaces: : Access log implementations which use the `Envoy::Extensions::AccessLoggers` namespace. : Bootstrap extensions which use the `Envoy::Extensions::Bootstrap` namespace. : Cluster extensions which use the `Envoy::Extensions::Clusters` namespace. : Compression extensions which use `Envoy::Extensions::Compression` namespace. : Fatal Action extensions which use the `Envoy::Extensions::FatalActions` namespace. : HTTP L7 filters which use the `Envoy::Extensions::HttpFilters` namespace. : Listener filters which use the `Envoy::Extensions::ListenerFilters` namespace. : L4 network filters which use the `Envoy::Extensions::NetworkFilters` namespace. : Access log formatters which use the `Envoy::Extensions::Formatters` namespace. : Custom gRPC credentials which use the `Envoy::Extensions::GrpcCredentials` namespace. : Custom health checkers which use the `Envoy::Extensions::HealthCheckers` namespace. : Internal Redirect extensions which use the `Envoy::Extensions::InternalRedirect` namespace. : QUIC extensions which use the `Envoy::Quic` namespace. : Resource monitor extensions which use the `Envoy::Extensions::ResourceMonitors` namespace. : Retry extensions which use the `Envoy::Extensions::Retry` namespace. : Stat sink implementations which use the `Envoy::Extensions::StatSinks` namespace. : Tracers which use the `Envoy::Extensions::Tracers` namespace. : Transport socket implementations which use the `Envoy::Extensions::TransportSockets` namespace. : Upstream extensions use the `Envoy::Extensions::Upstreams` namespace. : Watchdog extensions use the `Envoy::Extensions::Watchdog` namespace. : Rate limit descriptor extensions use the `Envoy::Extensions::RateLimitDescriptors` namespace. Each extension is contained wholly in its own namespace. E.g., `Envoy::Extensions::NetworkFilters::Echo`. Common code that is used by multiple extensions should be in a `common/` directory as close to the extensions as possible. E.g., for common code that is used by both HTTP and network filters. Common code used only by two HTTP filters would be found in `filters/http/common/`. Common code should be placed in a common namespace. E.g., `Envoy::Extensions::Filters::Common`. This directory contains contrib extensions. See for more information. : The default executable for contrib. This is similar to the `envoy-static` target but also includes all contrib extensions, and is used to produce the contrib image targets. : The rest of this directory mirrors the layout. Contrib extensions are placed here.