diff --git a/site-src/geps/gep-709.md b/site-src/geps/gep-709.md index 1e772e39b1..fe2b4a3bcc 100644 --- a/site-src/geps/gep-709.md +++ b/site-src/geps/gep-709.md @@ -5,18 +5,22 @@ ## TLDR -This GEP attempts to tackle both cross namespace forwarding and route inclusion. -These are closely related concepts that can be solved with a new ReferencePolicy -resource that enables app admins to describe where they trust references from. +This GEP attempts to enable cross namespace forwarding from Routes and provide a +way to simplify adding Route inclusion (Routes including other Routes) in the +future. These are closely related concepts that can be solved with a new +ReferencePolicy resource that enables app admins to describe where they trust +references from. ## Motivation/User Journeys/Background -This GEP enables the following capabilities: +This GEP keeps same namespace references simple while enabling the following +capabilities for cross namespace references: 1. Retaining full control of Gateway and Routes in an infra namespace, while targeting apps in different namespaces. 1. Traffic splitting between Services in different namespaces. -1. Mesh overrides to target Services in different namespaces. +1. Mesh overrides to target Services in different namespaces. (For more info, + see GEP [#713](https://github.com/kubernetes-sigs/gateway-api/issues/713)) ## ReferencePolicy @@ -71,7 +75,9 @@ decisions: 1. Each ReferencePolicy only supports a single From and To section. Additional trust relationships can be modeled with additional ReferencePolicy resources. 1. Resource names are intentionally excluded from this policy for simplicity and - because they rarely provide any meaningful protection. + because they rarely provide any meaningful protection. A user that is able + to write to resources of a certain kind within a namespace can always rename + resources or change the structure of the resources to match a given policy. 1. A single Namespace is allowed per "From" struct. Although a selector would be more powerful it may encourage unnecessarily insecure configuration. @@ -91,7 +97,9 @@ type ReferencePolicy struct { // for Gateway API. type ReferencePolicySpec struct { // From describes the trusted namespaces and kinds that can reference the - // resources described in "To". + // resources described in "To". Each entry in this list must be considered + // to be an additional place that references can be valid from, or to put + // this another way, entries must be combined using OR. // // Support: Core // @@ -99,7 +107,9 @@ type ReferencePolicySpec struct { From []ReferencePolicyFrom `json:"from"` // To describes the resources that may be referenced by the resources - // described in "From". + // described in "From". Each entry in this list must be considered to be an + // additional place that references can be valid to, or to put this another + // way, entries must be combined using OR. // // Support: Core // @@ -117,9 +127,14 @@ type ReferencePolicyFrom struct { // +kubebuilder:validation:MaxLength=253 Group string `json:"group"` - // Kind is kind of the referrent. + // Kind is the kind of the referrent. Although implementations may support + // additional resources, the following Route types are part of the "Core" + // support level for this field: // - // Support: Core + // * HTTPRoute + // * TCPRoute + // * TLSRoute + // * UDPRoute // // +kubebuilder:validation:MinLength=1 // +kubebuilder:validation:MaxLength=253 @@ -134,7 +149,8 @@ type ReferencePolicyFrom struct { Namespace string `json:"namespace,omitempty"` } -// ReferencePolicyTo describes trusted kinds. +// ReferencePolicyTo describes what Kinds are allowed as targets of the +// references. type ReferencePolicyTo struct { // Group is the group of the referrent. // @@ -144,9 +160,15 @@ type ReferencePolicyTo struct { // +kubebuilder:validation:MaxLength=253 Group string `json:"group"` - // Kind is kind of the referrent. + // Kind is the kind of the referrent. Although implementations may support + // additional resources, the following types are part of the "Core" + // support level for this field: // - // Support: Core + // * Service + // * HTTPRoute + // * TCPRoute + // * TLSRoute + // * UDPRoute // // +kubebuilder:validation:MinLength=1 // +kubebuilder:validation:MaxLength=253 @@ -166,15 +188,22 @@ type ReferencePolicyTo struct { separate handshake config on each Service or Route resource. #### Exceptions -If traffic is originating from the same location as the configured Route (such -as sidecars in some mesh implementations) implementations may choose to ignore -ReferencePolicy. This should only be done if: -* Other mechanisms like NetworkPolicy can be used to effectively limit - cross-namespace references. -* The implementation clearly documents that ReferencePolicy is not honored. - -This exception is very unlikely to apply to any ingress implementations of the -API and will not apply to all mesh implementations. +There are some situations where it MAY be acceptable to ignore ReferencePolicy +in favor of some other security mechanism. This MAY only be done if other +mechanisms like NetworkPolicy can effectively limit cross-namespace references +by the implementation. + +An implementation choosing to take this exception MUST clearly document that +ReferencePolicy is not honored as well as which alternative safeguards are +available. Note that this is unlikely to apply to ingress implementations of the +API and will not apply to all mesh implementations. + +For an example of the risks involved in cross-namespace references, refer to +[CVE-2021-25740](https://github.com/kubernetes/kubernetes/issues/103675). +Implementations of this API need to be very careful to avoid confused deputy +attacks. ReferencePolicy provides a safeguard for that. Exceptions MUST only +be made by implementations that are absolutely certain that other equally +effective safeguards are in place. ## ForwardTo