Skip to content

docs: add provisional GEP for Gateway API Firewall Support #4148

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add provisional GEP for Gateway API Firewall Support #4148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
72d304b
docs: add provisional GEP for Gateway Firewall Support
shaneutt Oct 6, 2025
ea04371
docs: add note about potential outcomes for 3614
shaneutt Oct 8, 2025
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
94 changes: 94 additions & 0 deletions geps/gep-3614/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# GEP-3614: Firewall

* Issue: [#3614](https://github.com/kubernetes-sigs/gateway-api/issues/3614)
* Status: Provisional

## TLDR

The ability to attach firewall rules for ingress L3, L4 and L7 Gateway traffic.

## Motivation

`Gateways` are commonly exposed to the internet, which puts them as risk of
attack. Internal networks can become compromised as well. We should provide
tooling, documentation and best-practices for users to restrict and control
access to their `Gateways`.

### Definitions

* "Firewall Engine" - A processor of request payloads and applies rulesets to
the contents to identify malicious, anomalous or otherwise unwanted traffic.
These are generally at the front of the request path, and may be attached to a
`Gateway` as a sidecar, integrated natively as part of the `Gateway`, or
deployed in front of the `Gateway` as part of the networking path.

### User Stories
Copy link
Contributor

@howardjohn howardjohn Oct 7, 2025

Choose a reason for hiding this comment

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

I am concerned about the ability to actually fulfill the goals in this GEP. Just from reading the title, I was worried about running into the lowest-common-denominator problem: that there is almost no overlap between each firewall configuration surface, so we end up with an API that is not useful (or, we end up debating the API surface indefinitely).

Gateway API actually does already have a solution for this, with policy attachment. I suspect you may disagree, but when we are faced with a problem set that doesn't have much overlap, policy attachment of implementation specific policies is a much better experience for users than attempting to make an API that doesn't work.

After reading the GEP, my concerns are far greater, though. This set of goals is impossible to reasonable tackle. While the title if "Firewall", in typical products the feature set here actually spans 3-4 API surfaces: WAF, Authorization (typically separate from WAF!!), rate limiting, auditing, DLP. And I saw in the AI WG, LLM guardrails was also something of interest as part of this effort (which, again, differs from traditional WAF). I am very worried we are biting off way to much work with this effort and it will make it impossible to proceed.

Just as an anecdote, even just rate limiting is ridiculously complex to design an API around. I suspect it would be harder than BackendTLSPolicy was...

Copy link
Member Author

@shaneutt shaneutt Oct 7, 2025

Choose a reason for hiding this comment

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

I am concerned about the ability to actually fulfill the goals in this GEP. Just from reading the title, I was worried about running into the lowest-common-denominator problem: that there is almost no overlap between each firewall configuration surface, so we end up with an API that is not useful (or, we end up debating the API surface indefinitely).

I am anticipating that we wont actually try to add significant API surface for this, see this conversation for some context.

In any case, I'm open to the possibility that this GEP moves to Withdrawn if we can't find the right stakeholders, and common surface.

Gateway API actually does already have a solution for this, with policy attachment. I suspect you may disagree, but when we are faced with a problem set that doesn't have much overlap, policy attachment of implementation specific policies is a much better experience for users than attempting to make an API that doesn't work.

This is getting into the "How?" we do things, which we're not ready for yet.

After reading the GEP, my concerns are far greater, though. This set of goals is impossible to reasonable tackle. While the title if "Firewall", in typical products the feature set here actually spans 3-4 API surfaces: WAF, Authorization (typically separate from WAF!!), rate limiting, auditing, DLP. And I saw in the AI WG, LLM guardrails was also something of interest as part of this effort (which, again, differs from traditional WAF). I am very worried we are biting off way to much work with this effort and it will make it impossible to proceed.

I will make sure you are considered a stakeholder for reviews, and that your concerns are incorporated 👍

Just as an anecdote, even just rate limiting is ridiculously complex to design an API around. I suspect it would be harder than BackendTLSPolicy was...

Agreed.

This is getting into the "How?", which we will get stuck on if we discuss this now. The important thing for this iteration is to align on the motivation and goals at a high level. If we do that, and then we move to the implementation details and we simply can not produce something that's effective within a reasonable scope, and is supported by multiple stakeholders, it is OK to consider this Withdrawn and keep it for posterity so that the community knows we looked into it, and what our reasons were for not continuing.

Copy link
Contributor

@mikemorris mikemorris Oct 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I am anticipating that we wont actually try to add significant API surface for this

In this case, I'm also wondering how this provides value that is not already available through HTTPRoute extensionRef custom filters or policy attachment, or what is missing from the current extension points to support this use case?

Something like first-class support for OWASP CRS configuration rules to provide WAF functionality in Gateway API might feel contentious and a scope stretch, but would at least feel more aligned with standardizing functionality within the Gateway API specification.

This does feel like it could be a valuable proprietary feature or product positioning for a Gateway API implementation, but I don't really see a purpose-built extension point enabling this as appropriate for the spec, when existing generic extension points may be sufficient (and potentially support the same or related use cases, such as using WASM modules to mutate or drop requests or responses as @jcchavezs mentioned in #4148 (comment)).

Copy link
Member Author

@shaneutt shaneutt Oct 7, 2025

Choose a reason for hiding this comment

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

In this case, I'm also wondering how this provides value that is not already available through HTTPRoute
extensionRef custom filters

Filters could be viable, we need to decide. This is an important part of the exercise of this GEP. There could be challenges. One challenge is the should language around the order of processing filters, which is not conducive to security systems.

or policy attachment

Policy Attachment could be viable, we need to decide. This too is an important part of the exercise. There will be challenges, as it comes with many caveats. Ordering policies is one thing that can be challenging to get right, among others.

We are into implementation details however.

I want to be extra clear that if we get to the "How?" and there is no consensus, I am not shy about slapping a Withdrawn on it and providing a written explanation as to why. That way people who are looking at least know that we've tried, what we've tried, and what the difficulties are.

If possible however, the bare minimum I would like for this effort to result in a memorandum that provides some guidance to implementations that want to integrate firewalls with their Gateways, as I see this as a pretty common desire from users.

Copy link
Member Author

@shaneutt shaneutt Oct 8, 2025

Choose a reason for hiding this comment

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

An explicit note about the potential to not change any API specification at all has been added in b195370. Please let me know if this seems reasonable for the purposes of moving forward with the initial PR, or if you have further concerns.

Copy link
Member

@robscott robscott Oct 8, 2025

Choose a reason for hiding this comment

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

My concern here is that we probably shouldn't merge something this as provisional unless we can think of one or more plausible ways that we could implement it in Gateway API. While I agree that we should generally focus on user stories first to ensure we get to the right implementation details, I also want to ensure that we have a viable path forward before we go too far here.

I think this is a good discussion to have, I just think the better outcome here might be to have a page/doc somewhere where we list common categories of Gateway API extensions such as firewalls, and describe why we don't think they're in scope for Gateway API at the current point in time, potentially with link(s) to discussion(s) with more context. If we have a GEP for each instance like this, I think we could get pretty quickly overloaded with GEPs.

Copy link
Member Author

@shaneutt shaneutt Oct 9, 2025

Choose a reason for hiding this comment

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

My concern here is that we probably shouldn't merge something this as provisional unless we can think of one or more plausible ways that we could implement it in Gateway API. While I agree that we should generally focus on user stories first to ensure we get to the right implementation details, I also want to ensure that we have a viable path forward before we go too far here.

I'm not sure why this is a concern: we've made it clear that one could use policy attachment, or possibly filters at a bare minimum. There's seems to be precedent in that cloud providers like GKE do this today.

I think this is a good discussion to have, I just think the better outcome here might be to have a page/doc somewhere where we list common categories of Gateway API extensions such as firewalls, and describe why we don't think they're in scope for Gateway API at the current point in time, potentially with link(s) to discussion(s) with more context.

I suppose that could be an outcome but it feels pretty arbitrary considering there's already implementations out there doing this (e.g. GKE).

If we have a GEP for each instance like this, I think we could get pretty quickly overloaded with GEPs.

If limiting the number of GEPs we have as a project becomes a common goal, we should find a neutral mechanism to start and not apply it in a procrustean manner to a mid-flight effort.

Copy link
Contributor

@mikemorris mikemorris Oct 9, 2025

Choose a reason for hiding this comment

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

Taking this back to specifics, I'm seeing:

One challenge is the should language around the order of processing filters, which is not conducive to security systems.
Ordering policies is one thing that can be challenging to get right, among others.

Which reads to me as ordering is a core missing capability for our extension points. FWIW I don't particularly like the semantics for priority ordering over in AdminNetworkPolicy (it generally feels too complicated and easy to footgun or create conflicting/undefined states), but I'd be more open to a GEP introducing optional ordering functionality for those features, citing specific firewall behavior expectations as a user story requiring it, than what feels like an overly-broad product story GEP potentially spanning many disparate features (on the scale of GAMMA or WG AI Gateway from my perspective).

(I'm not concerned with "too many GEPs" FWIW, but I do want to try to constrain the focus to concrete enhancements rather than biting off too big a scope without the intent of actually bringing the solution into the spec.)

Copy link
Member Author

@shaneutt shaneutt Oct 9, 2025

Choose a reason for hiding this comment

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

Which reads to me as ordering is a core missing capability for our extension points.

Yes.

FWIW I don't particularly like the semantics for priority ordering over in AdminNetworkPolicy (it generally feels too complicated and easy to footgun or create conflicting/undefined states), but I'd be more open to a GEP introducing optional ordering functionality for those features, citing specific firewall behavior expectations as a user story requiring it, than what feels like an overly-broad product story GEP potentially spanning many disparate features (on the scale of GAMMA or WG AI Gateway from my perspective).

I had a similar thought. Not sure it's only this, but this does seem like an area to focus. Since we seem to agree on that, I have added that to the notes for follow-up.

(I'm not concerned with "too many GEPs" FWIW, but I do want to try to constrain the focus to concrete enhancements rather than biting off too big a scope without the intent of actually bringing the solution into the spec.)

👍


* As an application developer, I want to allow specific IPs to access my
application.
* As an application developer, I want to block or allow requests based on
headers; e.g. allow or deny specific user-agents.
* As a gateway operator I want to be able to identify and block and log
malformed HTTP requests before they reach backend applications.
* As a gateway operator I want to be able to provide my own signature-based
detection rulesets to spot patterns of known malicious traffic and block and
log them, updating those rules dynamically over time.
* As a gateway operator I want to attach complete rulesets maintained by
upstream standards bodies to block well known common threats and dynamically
update for new threats over time.
* As a gateway operator I want to detect anomalies in traffic (which may or
may not be conclusively malicious) and log the requests with the option to
block them as well.
* As a cluster operator I want to be able to block traffic to gateways from
specific geographical regions, or only allow specific regions.
* As a cluster operator I want to be able to rate limit traffic to gateways to
avoid overuse and abuse that could decrease stability and/or spike costs.
* As a compliance officer I want to mutate (or block) and log responses that may
contain personally identifiable information (PII).
* As a gateway operator and in the context of a request I want information about
the request (e.g. headers) to be defined as triggers for changes in the
subsequent rules that apply to the request (modifying, or even disabling those
rules based on the trigger).
## Goals

* Enable attaching firewall engines to a `Gateway`
* Enable `Gateway`-level firewall rule enforcement
* Enable `HTTPRoute`-level firewall rule enforcement
* Enable processing of both requests _and_ responses
* Provide documentation and best practices for implementations which describe
how firewall engines and rules can best be integrated into a Gateway API
implementation.

## Non-Goals

* Building a firewall implementation
* Mesh-level support

## API

**TODO**: First PR will not include any implementation details, in favor of
building consensus on the motivation, goals and non-goals first. _"How?"_ we
implement shall be left open-ended until _"What?"_ and _"Why?"_ are solid.

> **Note**: Note: Implementation details are premature. However, we consider it
> valid for this GEP to become a memorandum outlining how to implement these
> capabilities via existing extension mechanisms (e.g., filters, policy
> attachment) without API changes if API modifications are not warranted. We
> may need to work on _ordering_ in these mechanisms however if we decide that
> is the way to go, as that's an underserved area.

## Alternatives Considered

### NetworkPolicy

When discussing this originally the obvious question whether `NetworkPolicy`
is sufficient, or should have some role in this, was asked. We do not consider
it sufficient to resolve the goals unto itself. For the purposes of this GEP,
we consider `NetworkPolicy` as an implementation detail at most: implementations
_may_ choose how they enforce firewall rules, whether some of that is
implemented with `NetworkPolicy` under the hood or not is up to them.

## References

* [GEP-1767: CORS](https://github.com/kubernetes-sigs/gateway-api/issues/1767)

7 changes: 7 additions & 0 deletions geps/gep-3614/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
apiVersion: internal.gateway.networking.k8s.io/v1alpha1
kind: GEPDetails
number: 3614
name: Gateway Firewall Support
status: Provisional
authors:
- shaneutt