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 goals doc #7

Merged
merged 14 commits into from
Apr 28, 2022
Merged

Adds initial goals doc #7

Changes from 4 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
89cf342
Adds initial goals doc
Apr 13, 2022
6b492ac
Populates content from the google docs, comments and discussions into…
Apr 18, 2022
4884ca3
Update GOALS.md
alexgervais Apr 19, 2022
77651b5
Splits the goals into "Expressive API" and "Simplified deployment"
Apr 21, 2022
12d39a5
Revised personas, direct xDS references and misc wording
Apr 22, 2022
9fd29b1
GOALS: "the Envoy Gateway" → "Envoy Gateway"
LukeShu Apr 27, 2022
e7dd2dd
GOALS: "the Envoy Proxy" → "Envoy Proxy"
LukeShu Apr 27, 2022
c721087
GOALS: Fuss with wording for readability
LukeShu Apr 27, 2022
e21312a
GOALS: Simplify the app-dev persona
LukeShu Apr 27, 2022
8792c73
GOALS: Try to better highlight that it's Gateway API
LukeShu Apr 27, 2022
5172fcc
GOALS: Use just "the API" rather than "the [adjective] API" for reada…
LukeShu Apr 27, 2022
eb0db71
GOALS: Mention vendor-extensibility in the intro paragraph
LukeShu Apr 27, 2022
bd5bc15
GOALS: Have a go at "batteries included"
LukeShu Apr 27, 2022
f0d486f
GOALS: Fix a sentence with mixed tense
LukeShu Apr 28, 2022
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
80 changes: 80 additions & 0 deletions GOALS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Goals

The high-level goal of the Envoy Gateway project is to attract more users to Envoy by lowering barriers to adoption
through expressive, extensible, role-oriented APIs that support a multitude of ingress and L7/L4 traffic routing
Copy link
Contributor

Choose a reason for hiding this comment

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

It appears that we need to add egress to the goals, xref.

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm leaving it out for now, given the reaction in yesterday's call.

use cases.

## Objectives

### Expressive API
The Envoy Gateway project will expose a simplified and expressive API, with defaults set for many capabilities.

