Gateway API v0.5.0 API Review

Author: robscott

apis/v1alpha2/gateway_types.go

@@ -145,7 +145,8 @@ type GatewaySpec struct {
 // Listener embodies the concept of a logical endpoint where a Gateway accepts
 // network connections.
 type Listener struct {
-	// Name is the name of the Listener.
+	// Name is the name of the Listener. This name MUST be unique within a
+	// Gateway.
 	//
 	// Support: Core
 	Name SectionName `json:"name"`
@@ -381,7 +382,7 @@ type AllowedRoutes struct {
 	// with the application protocol specified in the Listener's Protocol field.
 	// If an implementation does not support or recognize this resource type, it
 	// MUST set the "ResolvedRefs" condition to False for this Listener with the
-	// "InvalidRoutesRef" reason.
+	// "InvalidRouteKinds" reason.
 	//
 	// Support: Core
 	//
@@ -449,6 +450,7 @@ type GatewayAddress struct {
 	// Type of the address.
 	//
 	// +optional
+	// +kubebuilder:validation:Enum=IPAddress;Hostname;NamedAddress
 	// +kubebuilder:default=IPAddress
 	Type *AddressType `json:"type,omitempty"`
 
@@ -462,40 +464,6 @@ type GatewayAddress struct {
 	Value string `json:"value"`
 }
 
-// AddressType defines how a network address is represented as a text string.
-//
-// If the requested address is unsupported, the controller
-// should raise the "Detached" listener status condition on
-// the Gateway with the "UnsupportedAddress" reason.
-//
-// +kubebuilder:validation:Enum=IPAddress;Hostname;NamedAddress
-type AddressType string
-
-const (
-	// A textual representation of a numeric IP address. IPv4
-	// addresses must be in dotted-decimal form. IPv6 addresses
-	// must be in a standard IPv6 text representation
-	// (see [RFC 5952](https://tools.ietf.org/html/rfc5952)).
-	//
-	// Support: Extended
-	IPAddressType AddressType = "IPAddress"
-
-	// A Hostname represents a DNS based ingress point. This is similar to the
-	// corresponding hostname field in Kubernetes load balancer status. For
-	// example, this concept may be used for cloud load balancers where a DNS
-	// name is used to expose a load balancer.
-	//
-	// Support: Extended
-	HostnameAddressType AddressType = "Hostname"
-
-	// A NamedAddress provides a way to reference a specific IP address by name.
-	// For example, this may be a name or other unique identifier that refers
-	// to a resource on a cloud provider such as a static IP.
-	//
-	// Support: Implementation-Specific
-	NamedAddressType AddressType = "NamedAddress"
-)
-
 // GatewayStatus defines the observed state of Gateway.
 type GatewayStatus struct {
 	// Addresses lists the IP addresses that have actually been

apis/v1alpha2/httproute_types.go

@@ -152,7 +152,7 @@ type HTTPRouteRule struct {
 	//
 	// * The oldest Route based on creation timestamp.
 	// * The Route appearing first in alphabetical order by
-	//   "<namespace>/<name>".
+	//   "{namespace}/{name}".
 	//
 	// If ties still exist within the Route that has been given precedence,
 	// matching precedence MUST be granted to the first matching rule meeting
@@ -227,11 +227,10 @@ const (
 	// Matches based on a URL path prefix split by `/`. Matching is
 	// case sensitive and done on a path element by element basis. A
 	// path element refers to the list of labels in the path split by
-	// the `/` separator. A request is a match for path _p_ if every
-	// _p_ is an element-wise prefix of the request path.
+	// the `/` separator. When specified, a trailing `/` is ignored.
 	//
-	// For example, `/abc`, `/abc/` and `/abc/def` match the prefix
-	// `/abc`, but `/abcd` does not.
+	// For example. the paths `/abc`, `/abc/`, and `/abc/def` would all match
+	// the prefix `/abc`, but the path `/abcd` would not.
 	//
 	// "PathPrefix" is semantically equivalent to the "Prefix" path type in the
 	// Kubernetes Ingress API.
@@ -495,6 +494,8 @@ type HTTPRouteFilter struct {
 	// that filter MUST receive a HTTP error response.
 	//
 	// +unionDiscriminator
+	// +kubebuilder:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;ExtensionRef
+	// <gateway:experimental:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;URLRewrite;ExtensionRef>
 	Type HTTPRouteFilterType `json:"type"`
 
 	// RequestHeaderModifier defines a schema for a filter that modifies request
@@ -522,6 +523,13 @@ type HTTPRouteFilter struct {
 	// +optional
 	RequestRedirect *HTTPRequestRedirectFilter `json:"requestRedirect,omitempty"`
 
+	// URLRewrite defines a schema for a filter that modifies a request during forwarding.
+	// Support: Extended
+	//
+	// <gateway:experimental>
+	// +optional
+	URLRewrite *HTTPURLRewriteFilter `json:"urlRewrite,omitempty"`
+
 	// ExtensionRef is an optional, implementation-specific extension to the
 	// "filter" behavior.  For example, resource "myroutefilter" in group
 	// "networking.example.net"). ExtensionRef MUST NOT be used for core and
@@ -534,7 +542,6 @@ type HTTPRouteFilter struct {
 }
 
 // HTTPRouteFilterType identifies a type of HTTPRoute filter.
-// +kubebuilder:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;ExtensionRef
 type HTTPRouteFilterType string
 
 const (
@@ -548,13 +555,26 @@ const (
 
 	// HTTPRouteFilterRequestRedirect can be used to redirect a request to
 	// another location. This filter can also be used for HTTP to HTTPS
-	// redirects.
+	// redirects. This may not be used on the same Route rule or BackendRef as a
+	// URLRewrite filter.
 	//
 	// Support in HTTPRouteRule: Core
 	//
 	// Support in HTTPBackendRef: Extended
 	HTTPRouteFilterRequestRedirect HTTPRouteFilterType = "RequestRedirect"
 
+	// HTTPRouteFilterURLRewrite can be used to modify a request during
+	// forwarding. At most one of these filters may be used on a Route rule.
+	// This may not be used on the same Route rule or BackendRef as a
+	// RequestRedirect filter.
+	//
+	// Support in HTTPRouteRule: Extended
+	//
+	// Support in HTTPBackendRef: Extended
+	//
+	// <gateway:experimental>
+	HTTPRouteFilterURLRewrite HTTPRouteFilterType = "URLRewrite"
+
 	// HTTPRouteFilterRequestMirror can be used to mirror HTTP requests to a
 	// different backend. The responses from this backend MUST be ignored by
 	// the Gateway.
@@ -664,7 +684,42 @@ type HTTPRequestHeaderFilter struct {
 	Remove []string `json:"remove,omitempty"`
 }
 
-// HTTPRequestRedirectFilter defines configuration for the RequestRedirect filter.
+// HTTPPathModifierType defines the type of path redirect.
+type HTTPPathModifierType string
+
+const (
+	// This type of modifier indicates that the complete path will be replaced
+	// by the path redirect value.
+	AbsoluteHTTPPathModifier HTTPPathModifierType = "Absolute"
+
+	// This type of modifier indicates that any prefix path matches will be
+	// replaced by the substitution value. For example, a path with a prefix
+	// match of "/foo" and a ReplacePrefixMatch substitution of "/bar" will have
+	// the "/foo" prefix replaced with "/bar" in matching requests.
+	PrefixMatchHTTPPathModifier HTTPPathModifierType = "ReplacePrefixMatch"
+)
+
+// HTTPPathModifier defines configuration for path modifiers.
+// <gateway:experimental>
+type HTTPPathModifier struct {
+	// Type defines the type of path modifier.
+	//
+	// <gateway:experimental>
+	// +kubebuilder:validation:Enum=Absolute;ReplacePrefixMatch
+	Type HTTPPathModifierType `json:"type"`
+
+	// Substitution defines the HTTP path value to substitute. An empty value
+	// ("") indicates that the portion of the path to be changed should be
+	// removed from the resulting path. For example, a request to "/foo/bar"
+	// with a prefix match of "/foo" would be modified to "/bar".
+	//
+	// <gateway:experimental>
+	// +kubebuilder:validation:MaxLength=1024
+	Substitution string `json:"substitution"`
+}
+
+// HTTPRequestRedirect defines a filter that redirects a request. This filter
+// MUST not be used on the same Route rule as a HTTPURLRewrite filter.
 type HTTPRequestRedirectFilter struct {
 	// Scheme is the scheme to be used in the value of the `Location`
 	// header in the response.
@@ -685,6 +740,16 @@ type HTTPRequestRedirectFilter struct {
 	// +optional
 	Hostname *PreciseHostname `json:"hostname,omitempty"`
 
+	// Path defines parameters used to modify the path of the incoming request.
+	// The modified path is then used to construct the `Location` header. When
+	// empty, the request path is used as-is.
+	//
+	// Support: Extended
+	//
+	// <gateway:experimental>
+	// +optional
+	Path *HTTPPathModifier `json:"path,omitempty"`
+
 	// Port is the port to be used in the value of the `Location`
 	// header in the response.
 	// When empty, port (if specified) of the request is used.
@@ -704,6 +769,31 @@ type HTTPRequestRedirectFilter struct {
 	StatusCode *int `json:"statusCode,omitempty"`
 }
 
+// HTTPURLRewriteFilter defines a filter that modifies a request during
+// forwarding. At most one of these filters may be used on a Route rule. This
+// may not be used on the same Route rule as a HTTPRequestRedirect filter.
+//
+// <gateway:experimental>
+// Support: Extended
+type HTTPURLRewriteFilter struct {
+	// Hostname is the value to be used to replace the Host header value during
+	// forwarding.
+	//
+	// Support: Extended
+	//
+	// <gateway:experimental>
+	// +optional
+	Hostname *Hostname `json:"hostname,omitempty"`
+
+	// Path defines a path rewrite.
+	//
+	// Support: Extended
+	//
+	// <gateway:experimental>
+	// +optional
+	Path *HTTPPathModifier `json:"path,omitempty"`
+}
+
 // HTTPRequestMirrorFilter defines configuration for the RequestMirror filter.
 type HTTPRequestMirrorFilter struct {
 	// BackendRef references a resource where mirrored requests are sent.
@@ -738,7 +828,7 @@ type HTTPBackendRef struct {
 	//
 	// If there is a cross-namespace reference to an *existing* object
 	// that is not covered by a ReferencePolicy, the controller must ensure the
-	// "ResolvedRefs"  condition on the Route is set to `status: true`,
+	// "ResolvedRefs"  condition on the Route is set to `status: False`,
 	// with the "RefNotPermitted" reason and not configure this backend in the
 	// underlying implementation.
 	//

apis/v1alpha2/referencepolicy_types.go

@@ -123,7 +123,7 @@ type ReferencePolicyTo struct {
 	// * Service
 	Kind Kind `json:"kind"`
 
-	// Name is the name of the referent. When unspecified or empty, this policy
+	// Name is the name of the referent. When unspecified, this policy
 	// refers to all resources of the specified Group and Kind in the local
 	// namespace.
 	//