Skip to content

API for Default Gateways #3887

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
+298 −9
Open

API for Default Gateways #3887

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2f0077e
Add API to GEP-3793.
kflynn Jun 29, 2025
8c0d335
Minor fixes in text, more important fixes in list formatting.
kflynn Jun 29, 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
307 changes: 298 additions & 9 deletions geps/gep-3793/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,11 @@ she doesn't have to explicitly name, and can simply trust to exist.
not in scope for this GEP, in order to have a fighting chance of getting
functionality into Gateway API 1.4.

Additionally, note that providing support for Chihiro to swap the default
Gateway without downtime may very well require supporting multiple default
Gateways at the same time, since Kubernetes does not support atomic swaps of
resources.

- Allow Ana to override Chihiro's choice for the default Gateway for a given
Route without explicitly specifying the Gateway.

Expand Down Expand Up @@ -161,10 +166,10 @@ Gateways.

## API

Most of the API work for this GEP is TBD at this point. The challenge is to
find a way to allow Ana to use Routes without requiring her to specify the
Gateway explicitly, while still allowing Chihiro and Ian to retain control
over the Gateway and its configuration.
The main challenge in the API design is to find a way to allow Ana to use
Routes without requiring her to specify the Gateway explicitly, while still
allowing Chihiro and Ian to retain control over the Gateway and its
configuration.

An additional concern is CD tools and GitOps workflows. In very broad terms,
these tools function by applying manifests from a Git repository to a
Expand All @@ -189,10 +194,274 @@ will need resolution before this GEP can graduate.

[discussion]: https://github.com/kubernetes-sigs/gateway-api/pull/3852#discussion_r2140117567

Finally, although support for multiple default Gateways is a non-goal for this
GEP, it's worth noting that allowing Chihiro full control over the default
Gateway is very much a goal, which includes giving Chihiro a clean way to swap
one default Gateway for another. This is important because a zero-downtime
swap implies having two default Gateways running at the same time, since
Kubernetes does not support any sort of atomic swap operation.

### Gateway for Ingress (North/South)

There are two main aspects to the API design for default Gateways:

1. Giving Ana a way to bind Routes to the default Gateway.

2. Giving Chihiro a way to control which Gateway is the default, and to
enumerate which Routes are bound to it.

#### 1. Binding a Route to the Default Gateway

For Ana to indicate that a Route should use the default Gateway, she MUST
Copy link
Contributor

Choose a reason for hiding this comment

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

Correct me if I'm wrong, but I believe Ana lacks a method to verify the presence of a default gateway being deployed in the cluster or to check if there is at least one listener on the Gateway permitting attachmentent of her Route.

Consider a scenario where Ana creates a Route and expects the default gateway to be attached, but no status condition is propagated. How should she troubleshoot this?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is exactly the same problem as if Ana creates a route with a parentRef naming a Gateway that doesn't exist: Ana will create the route, no status will show up, Ana will probably give it another minute or so, it still won't show up, and at that point Ana will (probably) start doublechecking if she typo'd the name of the Gateway, or picked the wrong Gateway by accident, or looking to see what Gateways she sees deployed, or calling Chihiro to ask what's going on, etc.

This isn't to say that it's a great situation for Ana, it's just an already existing situation. This is actually one of the reasons I tend to argue that Ana should always have RBAC to see which Gateways are deployed: it can really help Ana to be able to see the Gateways, although in any given situation, yeah, she might actually need to talk to Chihiro about it.

Copy link
Member

Choose a reason for hiding this comment

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

I think it's also important to note that Ana may not be the one checking this at all. See: #3385

Ana may be simply handing Chihiro their manifests in a "this is how you deploy, and expose my application" sort of manner, and knowledge of the Gateways on the cluster is irrelevant from their perspective.

In my mind, this is one of the key reasons to do default gateways.

