Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds Initial Design Doc #5

Closed
wants to merge 1 commit into from
Closed

Adds Initial Design Doc #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions docs/DESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Introduction

For many application developers, [Envoy][envoy] requires too much cognitive load to support simple proxy
use cases. For example, users must understand concepts such as filters, clusters, etc. to simply proxy
HTTP requests to a personal static website. The goal of Envoy Gateway is to simplify the user experience
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Once finalized, I'd reference the GOALS.md document here instead of repeating the overarching goal.

while also supporting xDS for more advanced proxy use cases. Envoy Gateway provides:

- The ability for users to run Envoy and proxy traffic to an application with minimal intervention and
understanding of Envoy, e.g. [xDS][xds].
- An API to support simple proxy use cases while directly supporting xDS to handle advanced proxy use cases.
Copy link
Contributor

@LukeShu LukeShu Apr 14, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know that directly exposing raw xDS is the proper thing here.

Emissary used to support an analogous envoy_override feature where the user could specify bits of raw Envoy config (this actually predates Emissary using xDS; Envoy 1.4 introduced xDS just a month or two before Emissary added envoy_override--but conceptually it was the same thing as exposing direct xDS). This turned out to be unsupportable--it required the user to have an understanding of exactly what config Emissary would be generating internally in order to not conflict with it; this understanding would often need to change between versions of Emissary. And even if you had this understanding it was far too easy to write a config that would end up subtly breaking what Emissary was doing internally.

My first inclination is to figure out which kinds of advanced cases we are willing to support and define our own API that is somewhere between the simple Gateway API and full-blown xDS. But I recognize that defining yet another idiosyncratic thing is bad, and so maybe vanilla xDS is the way to go, but in that case it should IMO be a carefully selected subset of xDS that we expose; not all of xDS.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here's how Im thinking about xDS

  • Why should EG support xDS - imho EG's simple API will attempt to cover most (80%) cases but won't be able to cover the entire API gateway feature set (rest 20%) thats available in Envoy, which some user might need, and EG will always catch up with Envoy. At that point, the user is leveraging EG for its config distribution and platform support (like K8s) capabilities.
  • What should EG support - thinking out loud
    • Merge - merge Envoy subs resources / patches to existing EG generated resources to drive contextual changes to the Envoy resources.
    • Add - add new Envoy resources
  • How should EG support - Native Gateway API extensions .
    We can add a disclaimer to the docs mentioning that we cannot guarantee correctness and stability, and we could also make this an opt-in feature

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@LukeShu I agree with your feedback, exposing full xDS can cause many unsupportable situations. As @arkodg mentions, Gateway API extension points are tagged as "vendor-specific" and are not supported by the community.

@mattklein123 L10 comes from the feedback you provided. Let us know if you have any add'l thoughts on this thread.

- Run in Kubernetes and non-Kubernetes environments, e.g. on a Virtual Machine.
- Others?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extension points?
Apart from ext_authz, what kind of plugin interface or extension points will the Envoy Gateway design support?

Copy link
Contributor

@LukeShu LukeShu Apr 21, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"ext_authz and friends"; RateLimit service and Logging Service and... :)

... but I'm not sure what kind of extension points we want other than such plugin services.


## Design

Envoy Gateway consists of the following:

- __API Definitions:__ Provides a RESTful API to consumers for managing Envoy and routing traffic between
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unless "RESTful API" is referring to a Kubernetes API (the apiserver is mostly RESTful after all), I don't agree with this being the "main" thing. IMO the API should be defined in terms of Kubernetes resources, and by default it should fetch them by talking to the apiserver; non-Kubernetes operation should the ability to feed in those same resources via a non-apiserver mechanism.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@LukeShu can you please elaborate, it sounds like you would like a CRUD API Server for EG resources which could be RESTful or gRPC based, is that right ?

Copy link
Contributor Author

@danehans danehans Apr 20, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@LukeShu correct me if I'm wrong but I believe you're referring to the EG API following these API concepts. For non-k8s operations, the same resources should be used. For example, the path watcher config source from here would use the same resources as the Kubernetes config source.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At the time I wrote it, yeah it sounds like @arkodg got what I meant: Defining it in terms of EG resources, and then having some CRUD API to manage those resources. At the time I didn't have a real opinion on what that CRUD API looked like; REST or gRPC or whatever.

But I do have a few opinions now; see comments I've put on the Google Doc. (in particular, the one in this thread: https://docs.google.com/document/d/1riyTPPYuvNzIhBdrAX8dpfxTmcobWZDSYTTB5NeybuY/edit?disco=AAAAXpg4H9s)

[upstreams and downstreams][terminology].
- __Control Plane:__ Manages Envoy based on intent described by administration API definitions.
- __Managed Proxy:__ Proxies requests and responses based on intent described by routing API definitions.

![Design Diagram Placeholder](../images/design.png?raw=true "Envoy Gateway Design")

## API Definitions

Provides a RESTful API to consumers for managing Envoy and traffic routing.

## Control Plane

The Control Plane...
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps for this section, perhaps not. Given one of the goals is a "simplified deployment" (ref #7), let's add emphasis on a "single, all-encompassing pod deployment" as the runnable components in the Envoy Gateway architecture.


## Managed Proxy

Proxies requests and responses based on intent described by routing API definitions.

[envoy]: https://www.envoyproxy.io/
[xds]: https://github.com/envoyproxy/envoy/tree/main/api
[gateway_api]: https://gateway-api.sigs.k8s.io/
[terminology]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/intro/terminology
[go_cp]: https://github.com/envoyproxy/go-control-plane