This expressive API will make Envoy accessible to more users, especially application developers, and make Envoy a
stronger option for "getting started" as compared to other proxies. Application developers will use a simple API
LukeShu marked this conversation as resolved.
Show resolved Hide resolved
out of the box without needing to understand in-depth concepts of Envoy Proxy or use OSS wrappers.
The expressive API will use familiar nouns that [expert personas](#personas) understand.
LukeShu marked this conversation as resolved.
Show resolved Hide resolved

The core full-featured Envoy APIs (xDS) will remain available for those who need more capability and for those who
add functionality on top of Envoy, such as commercial API gateway products.
Copy link
Contributor

Choose a reason for hiding this comment

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

Should s/commercial API gateway products/commercial API management products/ since EG is an API gateway? I feel like EG does not compete with commercial API Gateways, e.g. Tyk, but will not compete with commercial API management systems, e.g. Ambassador Cloud, Edge Stack, etc.

Copy link
Contributor

Choose a reason for hiding this comment

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

I would call Edge Stack an API gateway product; it is essentially Emissary plus (1) an ext_authz service that provides additional gateway-related features, and (2) a service that is a fork of envoyproxy/ratelimit.

Copy link
Member

Choose a reason for hiding this comment

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

on top of Envoy Gateway ?


This expressive API will not be implemented by the Envoy Proxy, but rather an officially supported translation layer
Copy link
Contributor

Choose a reason for hiding this comment

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

Since we've already made reference to the API as being simple, expressive, etc, IMHO this paragraph reads better if follow-on references to the API are "the API".

Copy link
Contributor

Choose a reason for hiding this comment

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

I almost included that in 5172fcc, but decided to leave this sentence as-is. There are plenty of APIs that are implemented in Envoy Proxy itself, so in this sentence I think it makes sense to leave in "expressive" (as in the section header) as a scope-limiter for the sentence.

on top.

### Simplified deployment
The Envoy Gateway will simplify how Envoy is deployed and managed, allowing application developers to focus on
delivering core business value.

Making an application accessible needs to be a trivial task for any developer. Similarly, infrastructure administrator
LukeShu marked this conversation as resolved.
Show resolved Hide resolved
will enjoy a simplified deployment model that doesn't require extensive knowledge of the solution's architecture to
LukeShu marked this conversation as resolved.
Show resolved Hide resolved
operate.

### All environments
The Envoy Gateway will support running natively in Kubernetes environments as well as non-Kubernetes deployments.

Initially, Kubernetes will receive the most focus, with the aim of having the Envoy Gateway become the de facto
standard for Kubernetes ingress supporting the [Gateway API](https://gateway-api.sigs.k8s.io/).
Copy link
Contributor

Choose a reason for hiding this comment

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

It seems a little weird to me that this is the only mention of the Gateway API. If the point is to use the Gateway API as the starting point, why not mention that earlier? Is there some context here I missed?

Copy link
Contributor

Choose a reason for hiding this comment

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

@alexgervais I agree with @youngnick. The doc has the ## Expressive API section that we should clearly state this project intends to leverage Gateway API to provide expressive, extensible, role-oriented APIs. Refer to how Gateway API is highlighted in the recent Istio CNCF announcement.

Copy link
Contributor

Choose a reason for hiding this comment

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

I've attempted to address this in 8792c73.

Additional goals include multi-cluster support and various runtime environments.

### Extensibility
Vendors will have the ability to provide value-added products built on the Envoy Gateway foundation.

It will remain easy for end-users to use common Envoy Proxy extension points such as providing an implementation for
LukeShu marked this conversation as resolved.
Show resolved Hide resolved
authentication methods and rate-limiting. For advanced use cases, users will have the ability to switch to using xDS
directly.
LukeShu marked this conversation as resolved.
Show resolved Hide resolved

Since a general-purpose API cannot address all use cases, the Envoy Gateway will provide additional extension points
for flexibility. As such, the Envoy Gateway will form the base of vendor-provided managed control plane solutions,
LukeShu marked this conversation as resolved.
Show resolved Hide resolved
allowing vendors to shift to a higher management plane layer.

Copy link
Contributor

Choose a reason for hiding this comment

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

Can we add a point about "Stronger Envoy out of the box" - which highlights incorporating envoy native auxiliary control planes such as the envoy ratelimit service as well as core control plane libraries such as the go control plane

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I feel like "Stronger Envoy out of the box" is aligned with the simplification we want to push forward, but goes against extensibility. We want a "batteries included" solution, but are still unsure about which batteries.

Copy link
Contributor

Choose a reason for hiding this comment

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

yeah can we add batteries included into the goals doc. https://github.com/envoyproxy/ratelimit seems to be one, there might be more in the future such as an OIDC service or TLS Issuer service.

Copy link
Contributor

Choose a reason for hiding this comment

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

@alexgervais I like the "batteries included" analogy. Beyond the points above, the details behind "batteries included" can be 1. sensible defaults with the ability to override 2. Envoy infra provisioning, e.g. k8s service, deployment, etc. 3. should we include a self-signed CA to simplify TLS termination (for non-prod use) 4. improved ops through API status conditions, 5. Others?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Do we want to provide details about which batteries are included? I feel we need validation from the governance group in order to make sure we have an agreement from all vendor affiliations before committing to any of them.

Copy link
Contributor

Choose a reason for hiding this comment

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

@alexgervais I don't think we need to detail the battery details ;-) That can come in the future if needed. I just wanted to provide thoughts related to your "... but are still unsure about which batteries."

Copy link
Contributor

Choose a reason for hiding this comment

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

wdyt

Batteries Included

The Envoy Gateway project will strive to include any additional infrastructure components required by users
to fulfill their Ingress and APIGateway feature needs. This list can be exhaustive so as a starting point, the project will natively include any components that are part of the Envoy ecosystem (such as ratelimit service) or introduce new components for features that historically couldn't be implemented in Envoyproxy such as ACME support.

Copy link
Contributor

Choose a reason for hiding this comment

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

cc @mattklein123

Copy link
Contributor

Choose a reason for hiding this comment

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

I suggest we keep the goals as high-level as possible. Maybe just keep the first sentence from ^

The Envoy Gateway project plans to include any additional infrastructure components required by users
to fulfill their Ingress and API gateway needs.

The design doc can xref the example components provided above. When the design doc is merged, we will create GH issues to track the desire to add these specific components.

Copy link
Contributor

Choose a reason for hiding this comment

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

I hope I've captured the intent in bd5bc15. I used some of the specifics from #7 (comment) because while I agree that we should keep things as high-level as possible, I think that 1 sentence on its own isn't sufficiently clear.

## Non-objectives

### Cannibalize vendor models
Vendors need to have the ability to drive commercial value, so the goal is not to cannibalize any existing vendor
monetization model, though some vendors may be affected by it.

arkodg marked this conversation as resolved.
Show resolved Hide resolved
### Disrupt current Envoy usage patterns
The Envoy Gateway is purely an additive convenience layer and is not meant to disrupt any usage pattern of any user
with Envoy Proxy, xDS, or go-control-plane.

## Personas
LukeShu marked this conversation as resolved.
Show resolved Hide resolved
_In order of priority_

### 1. Application developer
The application developer spends the majority of their time developing business logic code. They require API gateway
functionalities to expose their applications. Using expressive configurations, they will define request routes,
TLS termination, rate limits, authentication and authorization policies, etc.
LukeShu marked this conversation as resolved.
Show resolved Hide resolved

### 2. Infrastructure administrators
The infrastructure administrators are responsible for the installation, maintenance, and operation of
API gateways appliances in infrastructure, such as CRDs, roles, service accounts, certificates, etc.
Infrastructure administrators support the needs of application developers by deploying instances of the Envoy Gateway.
LukeShu marked this conversation as resolved.
Show resolved Hide resolved

### 3. Envoy developer
The Envoy developer has the ability to quickly develop and test out new or improved features in Envoy proxy,
that later can be graduated into a user-friendly gateway feature.
arkodg marked this conversation as resolved.
Show resolved Hide resolved

## Other

Further discussions and drafts of the project's goals can be found in this document:
https://docs.google.com/document/d/18MuuV9Qzij7Z1OeZ6GrOURKzVi9D0qv2SgvFPELM4gc/edit
Copy link
Contributor

Choose a reason for hiding this comment

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

@alexgervais thanks for getting this started. The referenced goals doc is higher-level and a bit more wordy than what I'd like to see in this repo, but it does provide a good reference point for us to develop the GOALS.md. Here are a few goals that I noted from the kick-off meeting:

  1. Make Envoy easy to consume for simple use cases. For example, provide an API that abstracts xDS APIs, e.g. route HTTP/TLS requests for https://foo.example.com/bar to a backend Kubernetes service.
  2. Have Envoy Gateway become the de facto standard for Kubernetes ingress.
  3. Envoy Gateway should be expressive. For example, expose xDS APIs to support advanced gateway use cases instead of trying to replicate all the functionality provided by xDS.
  4. Support multiple personas, e.g. Infra Admins create Envoy Gateway/Proxy instances while App Devs create routing rules to their backend apps.
  5. Support various runtime environments with Kubernetes being the initial focus.
  6. Envoy Gateway should be extensible. For example, users should be allowed to use rate limiting solution "Foo" instead of envoyproxy/ratelimit.

As you can see above, I highlighted "simple", "expressive", and "extensible". IMHO these words should be the core principals of the project.

@mattklein123 @arkodg @youngnick feel free to add any goals as comments to this PR so we can get the GOALS.md merged.

Copy link
Member

Choose a reason for hiding this comment

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

This all sounds reasonable to me. One thing that we didn't discuss in the meeting is I would personally like multi-cluster to be an explicit medium-term goal. I think this is a critical feature in any real product deployment.

Copy link
Contributor

Choose a reason for hiding this comment

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

@mattklein123 I agree 100%, especially with it being a medium-term goal ;-) I created #9 to capture this, PTAL. @alexgervais please ensure that the GOAL.md specifies this requirement.

Copy link
Contributor

Choose a reason for hiding this comment

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

@alexgervais IMO we should drop this section and the linked gdoc.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@danehans agreed. I'll move it to the PR description so we still have a reference somewhere.