Gateway API v0.5.0 API Review

Author: robscott

apis/v1alpha2/gateway_types.go

@@ -135,7 +135,7 @@ type GatewaySpec struct {
 	// it assigns to the Gateway and add a corresponding entry in
 	// GatewayStatus.Addresses.
 	//
-	// Support: Core
+	// Support: Extended
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=16
@@ -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"`
@@ -320,7 +321,7 @@ type GatewayTLSConfig struct {
 	// CertificateRefs can reference to standard Kubernetes resources, i.e.
 	// Secret, or implementation-specific custom resources.
 	//
-	// Support: Core - A single reference to a Kubernetes Secret
+	// Support: Core - A single reference to a Kubernetes Secret of type kubernetes.io/tls
 	//
 	// Support: Implementation-specific (More than one reference or other resource types)
 	//
@@ -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
@@ -673,7 +641,6 @@ const (
 	//
 	// * "HostnameConflict"
 	// * "ProtocolConflict"
-	// * "RouteConflict"
 	//
 	// Possible reasons for this condition to be False are:
 	//
@@ -695,13 +662,6 @@ const (
 	// number, but have conflicting protocol specifications.
 	ListenerReasonProtocolConflict ListenerConditionReason = "ProtocolConflict"
 
-	// This reason is used with the "Conflicted" condition when the route
-	// resources selected for this Listener conflict with other
-	// specified properties of the Listener (e.g. Protocol).
-	// For example, a Listener that specifies "UDP" as the protocol
-	// but a route selector that resolves "TCPRoute" objects.
-	ListenerReasonRouteConflict ListenerConditionReason = "RouteConflict"
-
 	// This reason is used with the "Conflicted" condition when the condition
 	// is False.
 	ListenerReasonNoConflicts ListenerConditionReason = "NoConflicts"

apis/v1alpha2/httproute_types.go

@@ -152,12 +152,15 @@ 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
 	// the above criteria.
 	//
+	// When no rules matching a request have been successfully attached to the
+	// parent a request is coming from, a HTTP 404 status code MUST be returned.
+	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8
 	// +kubebuilder:default={{path:{ type: "PathPrefix", value: "/"}}}
@@ -187,13 +190,25 @@ type HTTPRouteRule struct {
 
 	// BackendRefs defines the backend(s) where matching requests should be
 	// sent.
-
-	// If unspecified or invalid (refers to a non-existent resource or a Service
-	// with no endpoints), the rule performs no forwarding. If there are also no
-	// filters specified that would result in a response being sent, a HTTP 503
-	// status code is returned. 503 responses must be sent so that the overall
-	// weight is respected; if an invalid backend is requested to have 80% of
-	// requests, then 80% of requests must get a 503 instead.
+	//
+	// A 404 status code MUST be returned if there are no BackendRefs or filters
+	// specified that would result in a response being sent.
+	//
+	// A BackendRef is considered invalid when it refers to:
+	//
+	// * an unknown or unsupported kind of resource
+	// * a resource that does not exist
+	// * a resource in another namespace when the reference has not been
+	//   explicitly allowed by a ReferencePolicy (or equivalent concept).
+	//
+	// When a BackendRef is invalid, 404 status codes MUST be returned for
+	// requests that would have otherwise been routed to an invalid backend. If
+	// multiple backends are specified, and some are invalid, the proportion of
+	// requests that would otherwise have been routed to an invalid backend
+	// MUST receive a 404 status code.
+	//
+	// When a BackendRef refers to a Service that has no ready endpoints, it is
+	// recommended to return a 503 status code.
 	//
 	// Support: Core for Kubernetes Service
 	// Support: Custom for any other resource
@@ -227,11 +242,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 +509,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 +538,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 +557,6 @@ type HTTPRouteFilter struct {
 }
 
 // HTTPRouteFilterType identifies a type of HTTPRoute filter.
-// +kubebuilder:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;ExtensionRef
 type HTTPRouteFilterType string
 
 const (
@@ -548,13 +570,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 +699,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 +755,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 +784,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 +843,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/object_reference_types.go

@@ -100,6 +100,7 @@ type BackendObjectReference struct {
 	Group *Group `json:"group,omitempty"`
 
 	// Kind is kind of the referent. For example "HTTPRoute" or "Service".
+	// Defaults to "Service" when not specified.
 	//
 	// +optional
 	// +kubebuilder:default=Service

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.
 	//