GEP-713 enhancements by guicassolato · Pull Request #3609 · kubernetes-sigs/gateway-api

guicassolato · 2025-02-11T03:52:57Z

What type of PR is this?
/kind gep

What this PR does / why we need it:
Rewriting of GEP-713 (Memorandum) to clarify concepts and incorporate enhancements discussed at #2927.

Which issue(s) this PR fixes:
Related to #713

Does this PR introduce a user-facing change?:

Enhances GEP-713 (Memorandum) according to top voted suggestions discussed at https://github.com/kubernetes-sigs/gateway-api/discussions/2927, such as:
* merging Direct and Inherited back into a single spec;
* introducing the concept of **merge strategy**

Additionally to:
* targetRef supporting label selectors as an option;
* reduction of targetRef.sectionName to the base case of "it's just another (virtual) resource kind"; and
* algorithm for calculating effective meta resources (effective policies)

And general enhancements to the spec aiming to:
* acknowledge the current known support of the pattern across Gateway API implementations;
* broaden the definitions to potentially welcome known implementations of other meta resource-like concepts into the pattern (or at least acknowledge their similarities with Gateway API)

Moves GEP-713's previous forks GEP-2648 and GEP-2649 to Rejected.

geps/gep-713/index.md

howardjohn · 2025-02-11T04:15:07Z

geps/gep-713/index.md


-Cons:
+#### Target object status


can we give some examples of this? I think I understand it but not certain

Added a simplified example, plus an extension of it for the case including sectionName.

Please let me know if that works or if you expected to see a full YAML.

A full yaml would be nice

geps/gep-713/index.md

howardjohn · 2025-02-11T15:47:10Z

geps/gep-713/index.md

-  going to affect their object, at apply time, which helps a lot with discoverability.
+* **Accepted**: the meta resource passed both syntactic validation by the API server and semantic validation enforced by the controller, such as whether the target objects exist.
+* **Enforced**: the meta resource’s spec is guaranteed to be fully enforced, to the extent of what the controller can ensure.
+* **Partially enforced**: parts of the meta resource’s spec is guaranteed to be enforced, while other parts are known to have been superseded by other specs, to the extent of what the controller can ensure. The status should include details highlighting which parts of the meta resource are enforced and which parts have been superseded, with the references to all other related meta resources.


As long as this is not a MUST then its not a problem, but this seems like it could be quite onerous to compute. For example, imagine I have a global policy and then 1000 namespaces any of which could partially conflict. Its not great to have to 'bubble up' these to the parent.

A concrete example of this in existing Gateway API is attachedRoutes, which is similarly complex for implementations to compute (efficiently)

geps/gep-713/index.md

geps/gep-2648/index.md

geps/gep-2648/metadata.yaml

geps/gep-2649/index.md

geps/gep-2649/metadata.yaml

geps/gep-713/metadata.yaml

mkdocs.yml

geps/gep-713/index.md

youngnick · 2025-02-12T03:41:46Z

geps/gep-713/index.md


-## Background and concepts
+The merge strategies typically include strategies for dealing with conflicting and/or missing specs, such as for applying default and/or override values on the target resources.


I think it's important to note that sometimes the merge strategy may be specified in the design of the object (that is, it's a defaults policy or something), rather than in a field?

In fact, I tend to think that, if the merge strategy is listed in a field, it should be in the status, not the spec, since it's relevant info for users of the Policy more than implementers (who will build the merge strategy into code when handling the Policy anyway).

+1, this feels like something that belongs in status.

+1 that merge strategy may be defined in the metaresource, e.g. the API contract is either only one is allowed per target, or multiple are allowed.

I feel confused about the merge strategy in the status instead of the spec.

Are we talking about the metaresource's status and spec? Or the target's?

The merge strategy, if more than one is supported by the metaresource kind, is a choice of the user that declares an instance of the metaresource. How can it be in the status?

The user literally specify what merge strategy to use when merging that instance of the metaresource. It should be in the spec, no?