leave `parentRefs` empty in the `spec` of the Route, for example:

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-route
spec:
rules:
- backendRefs:
- name: my-service
port: 80
```
would route _all_ HTTP traffic arriving at the default Gateway to `my-service`
on port 80.
Comment on lines +213 to +231
Copy link
Contributor

Choose a reason for hiding this comment

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

I agree this is really the only way to do this, but I think it may be important to be clear about what Ana is trading away here - the main thing is certainty. This defaulting behavior means that, if Ana does this, she is handing over control of where her app is advertised to Ian and Chihiro. It should absolutely not be used for anything that has specific security requirements, for example.

I say this, because I feel confident that at least someone will get screwed by that at some point in the future.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Heh, fascinating to read this and realize that I've been considering that as "obvious" -- so, yes, I'll add that, it's a great point to call out.


Note that Ana MUST omit `parentRefs` entirely: specifying an empty array for
Copy link
Member

Choose a reason for hiding this comment

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

This feels like it's going to lead to a lot of accidental exposures of a Route. This is a huge change. Currently the absence of parentRefs means that a Route is guaranteed to be internal only, and now we're changing it to mean "attached to any Gateway that claims to be default."

I would much rather have a way to intentionally attach to default Gateways. Maybe that's an entry in ParentRefs that is just kind: DefaultGateway, or maybe that's an entirely separate field which is attachToDefaultGateways: True. IMO, that would result in much clearer and more predictable behavior.

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 likely that this discussion will continue while I'm out on vacation; FTR I am okay with something like kind: DefaultGateway as a pseudo type more than I am with a separate field in the spec. But either would be okay if we have to do something more explicit.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

As we discussed in the Gateway API meeting today, I'd love to get more opinions here. I tend to feel that Ana is unlikely to be using Routes with no parentRefs because they don't anything, and as such I don't like things like

parentRefs:
  - kind: DefaultGateway

because it becomes just extra lines to type.

HOWEVER, I had also thought that a Route with no parentRefs would fail validation, and testing it this morning, nope, you can absolutely create such Routes. So I'm quite curious what others think.

Copy link
Contributor

Choose a reason for hiding this comment

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

Okay, I thought about this some more, and I have a few thoughts why I think that adding a DefaultGateway pseudo-Kind is probably better:

  • Because you can currently add a route with no parentRefs, the current proposal is a behavior change with no API change. As @robscott says, this runs a high risk of screwing Ana over. If she has created HTTPRoutes and expected them not to be advertised yet, then Chihiro flips the default switch to true on a Gatewyay, those HTTPRoutes will now be exposed with no action on Ana's part.
  • Not having any definite API change also makes this way harder to write an Extended feature for (since it seems reasonable that not every implementation will want to do this). Adding a DefaultGateway pseudo-Kind means that implementations can fail processing of that parentRoute and do the current behavior (which is to ignore the HTTPRoute because ownership reasons).
  • Using a pseudo-Kind also allows Ana to have a Route that binds to a GAMMA service and "whatever the default Gateway is", which doesn't seem like the best idea to me, but may be something that some Anas will want.
  • Since one of the primary uses for this defaulting config is write-once-read-many use cases like adding HTTPRoutes into Helm charts, having two extra lines is a small cost for the writer, while giving significant benefits (as above) to the reader and user (that is, Ana).

So yes, on reflection, I think I vastly prefer the kind: DefaultGateway solution.

With that said, I'm out on vacation in the next few hours until the end of the GEP refinement phase, so I should also be clear: I am not blocking this either way. I just think kind: DefaultGateway is a better design. But I would be reluctantly okay with the current "empty parentRefs" approach as well.

Copy link
Member

Choose a reason for hiding this comment

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

What would "pseudo-API" means? like no real API just a kind name? +1 if yes.

Copy link

@danwinship danwinship Jul 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

what if instead of having an API you just had a convention?

# Use the cluster's default gateway
parentRefs:
- namespace: default
  name: default

Copy link
Member

Choose a reason for hiding this comment

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

in this case, would you block users from actually deploy such a gateway in the default namespace?

Copy link

@danwinship danwinship Jul 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

"users" would not have permissions in the default namespace. (If they did, then they could replace the "kubernetes" service...) Only a cluster-admin ought to be able to create a Gateway there.

Copy link
Member

Choose a reason for hiding this comment

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

what if instead of having an API you just had a convention?

# Use the cluster's default gateway
parentRefs:
- namespace: default
  name: default

I think we'd have to avoid using the default namespace here and instead use a namespace that's unlikely to have been used before, but that seems like an easily solvable problem. The convention based approach is definitely the least disruptive here as it means no API changes are needed.

With that said, I'd be worried that this kind of approach would make it impossible to have more than one default gateway at a time, which would be annoying in the case that an admin wanted to migrate from one default gateway to another for a cluster. If for example a user was using GatewayClass foo as default and wanted to move to a Gateway of class bar as default, they'd have to either manually switching everything over that specified the default Gateway, or do a disruptive replacement of the default Gateway.

If the relationship was a bit more abstract (ie attachToDefaultGateways), you could have more than one default Gateway active at a time, and gradually swap DNS/whatever over after you'd verified that the new Gateway was meeting your needs.

Copy link

@JoelSpeed JoelSpeed Jul 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

An idea that came to mind, what if an alternative to parentRefs was implemented as a selector combination (namespace and label).

A cluster administrator could set up (in the future) a MutatingAdmissionPolicy (or equivalent mutation/policy) that looked at Gateways being created and, if they had no parent refs, could default the namespace/label selector to any value they like.
Perhaps they choose some label that has a key/value that implies default, it wouldn't really matter.

This would allow them to create many different gateways that match their selector, and over time adjust that set.

In theory it would allow other use cases of selecting the attachment in more dynamic ways too, not sure if that's something that had come up?

`parentRefs` MUST fail validation. If a Route with an empty array for
Copy link

Choose a reason for hiding this comment

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

How would you know the difference between omitted and an empty array? I don't think you can know that by the time you get to the Go type.

I assume this is just implemented as a minimum length requirement on the openapi validation on the CRD?

AFAICT this isn't on the schema today so is potentially a breaking change. Have you checked if validation ratcheting would cover this case? Does the entire window of supported K8s versions for GW API enable validation ratcheting by default?

`parentRefs` somehow exists in the cluster, all Gateways in the cluster MUST
refuse to accept it. (Omitting `parentRefs` entirely will work much more
cleanly with GitOps tools than specifying an empty array.)

Note also that if Ana specifies _any_ `parentRefs`, the default Gateway MUST
NOT claim the Route unless of the `parentRefs` explicitly names the default
Gateway. To do otherwise makes it impossible for Ana to define mesh-only
Routes, or to specify a Route that is meant to use only a specific Gateway
that is not the default. This implies that for Ana to specify a Route intended
to serve both north/south and east/west roles, she MUST explicitly specify the
Gateway in `parentRefs`, even if that Gateway happens to be the default
Gateway.

All other characteristics of a Route using the default Gateway MUST behave the
same as if the default Gateway were explicitly specified in `parentRefs`.

The default Gateway MUST use `status.parents` to announce that it has bound
the Route, for example:

```yaml
status:
parents:
- name: my-default-gateway
namespace: default
controllerName: gateway.networking.k8s.io/some-gateway-controller
conditions:
- type: Accepted
status: "True"
lastTransitionTime: "2025-10-01T12:00:00Z"
message: "Route is bound to default Gateway"
```

The default Gateway MUST NOT rewrite the `parentRefs` of a Route using the
default Gateway; it MUST leave `parentRefs` empty. This becomes important if
the default Gateway changes, or (in some situations) if GitOps tools are in
play.

##### Enumerating Routes Bound to the Default Gateway

To enumerate Routes bound to the default Gateway, Ana can look for Routes with
no `parentRefs` specified, and then check the `status.parents` of those Routes
to see if the Route has been claimed. This will also tell Ana which Gateway is
the default, even if she doesn't have RBAC to query Gateway resources
Copy link

Choose a reason for hiding this comment

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

Is that a form of privilege escalation?

directly.

While this is possible with `kubectl get -o yaml`, it's not exactly a friendly
user experience, so adding this functionality to a tool like `gwctl` would be
a dramatic improvement. In fact, looking at the `status` of a Route is very
much something that we should expect Ana to do often, whether or not default
Gateways are in play; `gwctl` or something similar SHOULD be able to show her
which Routes are bound to which Gateways in every case, not just with default
Gateways.

##### Open Questions

Should the Gateway also add a `condition` explicitly expressing that the Route
has been claimed by the default Gateway, perhaps with `type: DefaultGateway`?
This could help tooling like `gwctl` more easily enumerate Routes bound to the
default Gateway.

#### 2. Controlling which Gateway is the Default

Since Chihiro must be able to control which Gateway is the default, selecting
the default Gateway must be an active configuration step taken by Chihiro,
rather than any kind of implicit behavior. To that end, the Gateway resource
will gain a new field, `spec.isDefault`:

```go
type GatewaySpec struct {
// ... other fields ...
IsDefault *bool `json:"isDefault,omitempty"`
}
```
Comment on lines +295 to +307
Copy link
Contributor

Choose a reason for hiding this comment

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

This is roughly what I expected, I agree that there's no real way to do this other than a mechanism like this.

However, this option does not handle what happens when there are multiple Gateway-reconciling implementations in the cluster, each with a separate GatewayClass.

Does each GatewayClass have a separate default Gateway? Does each Route with no parentRefs get claimed by each GatewayClass?

Or is there also a mechanism for choosing a default GatewayClass? If so, we'd need to define similar rules for that.

tbh I am not sure which option is better here, although I think I slightly lean towards letting each GatewayClass have its own default, since each implementation will probably have a separate datapath.

Copy link
Member

Choose a reason for hiding this comment

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

Had roughly similar thoughts. Is the scope of the default Gateway is only per implementation? If so, why not defining the default Gateway in the GatewayClass?

Copy link
Member

Choose a reason for hiding this comment

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

+1 to comments above. I'd suggest that each Gateway implementation can implement their own limitations on how many default Gateways they'll support, with a baseline expectation that that will be at most one per GatewayClass.

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 started writing the API with the perspective that we would want to take the conservative route of supporting a single default Gateway per cluster, and changed my stance very very reluctantly as I gamed out the operational aspect of needing to change the default Gateway while the cluster is running, and the implementation aspect of enforcing such a limitation.

At this point, I do not consider it practical to limit the number of default Gateways at either the Gateway level or at the GatewayClass level. So, for example, if you have three Gateways marked as default, then if Ana creates a defaulted Route, it will bind to all three Gateways, irrespective of which GatewayClass the Gateways have.

I ended up here for a few reasons:

  1. If we enforce a single default Gateway, Chihiro cannot change the default Gateway without either incurring downtime, or having no way to make sure the new default Gateway will work. Enforcing one default per GatewayClass would seem to run into pretty much exactly the same set of implementation issues as enforcing one per cluster, and it doesn't actually improve the operational situation since it means that Chihiro only gets a safe way to do zero-downtime default Gateway swaps by involving a second GatewayClass, which is to say a second implementation that may or may not behave the same as the one they want to be using -- and I definitely don't think we know enough to declare that Chihiro will never want to swap to a different default Gateway in the same GatewayClass.
  2. Explaining one-per-GatewayClass to users of Gateway API is much more complex than explaining that any Gateway marked as a default will claim a defaulted Route. It's simply easier to reason about things without thinking about which GatewayClass owns a which Gateway.
  3. Finally, what we do really gain with a limit, per-cluster or otherwise? I was initially thinking of one per cluster because it sounds like it's the easiest to reason about... but really, it's not, because it introduces some ugly implementation details in an eventually-consistent world, and in turn those implementation details are likely to result in fragile enforcement that will leak. Ultimately, I don't think we gain anything: we shouldn't be imposing that kind of operational policy on Chihiro.

I'll see if I can express this better in the GEP. Always happy to hear suggestions for how, of course. 🙂

Copy link
Member

@LiorLieberman LiorLieberman Jul 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Thanks for the detailed reasoning. I think you have mostly convinced me.

Few more questions/concerns that comes with multiple default gateways:

  • Whats the intersection of default Gateways and Namespaces? Is the route going to be registered to Gateways in the same namespace AND gateways that allow refs from a different namespaces?

  • Assuming an org structure of default gateway per namespace. (while some gateways, allow refs from other namespaces for a reason). When Ana registers another route, she believes it is registered in her namespace but apparently it also impacts gateways in different namespaces. Probably it is expected, but would be useful a) document that and b) make sure Ana understands the implication of what she did?

Sidenote: I think this is a case where templating/dev independence tooling/ are a better fit for default gateways. (worth calling it out in alternatives to the whole GEP)

  • [perhaps not as significant concern] If we have X Default Gateways, Ana, when she registered her route to the default gateway(s), she has no idea where her route is registered. This can increase route conflicts and could potentially cause unexpected behavior (from Ana's perspective) as precedence rules are utilized more heavily.


If `spec.isDefault` is set to `true`, the Gateway MUST claim Routes that have
specified no `parentRefs` (subject to the usual Gateway API rules about which
Routes may be bound to a Gateway), and it MUST update its own `status` with a
`condition` of type `DefaultGateway` and `status` true to indicate that it is
the default Gateway, for example:

```yaml
status:
conditions:
- type: DefaultGateway
status: "True"
lastTransitionTime: "2025-10-01T12:00:00Z"
message: "Gateway is the default Gateway"
```
If `spec.isDefault` is not present or is set to `false`, the Gateway MUST NOT
claim those Routes and MUST NOT set the `DefaultGateway` condition in its
`status`.

##### Access to the Default Gateway

The rules for which Routes may bind to a Gateway do not change for the default
Gateway. In particular, if a default Gateway should accept Routes from other
namespaces, then it MUST include the appropriate `AllowedRoutes` definition,
and without such an `AllowedRoutes`, a default Gateway MUST accept only Routes
from its own namespace.

##### Behavior with No Default Gateway

If no Gateway has `spec.isDefault` set to `true`, then the behavior is exactly
the same as for Gateway API 1.3: all Routes MUST specify `parentRefs` in order
to function, and no Gateway will claim Routes that do not specify
`parentRefs`.

##### Deleting the Default Gateway

Deleting the default Gateway MUST behave the same as deleting any other
Gateway: all Routes that were bound to the default Gateway MUST be unbound,
and the `Accepted` conditions in the `status` of those Routes SHOULD be
removed.

##### Multiple Default Gateways

Support for multiple default Gateways in a cluster is not one of the original
goals of this GEP. However, allowing Chihiro to control which Gateway is the
default - including being able to switch which Gateway is the default at
runtime, without requiring downtime - is a goal.
Comment on lines +352 to +355
Copy link
Member

Choose a reason for hiding this comment

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

I think semantically throughout this GEP so far I'm reading the meaning of "Default Gateway" to mean "A single Gateway which routes will apply to by default".

However, I'm wondering if what a "Default Gateway" should more definitively be positioned as is: "a configuration on a Gateway that indicates that it will automatically accept routes within a certain scope by default". Under that definition, I think we would make multiple "Default Gateways" a goal.

🤔 curious as to your thoughts.


Kubernetes itself will not prevent setting `spec.isDefault` to `true` on
multiple Gateways in a cluster, and it also doesn't support any atomic swap
mechanisms. If we want to enforce only a single default Gateway, the Gateway
controllers will have to implement that enforcement logic. There are three
possible options here.

1. Don't bother with any enforcement logic.

In this case, a Route with no `parentRefs` specified will be bound to _all_
Gateways that have `spec.isDefault` set to `true`. Since Gateway API
already allows a Route to be bound to multiple Gateways, and the Route
`status` is already designed for it, this should function without
difficulty.

2. Treat multiple Gateways with `spec.isDefault` set to `true` as if no
Gateway has `spec.isDefault` set to `true`.

If we assume that all Gateway controllers in a cluster can see all the
Gateways in the cluster, then detecting that multiple Gateways have
`spec.isDefault` set to `true` is relatively straightforward.

For option 2, every Gateway with `spec.isDefault` set to `true` can simply
refuse to accept Routes with no `parentRefs` specified, behaving as if no
Gateway has been chosen as the default. Each Gateway would also update its
`status` with a `condition` of type `DefaultGateway` and `status` false to
indicate that it is not the default Gateway, for example:

```yaml
status:
conditions:
- type: DefaultGateway
status: "False"
lastTransitionTime: "2025-10-01T12:00:00Z"
message: "Multiple Gateways are marked as default"
```

3. Perform conflict resolution as with Routes.

In this case, the oldest Gateway with `spec.isDefault` set to `true` will
be considered the only default Gateway. That oldest Gateway will accept all
Routes with no `parentRefs` specified, while all other Gateways with
`spec.isDefault` set to `true` will ignore those Routes.

The oldest default Gateway will update its `status` to reflect that it the
default Gateway; all other Gateways with `spec.isDefault` set to `true`
will update their `status` as in Option 2.

Unfortunately, option 2 will almost certainly cause downtime in any case where
Chihiro wants to change the default Gateway:

- If Chihiro deletes the default Gateway before creating the new one, then all
routes using the default Gateway will be unbound during the time that
there's no default Gateway, resulting in errors for any requests using those
Routes.

- If Chihiro creates the new default Gateway before deleting the old one, then
all Routes using the default Gateway are still unbound during the time that
both Gateways exist.

Option 3 gives Chihiro a way to change the default Gateway without downtime:
when they create the new default Gateway, it will not take effect until the
old default Gateway is deleted. However, it doesn't give Chihiro any way to
test the Routes through the new default Gateway before deleting the old
Gateway.

Reluctantly, we must therefore conclude that option 1 is the only viable
choice. Therefore: Gateways MUST NOT attempt to enforce a single default
Gateway, and MUST allow Routes with no `parentRefs` to bind to _all_ Gateways
that have `spec.isDefault` set to `true`. This is simplest to implement, it
permits zero-downtime changes to the default Gateway, and it allows for
testing of the new default Gateway before the old one is deleted.

Comment on lines +422 to +428
Copy link
Contributor

Choose a reason for hiding this comment

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

It also doesn't change the security profile, since Ana is abrogating any responsibility for where her app is advertised by using this functionality.

##### Changes in Functionality

If Chihiro changes the default Gateway to a different implementation that does
not support all the functionality of the previous default Gateway, then the
Routes that were bound to the previous default Gateway will no longer function
as expected. This is not a new problem: it already exists when Ana changes a
Route's `parentRefs`, or when Chihiro changes the implementation of a Gateway
that is explicitly specified in a Route's `parentRefs`.

At present, we do not propose any solution to this problem, other than to note
that `gwctl` or similar tools SHOULD be able to show Ana not just the Gateways
to which a Route is bound, but also the features supported by those Gateways,
to at least help Ana understand if she is trying to use Gateways that don't
support a feature that she needs. This is a definitely an area for future
work, and it is complicated by the fact that Ana may not have access to read
Gateway resources in the cluster at all.

##### Listeners, ListenerSets, and Merging

Setting `spec.isDefault` on a Gateway affects which Routes will bind to the
Gateway, not where the Gateway listens for traffic. As such, setting
`spec.isDefault` MUST NOT alter a Gateway's behavior with respect to
Listeners, ListenerSets, or merging.

In the future, we may want to consider allowing a default ListenerSet rather
than only a default Gateway, but that is not in scope for this GEP. Even if it
is considered later, the guiding principle SHOULD be that `spec.isDefault`
SHOULD NOT affect where a Gateway listens for traffic or whether it can be
merged with other Gateways.

### Gateway For Mesh (East/West)

Mesh traffic is defined by using a Service as a `parentRef` rather than a
Gateway. As such, there is no case where a default Gateway would be used for
mesh traffic.

Comment on lines +461 to +464
Copy link
Member

Choose a reason for hiding this comment

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

what happens when parentRef is not empty due to needing to attach the route to a service? Would it violate the default-gateway requirement?

Copy link
Contributor

Choose a reason for hiding this comment

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

It's worth being explicit in here, probably, but my expectation is that, if you are specifying parentRefs for mesh, you're specifying parentRefs, and so you have to specify all parentRefs.

It's not going to be possible to do defaulting for GAMMA parentRefs because we don't have a clean object to put that setting in, I think. So, if you want a HTTPRoute to do both, you have to pick both the Service and the Gateway to attach to. That seems reasonable to me.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@youngnick did a fine job of summarizing my thought process here. I'll amplify this here, although it's discussed in the N/S section:

Note also that if Ana specifies any parentRefs, the default Gateway MUST
NOT claim the Route unless of the parentRefs explicitly names the default
Gateway. To do otherwise makes it impossible for Ana to define mesh-only
Routes, or to specify a Route that is meant to use only a specific Gateway
that is not the default. This implies that for Ana to specify a Route intended
to serve both north/south and east/west roles, she MUST explicitly specify the
Gateway in parentRefs, even if that Gateway happens to be the default
Gateway.

(ugh. s/unless of the/unless one of the/ in the second line...)

Copy link
Member

@LiorLieberman LiorLieberman Jul 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Want to revisit this though. We all believe default gateway is going to be useful, but at the same time, the vision for mesh is that you can use the same httproute for mesh. This increases the bar a little to onboard to GAMMA if you need to now mention all your gateways explicitly (of course this is a forward looking concern where users heavily rely on default gateways).

I understand the problem here and why you rely on empty parentRefs, but would like to think about how we can allow "default Gateway PLUS this service". perhaps this is another +1 to not rely on empty parentRef for this? xRef: #3887 (comment)

## Conformance Details

#### Feature Names
Expand All @@ -204,14 +473,34 @@ not seem like a good choice.

### Conformance tests

TBD.

## Alternatives

A possible alternative API design is to modify the behavior of Listeners or
ListenerSets; rather than having a "default Gateway", perhaps we would have
"[default Listeners]". One challenge here is that the Route `status` doesn't
currently expose information about which Listener is being used, though it
does show which Gateway is being used.
- A possible alternative API design is to modify the behavior of Listeners or
ListenerSets; rather than having a "default Gateway", perhaps we would have
"[default Listeners]". One challenge here is that the Route `status` doesn't
currently expose information about which Listener is being used, though it
does show which Gateway is being used.

[default Listeners]: https://github.com/kubernetes-sigs/gateway-api/pull/3852#discussion_r2149056246

- We could define the default Gateway as a Gateway with a magic name, e.g.
"default". This doesn't actually make things that much simpler for Ana
(she'd still have to specify `parentRefs`), and it raises questions about
Chihiro's ability to control which Routes can bind to the default Gateway,
as well as how namespacing would work -- it's especially unhelpful for Ana
if she has to know the namespace of the default Gateway in order to use it.
Comment on lines +488 to +493
Copy link
Member

Choose a reason for hiding this comment

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

I understand this sentiment, but I think it's worth noting here that we once discussed using API defaults to reduce the burden on Ana.

Copy link
Member

Choose a reason for hiding this comment

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

I think the other point against a change like this is that it would be a breaking change for anyone who already had a Gateway using whichever magic name we decided on here.


- A default Gateway could overwrite a Route's empty `parentRefs` with a
non-empty `parentRefs` pointing to the default Gateway. The main challenge
with this approach is that once the `parentRefs` are overwritten, it's no
longer possible to know that the Route was originally intended to use the
default Gateway. Using the `status` to indicate that the Route is bound to
the default Gateway instead both preserves Ana's original intent and also
makes it possible to change the default Gateway without requiring Ana to
recreate all her Routes.

## References

TBD.