Replace ObjectReference, TypedLocalObjectReference

Define well focused reference types and use them instead of ObjectReference
and TypedLocalObjectReference, which should be avoided for all the reasons
described in the ObjectReference godoc[1].

1. https://github.com/kubernetes/api/blob/6e59bf7a52c237aadf4cc1f905c66b5f178c30b9/core/v1/types.go#L4985-L4996

* api/v1alpha1/gateway_types.go (GatewaySpec): Replace
TypedLocalObjectReference with RouteObjectReference.
(Listener): Replace TypedLocalObjectReference with
ListenerExtensionObjectReference.
(ListenerTLS): Replace TypedLocalObjectReference with
CertificateObjectReference.
(LocalObjectReference): New type.  Identify an API object within a known
namespace.
(CertificateObjectReference): New type alias for LocalObjectReference.
Identify a certificate object.
(ListenerExtensionObjectReference): New type alias for
LocalObjectReference.  Identify a listener extension object.
(RouteObjectReference): New type alias for LocalObjectReference.  Identify
a route object.
* api/v1alpha1/gatewayclass_types.go (GatewayClassSpec): Replace
ObjectReference with GatewayClassParametersObjectReference.
(GatewayClassParametersObjectReference): New type alias for
LocalObjectReference.  Identify a parameters object for a GatewayClass
object.
* api/v1alpha1/httproute_types.go (HTTPRouteHost): Replace
TypedLocalObjectReference with RouteHostExtensionObjectReference.
(HTTPRouteMatch): Replace TypedLocalObjectReference with
RouteMatchExtensionObjectReference.
(RouteMatchExtensionObjectReference): New type alias for
LocalObjectReference.  Identify a route-match extension object.
(HTTPRouteFilter): Replace TypedLocalObjectReference with
RouteFilterExtensionObjectReference.
(RouteFilterExtensionObjectReference): New type alias for
LocalObjectReference.  Identify a route-filter extension object.
(HTTPHeaderFilter): Replace TypedLocalObjectReference with
RouteActionTargetObjectReference and RouteActionExtensionObjectReference.
(RouteActionTargetObjectReference): New type alias for
LocalObjectReference.  Identify a target object for a route action.
(RouteActionExtensionObjectReference): New type alias for
LocalObjectReference.  Identify a route-action extension object.
(RouteHostExtensionObjectReference): New type alias for
LocalObjectReference.  Identify a route-host extension object.
(HTTPRouteStatus): Replace ObjectReference with GatewayObjectReference.
(GatewayObjectReference): New type.  Identify a Gateway object.
* api/v1alpha1/zz_generated.deepcopy.go:
* config/crd/bases/networking.x.k8s.io_gatewayclasses.yaml:
* config/crd/bases/networking.x.k8s.io_gateways.yaml:
* config/crd/bases/networking.x.k8s.io_httproutes.yaml: Regenerate.

api/v1alpha1/gateway_types.go

