diff --git a/mkdocs.yml b/mkdocs.yml index 77f947deac..5ecc7d5ce5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,8 @@ nav: - API specification: references/spec.md - Releases: references/releases.md - Implementations: references/implementations.md + - Enhancement Proposals: + - "709: Cross Namespace References from Routes": geps/gep-709.md - Contributing: - Developer guide: contributing/devguide.md - Gateway Enhancement Proposal: contributing/gep.md diff --git a/site-src/geps/gep-709.md b/site-src/geps/gep-709.md index fe2b4a3bcc..86d8892e68 100644 --- a/site-src/geps/gep-709.md +++ b/site-src/geps/gep-709.md @@ -1,6 +1,6 @@ # GEP-709: Cross Namespace References from Routes -* Issue URL: https://github.com/kubernetes-sigs/gateway-api/issues/709 +* Issue: [#709](https://github.com/kubernetes-sigs/gateway-api/issues/709) * Status: Implementable ## TLDR @@ -24,16 +24,22 @@ capabilities for cross namespace references: ## ReferencePolicy -Anytime we allow crossing a namespace boundary, we need to be very cautious. To -ensure that this feature is safe, we need to enforce a handshake mechanism that -requires resources in both namespaces to agree to this reference. To accomplish -that, a new ReferencePolicy resource should be introduced. +Anytime we allow crossing a namespace boundary, we need to be very cautious. +In the past, we've seen that forwarding traffic across namespace boundaries is +a desired feature, but without the kinds of safeguards proposed here, +[vulnerabilities](https://github.com/kubernetes/kubernetes/issues/103675) can +emerge. + +To ensure that Gateway API is able to safely provide this functionality, we need +to enforce a handshake mechanism that requires resources in both namespaces to +agree to this reference. To accomplish that, a new ReferencePolicy resource +should be introduced. ![Reference Policy](images/709-referencepolicy.png) With this model, Routes would be able to directly reference Routes and Services in other namespaces. These references would only be considered valid if a -ReferencePolicy in the target namespace explicitly allowed it. +ReferencePolicy in the target namespace explicitly allowed it. The following example shows how a HTTPRoute in namespace foo could reference a Service in namespace bar. In this example a ReferencePolicy in the bar @@ -69,7 +75,7 @@ spec: ``` ### API -This proposed API is fairly straightforward, but comes with a couple notable +This proposed API is fairly straightforward, but comes with a few notable decisions: 1. Each ReferencePolicy only supports a single From and To section. Additional @@ -82,8 +88,11 @@ decisions: more powerful it may encourage unnecessarily insecure configuration. ```go -// ReferencePolicy identifies cross namespace relationships that are trusted for -// Gateway API. +// ReferencePolicy identifies kinds of resources in other namespaces that are +// trusted to reference the specified kinds of resources in the local namespace. +// Each ReferencePolicy can be used to represent a unique trust relationship. +// Additional Reference Policies can be used to add to the set of trusted +// sources of inbound references for the namespace they are defined within. type ReferencePolicy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -193,10 +202,11 @@ 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. +An implementation choosing to make this exception MUST clearly document that +ReferencePolicy is not honored by their implementations and detail 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). @@ -207,20 +217,22 @@ effective safeguards are in place. ## ForwardTo -To enable cross-namespace forwarding, we'll need to add a `namespace` field to -the ForwardTo BackendRef struct. +To enable cross-namespace forwarding, we'll need to add an optional `namespace` +field to the ForwardTo BackendRef struct. ```go type BackendRef struct { // ... - // Namespace is the namespace of the referrent. + // Namespace is the namespace of the backend. When unspecified, the local + // namespace is inferred. // // Support: Core // // +kubebuilder:validation:MinLength=1 // +kubebuilder:validation:MaxLength=253 - Namespace string `json:"namespace,omitempty"` + // +optional + Namespace *string `json:"namespace,omitempty"` } ``` @@ -228,7 +240,7 @@ type BackendRef struct { ### Inline Config Instead of ReferencePolicy, it is possible to represent these relationships -inline. +inline. ![Inline](images/709-inline.png) ```yaml