GEP-713 enhancements (#3609)

* GEP-713 resurrected

Resurrects GEP-713 all the way from being a Memorandum straight to Standard, while it buries its forks GEP-2648 and GEP-2649.

Addresses most of the up voted suggestions discussed at #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 enhacements to the spec aiming to:
* acknowledge the current known support of the pattern across Gateway API implementations;
* broaden the definitions to potentially welcome known implementation of other meta resource-like concepts into the pattern (or at least acknowledge their similarities with Gateway API)

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* update metadata files

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* not forcing annotations on objects not owned by the implementation

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* conflict resolution section rewritten to clarify that the merge strategy is the only thing necessary to resolve conflicts

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Metaresource spelled as a single word

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* addressing comments

* "meta resource" -> "metaresource" (single word)
* rephrasing/rearranging content for clarity
* typos

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fixing escaping of arrows and gt/lw characters

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* clarifying metaresource statuses' MUST vs SHOULD and example of target object status

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* targeting strategy -> targeting method, to avoid overloading of the term 'strategy'

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix target object status MUST versus SHOULD

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* diagrams to illustrate the abstract process for calculating effective metaresources

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* golang examples of target refs

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix broken anchors

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* diagrams for the end-to-end examples

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* sentence rephrased for improved readability

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* addressing a few comments by candita and robscott

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* typos

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Get GEP-713 back to Memorandum

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Reorg (take 1)

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Reorg (take 2)

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* minor fixes

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix: typo in 'sectionName'

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* minor fixes (2)

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix: typos

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* sentence about different kinds possibly implying different targetting semantics rephrased for improved readability

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* small enhancements to description of' Hierarchy of target kinds' and 'Conflict resolution rules' subsections

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Clarifying enhancements to the definitions of merge strategy and related concepts

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* added motivation to define 'classes of metaresources'

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Preferring 'Policy' over 'Metaresource' when prescribing rules/schema/etc in the spec

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Label selectors as a mechanism to target removed from the spec

Ref.: #3609 (comment)

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* More thorough definitions for the spec'ed merge strategies

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Further enhancements to the definition of Merge strategies after review

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 <guicassolato@gmail.com>

* minor fix: plural targetRefs used in an example

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Tables highlighting the current state of policies across multiple implementations

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix Envoy Gateway SecurityPolicy merge strategy

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* cleanup redundant 'in other words' summary from the conflict resolution rules section

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Less negative disclaimer at the top

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* minor fix: change and augment are not synonyms

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* added goal: facilitate building tools + implementations should adopt, not must adopt

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* keep support for singular form targetRef

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* use example.com in the examples

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* caveat to using sectionName

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix: list items and broken links

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* Reorg for more easily flagging of the status of each feature (each kind of merge strategy, etc)

+ more detailed `status` stanza provided

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix: several typos

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* warning, danger, and info blocks turned into regular paragraphs

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* PolicyAncestorStatus: Provisional -> Experimental

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* fix: broken link to GEP-1897

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

* links to known implementations

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

---------

Signed-off-by: Guilherme Cassolato <guicassolato@gmail.com>

Author: guicassolato

geps/gep-2648/index.md

@@ -1,12 +1,17 @@
 # GEP-2648: Direct Policy Attachment
 
 * Issue: [#2648](https://github.com/kubernetes-sigs/gateway-api/issues/2648)
-* Status: Provisional
+* Status: Declined
 
 (See [status definitions](../overview.md#gep-states).)
 
 ## TLDR
 
+!!! warning
+    This GEP has been merged back into [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/)
+    and now it's now obsolete. Please refer the original specification of Metaresources
+    and Policy Attachment for the current state of the pattern.
+
 Describe and specify a design pattern for a class of metaresource that can
 affect specific settings across a single target object.
 
@@ -21,13 +26,6 @@ Policy.
 
 This is a design for a _pattern_, not an API field or new object.
 
-!!! danger
-    This GEP is in the process of being updated.
-    Please see the discussion at https://github.com/kubernetes-sigs/gateway-api/discussions/2927
-    and expect further changes.
-    Some options under discussion there may make the distinction between Direct
-    and Inherited Policies moot, which would require a rework.
-
 ## Goals
 
 * Specify what common properties all Direct Attached Policies MUST have

geps/gep-2648/metadata.yaml

@@ -2,17 +2,17 @@ apiVersion: internal.gateway.networking.k8s.io/v1alpha1
 kind: GEPDetails
 number: 2648
 name: Direct Policy Attachment
-status: Provisional
+status: Declined
 # Any authors who contribute to the GEP in any way should be listed here using
 # their GitHub handle.
 authors:
   - youngnick
   - robscott
 relationships:
-  extends:
+  obsoletedBy:
     - name: Metaresources and Policy Attachment
       number: 713
-      description: Split out Direct Policy Attachment into its own GEP
+      description: Merged back into the original spec for Metaresources and Policy Attachment where it's presented as a well-defined class of metaresource
 # references is a list of hyperlinks to relevant external references.
 # It's intended to be used for storing GitHub discussions, Google docs, etc.
 references:

geps/gep-2649/index.md

@@ -1,24 +1,22 @@
 # GEP-2649: Inherited Policy Attachment
 
 * Issue: [#2649](https://github.com/kubernetes-sigs/gateway-api/issues/2649)
-* Status: Experimental
+* Status: Declined
 
 (See [status definitions](../overview.md#gep-states).)
 
 ## TLDR
 
+!!! warning
+    This GEP has been merged back into [GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/)
+    and now it's now obsolete. Please refer the original specification of Metaresources
+    and Policy Attachment for the current state of the pattern.
+
 Describe and specify a design pattern for a class of metaresource that can
 affect specific settings across a multiple target objects.
 
 This is a design for a _pattern_, not an API field or new object.
 
-!!! danger
-    This GEP is in the process of being updated.
-    Please see the discussion at https://github.com/kubernetes-sigs/gateway-api/discussions/2927
-    and expect further changes.
-    Some options under discussion there may make the distinction between Direct
-    and Inherited Policies moot, which would require a rework.
-
 ## Goals
 
 * Specify what common properties all Inherited Policies MUST have
@@ -224,7 +222,7 @@ proposal](https://github.com/kubernetes-sigs/gateway-api/issues/611).
 
 ### Policy Attachment for Ingress
 When talking about Direct Attached Policy attaching to Gateway resources for
-ingress use cases (as discussed in GEP-2648), the flow is relatively 
+ingress use cases (as discussed in GEP-2648), the flow is relatively
 straightforward. A policy can reference the resource it wants to apply to, and
 only affects that resource.
 
@@ -245,7 +243,7 @@ namespaces.
 ![Complex Ingress Example](images/2649-ingress-complex.png)
 
 In this example, the Gateway has a TimeoutPolicy attached, which affects the
-HTTPRoute in the App namespace. That HTTPRoute also has the Direct Attached 
+HTTPRoute in the App namespace. That HTTPRoute also has the Direct Attached
 RetryPolicy attached, which affects the HTTPRoute itself, and one of the backends
 has a HealthCheckPolicy attached to the Service, which is also a Direct Attached
 Policy.

geps/gep-2649/metadata.yaml

@@ -2,15 +2,15 @@ apiVersion: internal.gateway.networking.k8s.io/v1alpha1
 kind: GEPDetails
 number: 2649
 name: Inherited Policy Attachment
-status: Experimental
+status: Declined
 authors:
   - youngnick
   - robscott
 relationships:
-  extends:
+  obsoletedBy:
     - name: Metaresources and Policy Attachment
       number: 713
-      description: Split out Inherited Policy Attachment
+      description: Merged back into the original spec for Metaresources and Policy Attachment where it's presented as a well-defined class of metaresource
 # references is a list of hyperlinks to relevant external references.
 # It's intended to be used for storing GitHub discussions, Google docs, etc.
 references: