[GEP-1651]: Updated Types & Move to Experimental

apis/v1alpha2/doc.go

@@ -16,6 +16,7 @@ limitations under the License.
 
 // Package v1alpha2 contains API Schema definitions for the
 // gateway.networking.k8s.io API group.
+//
 // +kubebuilder:object:generate=true
 // +groupName=gateway.networking.k8s.io
 package v1alpha2

apis/v1beta1/doc.go

@@ -16,6 +16,7 @@ limitations under the License.
 
 // Package v1beta1 contains API Schema definitions for the
 // gateway.networking.k8s.io API group.
+//
 // +kubebuilder:object:generate=true
 // +groupName=gateway.networking.k8s.io
 package v1beta1

apis/v1beta1/gateway_types.go

@@ -119,6 +119,12 @@ type GatewaySpec struct {
 	// +kubebuilder:validation:MaxItems=64
 	Listeners []Listener `json:"listeners"`
 
+	// Infrastructure defines infrastructure level attributes about this Gateway instance.
+	//
+	// <gateway:experimental>
+	// +optional
+	Infrastructure *GatewayInfrastructure `json:"infrastructure,omitempty"`
+
 	// Addresses requested for this Gateway. This is optional and behavior can
 	// depend on the implementation. If a value is set in the spec and the
 	// requested address is invalid or unavailable, the implementation MUST
@@ -148,6 +154,69 @@ type GatewaySpec struct {
 	Addresses []GatewayAddress `json:"addresses,omitempty"`
 }
 
+// GatewayInfrastructure defines infrastructure level attributes about a Gateway
+type GatewayInfrastructure struct {
+	// Routability allows the Gateway to specify the accessibility of its addresses. Setting
+	// this property will override the default value defined by the GatewayClass.
+	//
+	// If the desired Gateway routability is incompatible with the GatewayClass implementations
+	// MUST set the condition `Accepted` to `False` with `Reason` set to `UnsupportedRoutability`.
+	//
+	// The default value of routability is implementation specific and MUST remain consistent for
+	// Gateways with the same gatewayClassName
+	//
+	// Implementations MUST clearly document if they support updates to this field. The default
+	// expectation should be that changes to this field are not supported unless an implementation
+	// specifies otherwise.
+	//
+	// If a Gateway is mutated but does not support the desired routability it MUST set the `Accepted`
+	// and `Programmed` conditions to `False` with `Reason` set to `UnsupportedRoutability`.
+	//
+	// +optional
+	Routability *GatewayRoutability `json:"routability,omitempty"`
+}
+
+// GatewayRoutablility represents the routability of a Gateway
+//
+// The pre-defined values listed in this package can be compared semantically.
+// `Public` has a larger scope than `Private`, while `Private` has a larger scope than
+// `Cluster`.
+//
+// Implementations can define custom routability values by specifying a vendor
+// prefix followed by a slash '/' and a custom name ie. `dev.example.com/my-routability`.
+//
+// +kubebuilder:validation:MinLength=1
+// +kubebuilder:validation:MaxLength=253
+// +kubebuilder:validation:Pattern=`^Public|Private|Cluster|[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-_]+$`
+type GatewayRoutability string
+
+const (
+	// GatewayRoutabilityPublic means the Gateway's address MUST
+	// be routable on the public internet.
+	//
+	// Support: Extended
+	GatewayRoutabilityPublic GatewayRoutability = "Public"
+
+	// GatewayRoutabilityPrivate means the Gateway's address MUST
+	// only be routable inside a private network larger than a single
+	// cluster (ie. VPC) and MAY include the RFC1918 address space.
+	//
+	// It is RECOMMENDED that in-cluster gateways SHOULD NOT support 'Private' routability.
+	// Kubernetes doesn't have a concept of 'Private' routability for Services. In the future this may
+	// change upstream.
+	//
+	// Support: Extended
+	GatewayRoutabilityPrivate GatewayRoutability = "Private"
+
+	// GatewayRoutabilityCluster means the Gateway's address MUST
+	// only be routable inside the [cluster's network].
+	//
+	// Support: Extended
+	//
+	// [cluster's network]: https://kubernetes.io/docs/concepts/cluster-administration/networking/#how-to-implement-the-kubernetes-network-model
+	GatewayRoutabilityCluster GatewayRoutability = "Cluster"
+)
+
 // Listener embodies the concept of a logical endpoint where a Gateway accepts
 // network connections.
 type Listener struct {
@@ -473,16 +542,52 @@ type GatewayAddress struct {
 	Value string `json:"value"`
 }
 
+// GatewayStatusAddress describes an address that is bound to a Gateway.
+type GatewayStatusAddress struct {
+	// Type of the address.
+	//
+	// +optional
+	// +kubebuilder:default=IPAddress
+	Type *AddressType `json:"type,omitempty"`
+
+	// Value of the address. The validity of the values will depend
+	// on the type and support by the controller.
+	//
+	// Examples: `1.2.3.4`, `128::1`, `my-ip-address`.
+	//
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
+	Value string `json:"value"`
+
+	// Routability specifies the routable bounds of this address
+	// Predefined values are: 'Private', 'Public', Cluster
+	// Other values MUST have a vendor prefix.
+	//
+	// Implementations that support Routability MUST populate this field
+	//
+	// +optional
+	// <gateway:experimental>
+	Routability *GatewayRoutability `json:"routability,omitempty"`
+}
+
 // GatewayStatus defines the observed state of Gateway.
 type GatewayStatus struct {
 	// Addresses lists the IP addresses that have actually been
 	// bound to the Gateway. These addresses may differ from the
 	// addresses in the Spec, e.g. if the Gateway automatically
 	// assigns an address from a reserved pool.
 	//
+	// Implementations that support GatewayRoutability MUST include an address
+	// that has the same routable semantics as defined in the Gateway spec.
+	//
+	// Implementations MAY add additional addresses in status, but they MUST be
+	// semantically less than the scope of the requested scope. For example if a
+	// user requests a `Private` routable Gateway then an additional address MAY
+	// have a routability of `Cluster` but MUST NOT include `Public`.
+	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=16
-	Addresses []GatewayAddress `json:"addresses,omitempty"`
+	Addresses []GatewayStatusAddress `json:"addresses,omitempty"`
 
 	// Conditions describe the current conditions of the Gateway.
 	//
@@ -572,6 +677,10 @@ const (
 	// express a range of circumstances, including (but not limited to) IPAM
 	// address exhaustion, address not yet allocated, or a named address not being found.
 	GatewayReasonAddressNotAssigned GatewayConditionReason = "AddressNotAssigned"
+
+	// This reason is used with "Programmed" and "Accepted" conditions when
+	// desired routability is not able to be fulfilled by the implementation
+	GatewayUnsupportedRoutability GatewayConditionReason = "UnsupportedRoutability"
 )
 
 const (

apis/v1beta1/gatewayclass_types.go

@@ -183,6 +183,21 @@ const (
 
 // GatewayClassStatus is the current status for the GatewayClass.
 type GatewayClassStatus struct {
+	// Routabilities specifies a list of supported routabilities offered by
+	// the GatewayClass. The first entry in this list will be the default
+	// routability used when Gateways of this class are created.
+	//
+	// Implementations MAY provide a pre-defined set of GatewayClasses that
+	// limit the routability choices of a Gateway.
+	//
+	// Implementations MUST populate this list with the GatewayRoutability values
+	// that are supported by this GatewayClass.
+	//
+	// +optional
+	// +kubebuilder:validation:MaxItems=8
+	// <gateway:experimental>
+	Routabilities []GatewayRoutability `json:"routabilities,omitempty"`
+
 	// Conditions is the current status from the controller for
 	// this GatewayClass.
 	//