diff --git a/site-src/geps/gep-995.md b/site-src/geps/gep-995.md new file mode 100644 index 0000000000..1ccddad329 --- /dev/null +++ b/site-src/geps/gep-995.md @@ -0,0 +1,74 @@ +# GEP-995: HTTP Route Naming + +* Issue: [#995](https://github.com/kubernetes-sigs/gateway-api/issues/995) +* Status: Implementable + +## TLDR + +* Add `Name` field to `Rules` field in HTTPRoute. +* Add `Name` field to `Matches` field in HTTPRouteRule. + +## Goals + +Provide a path for implementations to support: + +* Policy Attachment: + Attach policies to Route rules. For this to be useful, we'd also need to add SectionName to PolicyTargetReference + as described here: https://gateway-api.sigs.k8s.io/geps/gep-713/#apply-policies-to-sections-of-a-resource-future-extension. +* Route Attachment/Delegation: + Ability to have more fine-grained matches for policy references if we add sectionName to the policy object. + Although Route Attachment/Delegation is not part of the API yet, it is likely to be added in the future. + This concept is tracked by [#634](https://github.com/kubernetes-sigs/gateway-api/issues/634). + One of the solutions that has been proposed for this involves using ParentRefs on a Route to refer to a parent Route. + If we were to do that, it may be useful to attach to a specific Route rule instead of the entire Route. + Adding name to Route rule could enable that. +* Improved Debugging: + Ability to add debugging information, such as adding the specific matching route rule name to an access log. + +## Introduction + +As described above, there are a number of potential use cases for providing an identity to a route rule. +The most straightforward reason for this is to allow extending a particular route rule. +This change will enable implementations to support the above use cases while still providing a portable core. + +## API + +A `Name` field would be added to `HTTPRouteMatch`: + +```go +type HTTPRouteRule struct { + // The name assigned to the route for debugging purposes. The + // route's name will be concatenated with the match's name and may + // be logged in the access logs for requests matching this + // route/match depends on the implementor. + // + // +optional + Name *string `json:"name,omitempty"` + ... +} +``` + + +A `Name` field would be added to `HTTPRouteRule `: + +```go +type HTTPRouteMatch struct { + // Name specifies the HTTP route match name. The match's name will be + // concatenated with the parent route's name and may be logged in + // the access logs for requests matching this route depends on the implementor. + // + // +optional + Name *string `json:"name,omitempty"` + ... +} +``` +## Alternatives + +1. Users can split out Routes into different resources when they need to be referenced separately. + Route rules are really more of a convenience than a necessity. Instead of having 10 rules in 1 route, the same config could be represented by 10 routes with 1 rule each. + This does not apply to istio, which will generate a route per Rule here, and they are all combined into one single RDS, so it is not easy for users to patch a specific route. + +2. Route attachment/delegation may choose to use a different approach. For example, each Route could choose to include a set of child routes by direct reference. + +3. Logging could assign numerical indexes to Route rules. Instead of rules[sectionName] logs would include rules[0] or similar. + However, this is not suitable for implementors that merge the rules before generating underlying configs.