Fold in changes from kubernetes-sigs#2442 and fix yamllint errors

Signed-off-by: Nick Young <nick@isovalent.com>

geps/gep-2648/index.md

@@ -3,7 +3,7 @@
 * Issue: [#2648](https://github.com/kubernetes-sigs/gateway-api/issues/2648)
 * Status: Experimental
 
-(See status definitions [here](overview.md#status).)
+(See status definitions [here](/geps/overview/#gep-states)
 
 ## TLDR
 
@@ -12,15 +12,6 @@ affect specific settings across a single target object.
 
 This is a design for a _pattern_, not an API field or new object.
 
-## WIP TODO
-
-- Add changelog including the original PRs plus Flynn's one
-- Add details about how Direct is more specific and so overrides Inherited, NOT
-  MERGED
-- Update example to be BackendTLSPolicy
-- Specify some requirements for status (basically, do what we did for TLSBackendPolicy)
-
-
 ## Goals
 
 * Specify what common properties all Direct Attached Policies MUST have
@@ -35,7 +26,7 @@ This is a design for a _pattern_, not an API field or new object.
 
 GEP-713 defines two classes of Policy Attachment: Direct and Inherited.
 
-Direct Attached Policies (or Direct Policies) _only)_ affect the object they are
+Direct Attached Policies (or Direct Policies) _only_ affect the object they are
 attached to; that is, the object specified in their `targetRef`.
 
 Note that as soon as the Policy affects more objects than the referenced object,
@@ -44,6 +35,7 @@ it is an Inherited Policy.
 ## Direct Policy Attachment requirements in brief
 
 The following parts of GEP-713 also apply here. Direct Policy Attachments:
+
 - MUST be their own CRDs (e.g. `TimeoutPolicy`, `RetryPolicy` etc),
 - MUST include both `spec` and `status` stanzas
 - MUST have the `status` stanza include a `conditions` section using the standard
@@ -70,16 +62,19 @@ used to connect to that Service when it is used as a backend by a Route.
 
 See GEP-1897 for all the details of this Policy object.
 
-## Direct Policy design guidelines
+## Direct Policy design rules
 
-With this example in mind, here are some guidelines for when to consider
-using Direct Policy Attachment:
+With this example in mind, here are some rules for when a Policy is a Direct
+Policy:
 
-* The number or scope of objects is exactly _one_ object.
+* The number or scope of objects is exactly _one_ object. No label selectors or
+  lists of `targetRef` are allowed.
 * The modifications to be made to the objects don’t have any transitive information -
   that is, the modifications MUST only affect the single object that the targeted
   metaresource is bound to, and MUST NOT have ramifications that flow beyond that
-  object.
+  object. No attaching a Policy to a Gateway and affecting settings in Routes or
+  backends. If a Direct Attached Policy attaches to an object, it can only affect
+  properties _of that object_.
 * In terms of status, it SHOULD be reasonably easy for a user to understand that
   everything is working - basically, as long as the targeted object exists, and
   the modifications are valid, the metaresource is valid, and this should be
@@ -99,9 +94,11 @@ using Direct Policy Attachment:
 The `sectionName` field of `targetRef` can be used to target a specific section of other resources:
 
 * Service.Ports.Name
-* xRoute.Rules.Name
+* Gateway.Listners.Name
+* HTTPRoute.Rules.Name (once they are added in GEP-995, PR at https://github.com/kubernetes-sigs/gateway-api/pull/2593)
 
 For example, the RetryPolicy below applies to a RouteRule inside an HTTPRoute.
+(or rather, it will when GEP-995 merges).
 
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1alpha2
@@ -136,16 +133,17 @@ spec:
     sectionName: bar
 ```
 
-If a `sectionName` is specified, but does not exist on the targeted object, the Policy must fail to attach,
-and the policy implementation should record a `resolvedRefs` or similar Condition in the Policy's status.
-
-When multiple Policies of the same type target the same object, one with a `sectionName` specified, and one without,
-the one with a `sectionName` is more specific, and so will have all its settings apply. The less-specific Policy will
-not attach to the target.
-
-## Interactions with other Policy objects and settings
+If a `sectionName` is specified, but does not exist on the targeted object, the
+Policy must fail to attach, and the policy implementation should record a
+`resolvedRefs` or similar Condition in the Policy's status.
 
-TODO: See the discussion on https://github.com/kubernetes-sigs/gateway-api/pull/2442
+When multiple Policies of the same type target the same object, one with a
+`sectionName` and one without, the more specific policy (i.e., the one with a
+`sectionName`) will have its entire `spec` applied to the named section.
+The less specific policy will also have its `spec` applied to the target but
+MUST not affect the named section. The less specific policy will have its `spec`
+applied to all other sections of the target that are not targeted by any other
+more specific policies.
 
 ## User discoverability and status
 
@@ -244,6 +242,7 @@ implementation-specific domain prefix) added instead.
 
 Because these Conditions or annotations are namespaced per-implementation,
 implementations SHOULD:
+
 - Add the Condition or annotation if an object is policy affected when it is not
   already present
 - Remove the Condition or annotation when the last policy object stops referencing
@@ -379,9 +378,10 @@ type PolicyStatus struct {
 
 ## Examples
 
-### Direct Policy Attachment
+### Hypothetical TLSMinimumVersionPolicy
 
-The following Policy sets the minimum TLS version required on a Gateway Listener:
+The following hypothetical Policy sets the minimum TLS version required on a
+Gateway Listener:
 
 ```yaml
 apiVersion: networking.example.io/v1alpha1
@@ -403,3 +403,13 @@ Gateway `spec`, this is an example of a non-field Policy.
 This is an example of a Direct Attached Policy because it affects a field on the
 Gateway itself, rather than fields or behavior associated with Routes attached
 to that Gateway.
+
+### BackendTLSPolicy
+
+BackendTLSPolicy, introduced in [GEP-1897](https://gateway-api.sigs.k8s.io/geps/gep-1897/)
+allows backends to set the TLS details that a Gateway implementation must use
+to connect to that backend.
+
+It does this using a Direct Attached Policy that attaches to a Service.
+
+Work on this Policy is still ongoing, please see GEP-1897 for details.

geps/gep-2648/metadata.yaml

@@ -1,22 +1,22 @@
 apiVersion: internal.gateway.networking.k8s.io/v1alpha1
 kind: GEPDetails
-number: 696
+number: 2648
 name: Direct Policy Attachment
 status: Experimental
 # Any authors who contribute to the GEP in any way should be listed here using
 # their Github handle.
 authors:
   - robscott
   - youngnick
-  - kflynn
 relationships:
   extends:
-  - name: Metaresources and Policy Attachment
-    number: 713
-    description: Split out Direct Policy Attachment into its own GEP
+    - name: Metaresources and Policy Attachment
+      number: 713
+      description: Split out Direct Policy Attachment into its own GEP
 # references is a list of hyperlinks to relevant external references.
 # It's intended to be used for storing Github discussions, Google docs, etc.
 references: {}
 # changelog is a list of hyperlinks to PRs that make changes to the GEP, in
 # ascending date order.
-changelog: {}
+changelog:
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2813"

geps/gep-2649/index.md

@@ -3,7 +3,7 @@
 * Issue: [#2649](https://github.com/kubernetes-sigs/gateway-api/issues/2649)
 * Status: Experimental
 
-(See status definitions [here](overview.md#status).)
+(See status definitions [here](/geps/overview/#gep-states)
 
 ## TLDR
 
@@ -25,6 +25,7 @@ This is a design for a _pattern_, not an API field or new object.
 ## Inherited Policy Attachment requirements in brief
 
 The following parts of GEP-713 also apply here. Inherited Policy Attachments:
+
 - MUST be their own CRDs (e.g. `TimeoutPolicy`, `RetryPolicy` etc),
 - MUST include both `spec` and `status` stanzas
 - MUST have the `status` stanza include a `conditions` section using the standard
@@ -35,6 +36,7 @@ kind is a Policy, and SHOULD use the `Policy` suffix at the end of the Kind and
 `policies` at the end of the Resource names).
 
 Additionally, Inherited Policy Attachment:
+
 - MAY specify a `defaults` stanza, an `overrides` stanza, or both. If it does not,
   it MUST specify if its fields are defaults or overrides in each field's godoc.
 
@@ -116,34 +118,29 @@ this document.
   specifies a value, the _object's_ value wins.
 * Policies interact with the fields they are controlling in a "replace value"
   fashion.
-  * For fields where the `value` is a scalar, (like a string or a number)
-    MUST have their value _replaced_ by the value in the Policy if it wins.
-    Notably, this means that a `default` will only ever replace an empty or unset
-    value in an object.
-  * For fields where the value is an object, the Policy should include the fields
-    in the object in its definition, so that the replacement can be performed
-    on each field inside the object as a simple field rather than the object as
-    a whole.
-  * For fields where the final value is non-scalar, but is not an _object_ with
-    fields of its own, the value MUST be entirely replaced, _not_ merged. This
-    means that lists of strings or lists of ints specified in a Policy overwrite
-    the empty list (in the case of a `default`) or any specified list (in the case
-    of an `override`). The same applies to `map[string]string` fields. An example
-    here would be a field that stores a map of annotations - specifying a Policy
-    that overrides annotations will mean that a final object specifying those
-    annotations will have its value _entirely replaced_ by an `override` setting.
+    * For fields where the `value` is a scalar, (like a string or a number)
+      MUST have their value _replaced_ by the value in the Policy if it wins.
+      Notably, this means that a `default` will only ever replace an empty or unset
+      value in an object. Note also that, as in Go, the empty string value is _only_
+      a string of length 0, generally represented as `""`.
+    * For fields where the value is an object, the Policy should include the fields
+      in the object in its definition, so that the replacement can be performed
+      on each field inside the object as a simple field rather than the object as
+      a whole.
+    * For fields where the final value is non-scalar, but is not an _object_ with
+      fields of its own, the value MUST be entirely replaced, _not_ merged. This
+      means that lists of strings or lists of ints specified in a Policy overwrite
+      the empty list (in the case of a `default`) or any specified list (in the case
+      of an `override`). The same applies to `map[string]string` fields. An example
+      here would be a field that stores a map of annotations - specifying a Policy
+      that overrides annotations will mean that a final object specifying those
+      annotations will have its value _entirely replaced_ by an `override` setting.
 * In the case that two Policies of the same type specify different fields, then
   _all_ of the specified fields MUST take effect on the affected object, using
   the precedence rules given above.
 
 Examples to further illustrate these rules are given below.
 
-#### Supported Resources
-It is important to note that not every implementation will be able to support
-policy attachment to each resource described in the hierarchy above. When that
-is the case, implementations MUST clearly document which resources a policy may
-be attached to.
-
 #### Attaching Policy to GatewayClass
 GatewayClass may be the trickiest resource to attach policy to. Policy
 attachment relies on the policy being defined within the same scope as the
@@ -207,23 +204,39 @@ but also borrows some concepts from the [ServicePolicy
 proposal](https://github.com/kubernetes-sigs/gateway-api/issues/611).
 
 ### Policy Attachment for Ingress
-Attaching a Directly Attached Policy to Gateway resources for ingress use cases
-is relatively straightforward. A policy can reference the resource it wants to
-apply to.
+When talking about Direct Attached Policy attaching to Gateway resources for
+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.
 
-Access is granted with RBAC - anyone that has access to create a RetryPolicy in
-a given namespace can attach it to any resource within that namespace.
 
 ![Simple Ingress Example](images/2649-ingress-simple.png)
 
-An Inherited Policy can attach to a parent resource, and then each policy
+However, an Inherited Policy can attach to a parent resource, and then each policy
 applies to the referenced resource and everything below it in terms of hierarchy.
-Although this example is likely more complex than many real world
+
+In the simple example above, the TimeoutPolicy _attaches_ to the Gateway but
+_affects_ the HTTPRoute. That's the very thing that makes this an Inherited
+Policy.
+
+Although the next example is likely more complex than many real world
 use cases, it helps demonstrate how policy attachment can work across
 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 
+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.
+
+This shows how Direct and Inherited Policies can be attached to varied objects
+and still apply the relevant configuration.
+
+As a preview of a later section though, ask yourself: If I was the owner of the
+HTTPRoute, how would I know what Policy was affecting it at any point in time?
+
 ### Policy Attachment for Mesh
 Although there is a great deal of overlap between ingress and mesh use cases,
 mesh enables more complex policy attachment scenarios. For example, you may want
@@ -411,6 +424,12 @@ objects _may_ both end up affecting the final object.
 
 ![Inherited Policy Example](images/2649-policy-hierarchy.png)
 
+#### Supported Resources
+It is important to note that not every implementation will be able to support
+policy attachment to each resource described in the hierarchy above. When that
+is the case, implementations MUST clearly document which resources a policy may
+be attached to.
+
 ## Examples
 
 This section provides some examples of various types of Policy objects, and how

geps/gep-2649/metadata.yaml

@@ -3,24 +3,18 @@ kind: GEPDetails
 number: 2649
 name: Inherited Policy Attachment
 status: Experimental
-# Any authors who contribute to the GEP in any way should be listed here using
-# their Github handle.
 authors:
   - youngnick
+  - robscott
 relationships:
-  # extends indicates that a GEP extends the linkned GEP, adding more detail
-  # or additional implementation. The extended GEP MUST have its extendedBy
-  # field set back to this GEP.
   extends:
     - name: Metaresources and Policy Attachment
       number: 713
       description: Split out Inherited Policy Attachment
 # references is a list of hyperlinks to relevant external references.
 # It's intended to be used for storing Github discussions, Google docs, etc.
 references: {}
-# featureNames is a list of the feature names introduced by the GEP, if there
-# are any. This will allow us to track which feature was introduced by which GEP.
-featureNames: {}
 # changelog is a list of hyperlinks to PRs that make changes to the GEP, in
 # ascending date order.
-changelog: {}
+changelog:
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2813"

geps/gep-713/index.md

@@ -1,13 +1,7 @@
 # GEP-713: Metaresources and Policy Attachment
 
 * Issue: [#713](https://github.com/kubernetes-sigs/gateway-api/issues/713)
-* Status: Experimental
-
-> **Note**: This GEP is exempt from the [Probationary Period][expprob] rules of
-> our GEP overview as it existed before those rules did, and so it has been
-> explicitly grandfathered in.
-
-[expprob]:https://gateway-api.sigs.k8s.io/geps/overview/#probationary-period
+* Status: Memorandum
 
 ## TLDR
 
@@ -145,7 +139,7 @@ small examples. Please see the separated GEPs for more examples.
 
 **BackendTLSPolicy** is the canonical example of a Direct Attached Policy because
 it _only_ affects the Service that the Policy attaches to, and affects how that
-Service is consumed. BUt you can know everything you need to about the Service
+Service is consumed. But you can know everything you need to about the Service
 and BackendTLSPolicy just by looking at those two objects.
 
 **Hypothetical max body size Policy**: Kate Osborn

geps/gep-713/metadata.yaml

@@ -2,18 +2,30 @@ apiVersion: internal.gateway.networking.k8s.io/v1alpha1
 kind: GEPDetails
 number: 713
 name: Metaresources and Policy Attachment
-status: Experimental
+status: Memorandum
 authors:
   - youngnick
+  - robscott
   - kflynn
+  - sanjaypujare
+  - spacewander
 relationships:
   extendedBy:
-  - name: Direct Policy Attachment
-    number: 2648
-    description: Split out Direct Policy Attachment
-  - name: Inherited Policy Attachment
-    number: 2649
-    description: Split out Inherited Policy Attachment
+    - name: Direct Policy Attachment
+      number: 2648
+      description: Split out Direct Policy Attachment
+    - name: Inherited Policy Attachment
+      number: 2649
+      description: Split out Inherited Policy Attachment
 references:
   - "https://github.com/kubernetes-sigs/gateway-api/issues/611"
   - "https://docs.google.com/document/d/13fyptUtO9NV_ZAgkoJlfukcBf2PVGhsKWG37yLkppJo/edit?resourcekey=0-Urhtj9gBkGBkSL1gHgbWKw"
+changelog:
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/715"
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/1565"
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2128"
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2283"
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2448"
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2654"
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2660"
+  - "https://github.com/kubernetes-sigs/gateway-api/pull/2813"