[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,11 @@ type GatewaySpec struct {
 	// +kubebuilder:validation:MaxItems=64
 	Listeners []Listener `json:"listeners"`
 
+	// Infrastructure defines infrastructure level attributes about this Gateway instance.
+	//
+	// +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 +153,68 @@ 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 it's 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.
+	// It is RECOMMENDED that the default routability remains consistent for Gateways with the same
+	// gatewayClassName
+	//
+	// Implementations MAY leave this property unset and signal the default
+	// routability in the [GatewayStatus]
+	//
+	// Implementations MAY prevent end-users from updating the routability value of a Gateway.
+	// If updates are allowed the semantics and behavior will depend on the underlying implementation.
+	// If a Gateway is mutated but does not support the desired routability it MUST set the conditions
+	// `Accepted`, `Programmed` to `False` with `Reason` set to `UnsupportedRoutability`.
+	//
+	// 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.
+	//
+	// +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.
+// [GatewayRoutabilityPublic] has a larger scope than [GatewayRoutabilityPrivate],
+// while [GatewayRoutabilityPrivate] has a larger scope than
+// [GatewayRoutabilityCluster].
+//
+// 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`.
+type GatewayRoutability string
+
+const (
+	// GatewayRoutabilityPublic means the Gateway's address MUST
+	// be routable on the public internet
+	//
+	// Implementations MAY support this routability
+	GatewayRoutabilityPublic GatewayRoutability = "Public"
+
+	// GatewayRoutabilityPrivate means the Gateway's address MUST
+	// be routable inside a private network larger than a single
+	// cluster (ie. VPC) and MAY include the RFC1918 address space
+	//
+	// Implementations MAY support this routability
+	GatewayRoutabilityPrivate GatewayRoutability = "Private"
+
+	// GatewayRoutabilityCluster means the Gateway's address MUST
+	// be only be routable inside the [cluster's network]
+	//
+	// Implementations MAY support this routability
+	//
+	// [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 +540,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
+	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 `Cluster` routable Gateway then the list of addresses
+	// MUST NOT have a routability of `Public` or `Private`.
+	//
+	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=16
-	Addresses []GatewayAddress `json:"addresses,omitempty"`
+	Addresses []GatewayStatusAddress `json:"addresses,omitempty"`
 
 	// Conditions describe the current conditions of the Gateway.
 	//
@@ -522,6 +625,12 @@ type GatewayConditionType string
 // particular Gateway condition type has been raised.
 type GatewayConditionReason string
 
+const (
+	// 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 (
 	// This condition indicates whether a Gateway has generated some
 	// configuration that is assumed to be ready soon in the underlying data

apis/v1beta1/gatewayclass_types.go

@@ -183,6 +183,20 @@ 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.
+	//
+	// Implemenations MAY provide a pre-defined set of GatewayClasses that
+	// limit the routability choices of a Gateway.
+	//
+	// Implementations that support routability MUST populate this list with
+	// a subset of the pre-defined [GatewayRoutability] values or vendored
+	// prefix values.
+	//
+	// +optional
+	Routabilities []GatewayRoutability `json:"routabilities,omitempty"`
+
 	// Conditions is the current status from the controller for
 	// this GatewayClass.
 	//