Added a few lines about merge strategy as a user choice or not, and reflected in the status stanza of the metaresource.

geps/gep-713/index.md

youngnick · 2025-02-12T04:54:28Z

geps/gep-713/index.md


-**Ana**: _What the hell just happened??_
+If multiple meta resources target the same context, this is considered to be a conflict.


We need to define "context" again here, I think. (I'd forgotten the definition by the time I got to this part).

Suggested change

If multiple meta resources target the same context, this is considered to be a conflict.

If multiple meta resources target the same context (that is, multiple instances of the same or similar policies acting on the same hierarchy have an effective target of the same object), this is considered to be a conflict.

"same", yes; "similar", not a good idea IMO. I think the behavior for different kinds of policies should be undefined.

I'm okay with removing "or similar", but I think that if we're going to leave this as undefined in some cases, we need to be specific in the ones where we do need to have opinions:

For Gateway API Policy objects included in the specification, in the case of intent conflict with some other Policy on Gateway API objects, the Gateway API Policy must take precedence.

For implementation specific Policy objects that affect the same properties across multiple implementations, it's up to the implementations to define behavior. If they don't then the behavior is, necessarily, undefined and could produce differing outcomes depending on unknown factors.

In other words, this is a terrible idea and users should try not to use multiple Policy objects that affect the same things.

youngnick · 2025-02-12T05:00:15Z

geps/gep-713/index.md

-**Chihiro**: _At a guess, all the workloads in the `baker` namespace actually
-fail a lot, but they seem OK because there are retries across the whole
-namespace?_ 🤔
+Conflicts must be resolved by applying a defined *merge strategy* (see further definition in the next section), where the meta resource considered higher between two conflicting specs dictates the merge strategy according to which the conflict must be resolved, defaulting to the lower spec (more specific) beating the higher one if not specified otherwise.


Suggested change

Conflicts must be resolved by applying a defined *merge strategy* (see further definition in the next section), where the meta resource considered higher between two conflicting specs dictates the merge strategy according to which the conflict must be resolved, defaulting to the lower spec (more specific) beating the higher one if not specified otherwise.

Conflicts must be resolved by applying a defined *merge strategy* (see further definition in the next section).

When resolving conflicts, the meta resource higher in the relevant hierarchy dictates the merge strategy - that is, merge strategy conflict resolution works on a least-specific-wins basis. After that the merge strategy's conflict resolution rules apply.

If no merge strategy is specified, then implementations should use more-specific-wins merge strategy by default.

I think this is what you meant here @guicassolato?

Yes, but I happen to find the suggested text more confusing than the original.

"least-specific-wins" and "more-specific-wins" have different subjects in the sentences, and therefore I would phrase it differently to avoid confusion.

A merge strategy is a function that takes as input 2 specs and outputs 1.

One thing is determining the merge strategy. When resolving a conflict posed by 2 metaresources, the least specific metaresource among the two dictates the merge strategy that will be used to solve the conflict, i.e. the function that will take both metaresource specs as input. It's always the least specific metaresource that determines it.

The determined merge strategy can be a merge strategy that resolves to "least-specific-wins" or "more-specific-wins" (and occasionally to things more sophisticated than that, like actual merges).

If the least specific metaresource does not specify a merge strategy, then the merge strategy used to resolve the conflict is "more-specific-wins".

Rephrased a bit to break down as suggested but trying to avoid overloading terminology.

geps/gep-713/index.md

…ted concepts Signed-off-by: Guilherme Cassolato <[email protected]>

Signed-off-by: Guilherme Cassolato <[email protected]>

…/etc in the spec Signed-off-by: Guilherme Cassolato <[email protected]>

Ref.: kubernetes-sigs#3609 (comment) Signed-off-by: Guilherme Cassolato <[email protected]>

Signed-off-by: Guilherme Cassolato <[email protected]>

1. Define names and mechanisms for possible merge strategies (so both what e.g. “atomic default” means, but also that “atomic default” is the correct name for that strategy) 2. Define a status mechanism by which the strategy SHOULD be reported, and that a conformant implementation MUST use the names defined in 1 to report strategy. 3. Define what merge strategy is preferred for `defaults`, and define that implementations using the defaults clause SHOULD use that strategy. 4. Define what merge strategy is preferred for `overrides`, and define that implementations using the overrides clause SHOULD use that strategy. 5. Acknowledge that implementations MAY support other strategies, or selecting strategies at runtime, but that those are implementation-specific behaviors. Signed-off-by: Guilherme Cassolato <[email protected]>

Signed-off-by: Guilherme Cassolato <[email protected]>

…lementations Signed-off-by: Guilherme Cassolato <[email protected]>

Signed-off-by: Guilherme Cassolato <[email protected]>

…on rules section Signed-off-by: Guilherme Cassolato <[email protected]>

Signed-off-by: Guilherme Cassolato <[email protected]>

… not must adopt Signed-off-by: Guilherme Cassolato <[email protected]>

Signed-off-by: Guilherme Cassolato <[email protected]>

…nd of merge strategy, etc) + more detailed `status` stanza provided Signed-off-by: Guilherme Cassolato <[email protected]>

