diff --git a/geps/gep-2648/index.md b/geps/gep-2648/index.md index 7bb19e6e0b..a45285222e 100644 --- a/geps/gep-2648/index.md +++ b/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 @@ -99,9 +91,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 +130,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 +239,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 +375,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 +400,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. diff --git a/geps/gep-2648/metadata.yaml b/geps/gep-2648/metadata.yaml index a1aa7489f1..130c9fdfe6 100644 --- a/geps/gep-2648/metadata.yaml +++ b/geps/gep-2648/metadata.yaml @@ -1,6 +1,6 @@ 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 @@ -8,15 +8,15 @@ status: Experimental 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" diff --git a/geps/gep-2649/index.md b/geps/gep-2649/index.md index d9acce8788..e2897e4390 100644 --- a/geps/gep-2649/index.md +++ b/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,22 +118,23 @@ 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. @@ -207,23 +210,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 diff --git a/geps/gep-2649/metadata.yaml b/geps/gep-2649/metadata.yaml index 059a0640d4..fff0d0f5f4 100644 --- a/geps/gep-2649/metadata.yaml +++ b/geps/gep-2649/metadata.yaml @@ -3,14 +3,10 @@ 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 @@ -18,9 +14,7 @@ relationships: # 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" diff --git a/geps/gep-713/index.md b/geps/gep-713/index.md index 802de6b2ec..ee403fffad 100644 --- a/geps/gep-713/index.md +++ b/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 diff --git a/geps/gep-713/metadata.yaml b/geps/gep-713/metadata.yaml index c3d3e686c9..eed01c8459 100644 --- a/geps/gep-713/metadata.yaml +++ b/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" diff --git a/mkdocs.yml b/mkdocs.yml index 70621d877f..325289eae5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -129,6 +129,8 @@ nav: - geps/gep-1911/index.md - geps/gep-2162/index.md - geps/gep-2257/index.md + - geps/gep-2648/index.md + - geps/gep-2649/index.md - Standard: - geps/gep-709/index.md - geps/gep-718/index.md