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

Reworking Policy vs. Filter Documentation #880

Merged
merged 1 commit into from
Sep 28, 2021
Merged

Reworking Policy vs. Filter Documentation #880

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
63 changes: 37 additions & 26 deletions site-src/v1alpha2/references/policy-attachment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,32 +258,43 @@ Although these concerns are not unsolvable, they lead to the conclusion that
a Kubectl plugin should be our primary approach to providing visibility here,
with a possibility of adding policies to status at a later point.

### Interaction with Custom Filters and other extension points
There are multiple methods of custom extension in the Gateway API. Policy
attachment and custom Route filters are two of these. Policy attachment is
designed to provide arbitrary configuration fields that decorate Gateway API
resources. Route filters provide custom request/response filters embedded inside
Route resources. Both are extension methods for fields that cannot easily be
standardized as core or extended fields of the Gateway API. The following
guidance should be considered when introducing a custom field into any Gateway
controller implementation:

1. For any given field that a Gateway controller implementation needs, the
possibility of using core or extended should always be considered before
using custom policy resources. This is encouraged to promote standardization
and, over time, to absorb capabilities into the API as first class fields,
which offer a more streamlined UX than custom policy attachment.

2. Although it's possible that arbitrary fields could be supported by custom
policy, custom route filters, and core/extended fields concurrently, it is
strongly recommended that implementations not use multiple mechanisms for
representing the same fields. A given field should only be supported through
a single extension method. An example of potential conflict is policy
precedence and structured hierarchy, which only applies to custom policies.
Allowing a field to exist in custom policies and also other areas of the API,
which are not part of the structured hierarchy, breaks the precedence model.
Note that this guidance may change in the future as we gain a better
understanding for extension mechanisms of the Gateway API can interoperate.
### Interaction with Custom Route Filters
Both Policy attachment and custom Route filters provide ways to extend Gateway
API. Although similar in nature, they have slightly different purposes.

Custom Route filters provide a way to configure request/response modifiers or
middleware embedded inside Route rules or backend references.

Policy attachment is more broad in scope. In contrast with filters, policies can
be attached to a wide variety of Gateway API resources, and include a concept of
hierarchical defaulting and overrides. Although Policy attachment can be used to
target an entire Route or Backend, it cannot currently be used to target
specific Route rules or backend references. If there are sufficient use cases
for this, policy attachment may be expanded in the future to support this fine
grained targeting.

The following guidance should be considered when introducing a custom field into
any Gateway controller implementation:

#### 1. Use core or extended fields if available
For any given field that a Gateway controller implementation needs, the
possibility of using core or extended fields should always be considered
before using custom policy resources. This is encouraged to promote
standardization and, over time, to absorb capabilities into the API as first
class fields, which offer a more streamlined UX than custom policy
attachment.

#### 2. Custom filters and policies should not overlap
Copy link
Contributor

Choose a reason for hiding this comment

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

This seems in violation of our goals of policy attachment. This means any given configuration can apply to {gateway, route, service} or {route rule, route backend}, but nothing can apply to both. And if its in one category, it has to have one shape and is a backref, and in the other category its in another shape and is a forward ref.

This inconsistency is extremely confusing to users and implementors.

Copy link
Member Author

Choose a reason for hiding this comment

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

This seems in violation of our goals of policy attachment

This inconsistency is extremely confusing to users and implementors.

I personally disagree. I think allowing/encouraging the same resources/config to be attached with both filters and policy would get more confusing.

The way I look at it, it's potentially confusing to have both policy and custom filters, but this helps limit that by differentiating the two a bit more clearly. I think there are legitimate use cases where custom filters will be easier to work with.

This means any given configuration can apply to {gateway, route, service} or {route rule, route backend}, but nothing can apply to both

That's roughly true, but with policy you still have a lot of flexibility. It's entirely possible to split out Route rules into different Routes if needed for policy attachment. Although not ideal, it does make policy attachment fairly capable. When combined with the ability for policy to attach directly to backends, it seems like there aren't many remaining gaps in policy capabilities.

Although it's possible that arbitrary fields could be supported by custom
policy, custom route filters, and core/extended fields concurrently, it is
strongly recommended that implementations not use multiple mechanisms for
representing the same fields. A given field should only be supported through a
single extension method. An example of potential conflict is policy precedence
and structured hierarchy, which only applies to custom policies. Allowing a
field to exist in custom policies and also other areas of the API, which are not
part of the structured hierarchy, breaks the precedence model. Note that this
guidance may change in the future as we gain a better understanding of how
extension mechanisms of the Gateway API can interoperate.

### Conformance Level
This policy attachment pattern is associated with an "EXTENDED" conformance
Expand Down