Signed-off-by: Guilherme Cassolato <[email protected]>

robscott

Thanks @guicassolato, this is really well done!

Not at all a blocker for this PR, but this is by far our largest GEP now and may justify being split out into separate docs pages in the not too distant future.

robscott · 2025-10-30T05:03:01Z

geps/gep-713/index.md

+!!! warning
+    This GEP specifies a _pattern_, not an API field or new object. It defines some terms, including _Metaresource_, _Policies_ and _Policy Attachment_, and their related concepts.


A concern here is that when I look at the deploy preview for this, the number of warnings at the top of the page are pretty overwhelming. I think the text here is good, but I don't think it needs to be included in a warning block.

We have a warning, a danger and an info block here. Should them all be turned into regular paragraphs or just the warning one?

I'll make them all paragraphs for now, but happy to revert if needed.

robscott · 2025-10-30T05:06:46Z

geps/gep-713/index.md

+
+#### gwctl
+
+https://github.com/kubernetes-sigs/gwctl


Mind turning this into a link? (Same applies to similar items above and below)

robscott · 2025-10-30T05:10:02Z

geps/gep-713/index.md

+
+This is an `Ancestor` status rather than a `Parent` status, as in the Route status, because, for Policy Attachment, the relevant object may or may not be the direct parent.
+
+For example, `BackendTLSPolicy` directly attaches to a Service, which may be included in multiple Routes, in multiple Gateways. However, for many implementations, the status of the `BackendTLSPolicy` will be different only at the Gateway level, so Gateway is the relevant Ancestor for the status. Each Gateway that has a Route that includes a backend with an attached `BackendTLSPolicy` SHOULD have a separate `PolicyAncestorStatus` section in the `BackendTLSPolicy`'s `status.ancestors` stanza, which mandates that entries must be distinct using the combination of the `AncestorRef` and the `ControllerName` fields as a key. See [GEP-1897][../gep-1897/index.md] for the exact details.


The link to GEP-1897 isn't working

robscott · 2025-10-30T05:10:36Z

geps/gep-713/index.md

+
+##### Using upstream `PolicyAncestorStatus` struct
+
+_Status:_ Provisional


This feels like it should be experimental at minimum, likely standard now that we have a GA resource relying on it.

OK. Let's make it Experimental then. I think many implementations still need to catch up on this.

Signed-off-by: Guilherme Cassolato <[email protected]>

youngnick · 2025-11-04T06:03:59Z

One tiny non-blocking nit, so I'm going to get this done.

/lgtm

youngnick · 2025-11-04T06:43:35Z

/unhold

k8s-ci-robot requested review from robscott and youngnick February 11, 2025 03:53

k8s-ci-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Feb 11, 2025

howardjohn reviewed Feb 11, 2025

View reviewed changes