@@ -56,9 +56,11 @@ type GatewaySpec struct {
 	// Listeners associated with this Gateway. Listeners define what addresses,
 	// ports, protocols are bound on this Gateway.
 	Listeners []Listener `json:"listeners"`
-	// Routes associated with this Gateway. Routes define
-	// protocol-specific routing to backends (e.g. Services).
-	Routes []core.TypedLocalObjectReference `json:"routes"`
+	// Routes associated with this Gateway. Routes define protocol-specific
+	// routing to backends (e.g. Services).  Typically the resource is
+	// "httproute" or "tcproute" in group "networking.x.k8s.io", or an
+	// implementation may support other resources.
+	Routes []RouteObjectReference `json:"routes"`
 }
 
 const (
@@ -108,11 +110,13 @@ type Listener struct {
 	//
 	// +optional
 	TLS *ListenerTLS `json:"tls,omitempty"`
-	// Extension for this Listener.
+	// Extension for this Listener.  The resource may be "configmap" (use
+	// the empty string for the group) or an implementation-defined resource
+	// (for example, resource "mylistener" in group "networking.acme.io").
 	//
 	// Support: custom.
 	// +optional
-	Extension *core.TypedLocalObjectReference `json:"extension,omitempty"`
+	Extension *ListenerExtensionObjectReference `json:"extension,omitempty"`
 }
 
 const (
@@ -159,19 +163,21 @@ const (
 // - aws: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#describe-ssl-policies
 // - azure: https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-bindings#enforce-tls-1112
 type ListenerTLS struct {
-	// Certificates is a reference to one or more Kubernetes objects each containing
-	// an identity certificate that is bound to the listener. The hostname in a TLS
-	// SNI client hello message is used for certificate matching and route hostname
-	// selection. The SNI server_name must match a route hostname for the Gateway to
-	// route the TLS request.
-	//
-	// If apiGroup and kind are empty, will default to Kubernetes Secrets resources.
+	// Certificates is a list of references to Kubernetes objects that each
+	// contain an identity certificate that is bound to the listener.  The
+	// host name in a TLS SNI client hello message is used for certificate
+	// matching and route host name selection.  The SNI server_name must
+	// match a route host name for the Gateway to route the TLS request.  If
+	// an entry in this list specifies the empty string for both the group
+	// and the resource, the resource defaults to "secret".  An
+	// implementation may support other resources (for example, resource
+	// "mycertificate" in group "networking.acme.io").
 	//
 	// Support: Core (Kubernetes Secrets)
 	// Support: Implementation-specific (Other resource types)
 	//
 	// +required
-	Certificates []core.TypedLocalObjectReference `json:"certificates"`
+	Certificates []CertificateObjectReference `json:"certificates,omitempty"`
 	// MinimumVersion of TLS allowed. It is recommended to use one of
 	// the TLS_* constants above. Note: this is not strongly
 	// typed to allow implementation-specific versions to be used without
@@ -195,6 +201,43 @@ type ListenerTLS struct {
 	Options map[string]string `json:"options"`
 }
 
+// LocalObjectReference identifies an API object within a known namespace.
+type LocalObjectReference struct {
+	// Group is the group of the referent.  The empty string represents
+	// the core API group.
+	//
+	// +kubebuilder:validation:Required
+	// +required
+	Group string `json:"group"`
+	// Resource is the resource of the referent.
+	//
+	// +kubebuilder:validation:Required
+	// +required
+	Resource string `json:"resource"`
+	// Name is the name of the referent.
+	//
+	// +kubebuilder:validation:Required
+	// +required
+	Name string `json:"name"`
+}
+
+// CertificateObjectReference identifies a certificate object within a known
+// namespace.
+//
+// +k8s:deepcopy-gen=false
+type CertificateObjectReference = LocalObjectReference
+
+// ListenerExtensionObjectReference identifies a listener extension object
+// within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type ListenerExtensionObjectReference = LocalObjectReference
+
+// RouteObjectReference identifies a route object within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type RouteObjectReference = LocalObjectReference
+
 // GatewayStatus defines the observed state of Gateway.
 type GatewayStatus struct {
 	// Conditions describe the current conditions of the Gateway.

api/v1alpha1/gatewayclass_types.go

@@ -66,16 +66,22 @@ type GatewayClassSpec struct {
 	// class. This is optional if the controller does not require
 	// any additional configuration.
 	//
-	// Valid types for reference are up to the
-	// Controller. Examples include `core.ConfigMap` or a custom
-	// resource (CRD).
+	// Valid resources for reference are up to the Controller. Examples
+	// include "configmap" (using the empty string to indicate the core API
+	// group) or a custom resource (CRD).
 	//
 	// Support: Custom
 	//
 	// +optional
-	ParametersRef *core.ObjectReference `json:"parameters,omitempty" protobuf:"bytes,2,opt,name=parametersRef"`
+	ParametersRef *GatewayClassParametersObjectReference `json:"parameters,omitempty" protobuf:"bytes,2,opt,name=parametersRef"`
 }
 
+// GatewayClassParametersObjectReference identifies a parameters object for a
+// gateway class within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type GatewayClassParametersObjectReference = LocalObjectReference
+
 // GatewayClassConditionType is the type of status conditions.
 type GatewayClassConditionType string
 

api/v1alpha1/httproute_types.go

@@ -16,7 +16,6 @@ limitations under the License.
 package v1alpha1
 
 import (
-	core "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
@@ -43,13 +42,15 @@ type HTTPRouteHost struct {
 	// Rules are a list of HTTP matchers, filters and actions.
 	Rules []HTTPRouteRule `json:"rules"`
 
-	// Extension is an optional, implementation-specific extension
-	// to the "host" block.
+	// Extension is an optional, implementation-specific extension to the
+	// "host" block.  The resource may be "configmap" (use the empty string
+	// for the group) or an implementation-defined resource (for example,
+	// resource "myroutehost" in group "networking.acme.io").
 	//
 	// Support: custom
 	//
 	// +optional
-	Extension *core.TypedLocalObjectReference `json:"extension"`
+	Extension *RouteHostExtensionObjectReference `json:"extension"`
 }
 
 // HTTPRouteRule is the configuration for a given path.
@@ -107,15 +108,23 @@ type HTTPRouteMatch struct {
 	// +optional
 	Header map[string]string `json:"header"`
 
-	// Extension is an optional, implementation-specific extension
-	// to the "match" behavior.
+	// Extension is an optional, implementation-specific extension to the
+	// "match" behavior.  The resource may be "configmap" (use the empty
+	// string for the group) or an implementation-defined resource (for
+	// example, resource "myroutematcher" in group "networking.acme.io").
 	//
 	// Support: custom
 	//
 	// +optional
-	Extension *core.TypedLocalObjectReference `json:"extension"`
+	Extension *RouteMatchExtensionObjectReference `json:"extension"`
 }
 
+// RouteMatchExtensionObjectReference identifies a route-match extension object
+// within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type RouteMatchExtensionObjectReference = LocalObjectReference
+
 // HTTPRouteFilter defines a filter-like action to be applied to
 // requests.
 type HTTPRouteFilter struct {
@@ -125,15 +134,23 @@ type HTTPRouteFilter struct {
 	// +optional
 	Headers *HTTPHeaderFilter `json:"headers"`
 
-	// Extension is an optional, implementation-specific extension
-	// to the "filter" behavior.
+	// Extension is an optional, implementation-specific extension to the
+	// "filter" behavior.  The resource may be "configmap" (use the empty
+	// string for the group) or an implementation-defined resource (for
+	// example, resource "myroutefilter" in group "networking.acme.io").
 	//
 	// Support: custom
 	//
 	// +optional
-	Extension *core.TypedLocalObjectReference `json:"extension"`
+	Extension *RouteFilterExtensionObjectReference `json:"extension"`
 }
 
+// RouteFilterExtensionObjectReference identifies a route-filter extension
+// object within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type RouteFilterExtensionObjectReference = LocalObjectReference
+
 // HTTPHeaderFilter defines the filter behavior for a request match.
 type HTTPHeaderFilter struct {
 	// Add adds the given header (name, value) to the request
@@ -178,21 +195,56 @@ type HTTPHeaderFilter struct {
 
 // HTTPRouteAction is the action taken given a match.
 type HTTPRouteAction struct {
-	// ForwardTo sends requests to the referenced object.
-	ForwardTo *core.TypedLocalObjectReference `json:"forwardTo"`
+	// ForwardTo sends requests to the referenced object.  The resource may
+	// be "service" (use the empty string for the group), or an
+	// implementation may support other resources (for example, resource
+	// "myroutetarget" in group "networking.acme.io").
+	ForwardTo *RouteActionTargetObjectReference `json:"forwardTo"`
 
-	// Extension is an optional, implementation-specific extension
-	// to the "action" behavior.
+	// Extension is an optional, implementation-specific extension to the
+	// "action" behavior.  The resource may be "configmap" (use the empty
+	// string for the group) or an implementation-defined resource (for
+	// example, resource "myrouteaction" in group "networking.acme.io").
 	//
 	// Support: custom
 	//
 	// +optional
-	Extension *core.TypedLocalObjectReference `json:"extension"`
+	Extension *RouteActionExtensionObjectReference `json:"extension"`
 }
 
-// HTTPRouteStatus defines the observed state of HTTPRoute
+// RouteActionTargetObjectReference identifies a target object for a route
+// action within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type RouteActionTargetObjectReference = LocalObjectReference
+
+// RouteActionExtensionObjectReference identifies a route-action extension
+// object within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type RouteActionExtensionObjectReference = LocalObjectReference
+
+// RouteHostExtensionObjectReference identifies a route-host extension object
+// within a known namespace.
+//
+// +k8s:deepcopy-gen=false
+type RouteHostExtensionObjectReference = LocalObjectReference
+
+// HTTPRouteStatus defines the observed state of HTTPRoute.
 type HTTPRouteStatus struct {
-	Gateways []core.ObjectReference `json:"gateways"`
+	Gateways []GatewayObjectReference `json:"gateways"`
+}
+
+// GatewayObjectReference identifies a Gateway object.
+type GatewayObjectReference struct {
+	// Namespace is the namespace of the referent.
+	// +optional
+	Namespace string `json:"namespace,omitempty"`
+	// Name is the name of the referent.
+	//
+	// +kubebuilder:validation:Required
+	// +required
+	Name string `json:"name"`
 }
 
 // +kubebuilder:object:root=true