Making Gateway Status more descriptive

api/v1alpha1/gateway_types.go

@@ -70,7 +70,11 @@ const (
 
 // Listener defines a
 type Listener struct {
-	// Address bound on the listener. This is optional and behavior
+	// Name can be used to tie this Listener to a ListenerStatus entry with the
+	// same name. Each listener must have a unique name within a Gateway. This
+	// must be a valid DNS_LABEL.
+	Name string `json:"string"`
+	// Address requested for this listener. This is optional and behavior
 	// can depend on GatewayClass. If a value is set in the spec and
 	// the request address is invalid, the GatewayClass MUST indicate
 	// this in the associated entry in GatewayStatus.Listeners.
@@ -113,8 +117,7 @@ const (
 	NamedAddress = "NamedAddress"
 )
 
-// ListenerAddress describes an address bound by the
-// Listener.
+// ListenerAddress describes an address bound by the Listener.
 type ListenerAddress struct {
 	// Type of the Address. This is one of the *AddressType constants.
 	//
@@ -179,56 +182,95 @@ type ListenerTLS struct {
 
 // GatewayStatus defines the observed state of Gateway
 type GatewayStatus struct {
-	// TODO overall status
-
-	// Listeners is the status for each listener block in the
-	// Spec. The status for a given block will match the order as
-	// declared in the Spec, e.g. the status for Spec.Listeners[3]
-	// will be in Status.Listeners[3].
+	// Conditions describe the current conditions of the Gateway.
+	Conditions []GatewayCondition `json:"conditions"`
+	// Listeners provide status for each listener defined in the Spec. The name
+	// in ListenerStatus refers to the corresponding Listener of the same name.
 	Listeners []ListenerStatus `json:"listeners"`
-	// Routes is the status for each attached route to the
-	// Gateway. The status for a given route will match the orer as
-	// declared in the Spec, e.g. the status for Spec.Routes[3] will
-	// be in Status.Routes[3].
-	Routes []GatewayRouteStatus `json:"routes"`
+}
+
+// GatewayConditionType is a type of condition associated with a Gateway.
+type GatewayConditionType string
+
+const (
+	// ConditionNoSuchGatewayClass indicates that the specified GatewayClass
+	// does not exist.
+	ConditionNoSuchGatewayClass GatewayConditionType = "NoSuchGatewayClass"
+	// ConditionGatewayNotScheduled indicates that the Gateway has not been
+	// scheduled.
+	ConditionGatewayNotScheduled GatewayConditionType = "GatewayNotScheduled"
+	// ConditionListenersNotReady indicates that at least one of the specified
+	// listeners os not ready.
+	ConditionListenersNotReady GatewayConditionType = "ListenersNotReady"
+	// ConditionInvalidListeners indicates that at least one of the specified
+	// routes is invalid.
+	ConditionInvalidListeners GatewayConditionType = "InvalidListeners"
+	// ConditionRoutesNotReady indicates that at least one of the specified
+	// routes is not ready.
+	ConditionRoutesNotReady GatewayConditionType = "RoutesNotReady"
+	// ConditionInvalidRoutes indicates that at least one of the specified
+	// routes is invalid.
+	ConditionInvalidRoutes GatewayConditionType = "InvalidRoutes"
+)
+
+// GatewayCondition is an error status for a given route.
+type GatewayCondition struct {
+	// Type indicates the type of condition.
+	Type GatewayConditionType `json:"type"`
+	// Status describes the current state of this condition. Can be "True",
+	// "False", or "Unknown".
+	Status core.ConditionStatus `json:"status"`
+	// Message is a human-understandable message describing the condition.
+	Message string `json:"message"`
+	// Reason indicates why the condition is in this state.
+	// +optional
+	Reason string `json:"reason"`
+	// LastTransitionTime indicates the last time this condition changed.
+	// +optional
+	LastTransitionTime metav1.Time `json:"lastTransitionTime"`
 }
 
 // ListenerStatus is the status associated with each listener block.
 type ListenerStatus struct {
-	// Errors is a list of reasons why a given Listener Spec is
-	// not valid. Errors will be empty if the Spec is valid.
-	Errors []ListenerError `json:"errors"`
-
-	//
-	Address string `json:"address"`
+	// Name is the name of the listener this status refers to.
+	Name string `json:"name"`
+	// Address bound on this listener.
+	Address *ListenerAddress `json:"address"`
+	// Conditions describe the current condition of this listener.
+	Conditions []ListenerCondition `json:"conditions"`
 }
 
-// ListenerErrorReason is the type for errors associated with the
-// listener.
-type ListenerErrorReason string
+// ListenerConditionType is a type of condition associated with the listener.
+type ListenerConditionType string
 
 const (
-	// ErrListenerInvalidSpec is a generic error that is a
-	// catch all for unsupported configurations that do not match a
-	// more specific error. Implementors should try to use more
-	// specific errors instead of this one to give users and
-	// automation a more information.
-	ErrListenerInvalidSpec ListenerErrorReason = "InvalidSpec"
-	// ErrListenerBadAddress indicates the Address
-	ErrListenerBadAddress ListenerErrorReason = "InvalidAddress"
+	// ConditionInvalidListener is a generic condition that is a catch all for
+	// unsupported configurations that do not match a more specific condition.
+	// Implementors should try to use more specific condition instead of this
+	// one to give users and automation a more information.
+	ConditionInvalidListener ListenerConditionType = "InvalidListener"
+	// ConditionInvalidAddress indicates the Address is invalid.
+	ConditionInvalidAddress ListenerConditionType = "InvalidAddress"
+	// ConditionNoSuchListener indicates the listener does not exist.
+	ConditionNoSuchListener ListenerConditionType = "NoSuchListener"
 )
 
-// ListenerError is an error status for a given ListenerSpec.
-type ListenerError struct {
-	// Reason is a automation friendly reason code for the error.
-	Reason ListenerErrorReason `json:"reason"`
-	// Message is a human-understandable error message.
+// ListenerCondition is an error status for a given listener.
+type ListenerCondition struct {
+	// Type indicates the type of condition. Can be "InvalidListener",
+	// "InvalidAddress", or "NoSuchListener".
+	Type ListenerConditionType `json:"type"`
+	// Status describes the current state of this condition. Can be "True",
+	// "False", or "Unknown".
+	Status core.ConditionStatus `json:"status"`
+	// Message is a human-understandable message describing the condition.
 	Message string `json:"message"`
-}
-
-// GatewayRouteStatus is the status associated with a given (Gateway,
-// Route) pair.
-type GatewayRouteStatus struct {
+	// Reason indicates why the condition is in this state.
+	// +optional
+	Reason string `json:"reason"`
+	// LastTransitionTime indicates the last time this condition changed.
+	// +optional
+	LastTransitionTime metav1.Time `json:"lastTransitionTime"`
 }
 
 func init() {

docs-src/concepts.md

@@ -17,7 +17,7 @@ limitations under the License.
 # API Concepts
 
 This document is a deep dive into the reasoning and design for the API. The
-content of this document is taken from the [API sketch][api-sketch]. 
+content of this document is taken from the [API sketch][api-sketch].
 
 > We will try to keep the two documents in sync as the sketch document has to
 > lowest bar to contribution, but this document is easier to format well and
@@ -30,7 +30,7 @@ content of this document is taken from the [API sketch][api-sketch].
 In the original design of Kubernetes, the Ingress and Service resources were
 based on a self-service model of usage; developers who create Services and
 Ingresses control all aspects of defining and exposing their applications to
-their users. 
+their users.
 
 We have found that the self-service model does not fully capture some of the
 more complex deployment and team structures that our users are seeing. The
@@ -121,7 +121,7 @@ kind: GatewayClass
 metadata:
   name: from-internet
 controller:                          # links to a custom resource
-  apiGroup: networking.acme.io       # that implements this class. 
+  apiGroup: networking.acme.io       # that implements this class.
   kind: cloud-lb
   name: from-internet
 ```
@@ -161,13 +161,14 @@ The Gateway spec defines the following:
 
 * GatewayClass used to instantiate this Gateway.
 * Listener bindings, which define addresses and ports, protocol termination,
-  TLS-settings. Listener configuration requested by a Gateway definition can be
-  incompatible with a given GatewayClass (e.g. port/protocol combination is not
-  supported)
+  TLS-settings.
 
-. In this case, the Gateway will be in an error state, signalled by the status field.
+Listener configuration requested by a Gateway definition can be incompatible
+with a given GatewayClass (e.g. port/protocol combination is not supported). In
+this case, the Gateway will be in an error state, signalled by the status field.
 Routes, which point to a set of protocol-specific routing served by the Gateway.
-OPTIONAL: A Gateway can point directly to Kubernetes Service if no advanced routing is required.
+A Gateway can point directly to Kubernetes Service if no advanced routing is
+required.
 
 #### Deployment models
 
@@ -185,6 +186,15 @@ The API does not specify which one of these actions will be taken. Note that a
 GatewayClass controller that manages in-cluster proxy processes MAY restrict
 Gateway configuration scope, e.g. only be served in the same namespace.
 
+#### Gateway Status
+
+Gateways track status for the Gateway resource as a whole as well as each
+Listener it contains. Status can be tracked indepently on each Route resource.
+Within GatewayStatus, Listeners will have status entries corresponding to their
+name. Both GatewayStatus and ListenerStatus follow the conditions pattern used
+elsewhere in Kubernetes. This is a list that includes a type of condition, the
+status of that condition, and the last time this condition changed.
+
 #### Listeners
 
 TODO