Skip to content

Commit

Permalink
Making Gateway Status more descriptive
Browse files Browse the repository at this point in the history
  • Loading branch information
@robscott
robscott committed Jan 21, 2020
1 parent 453aeb8 commit 2b8bd7e
Show file tree
Hide file tree
Showing 7 changed files with 177 additions and 63 deletions.
93 changes: 65 additions & 28 deletions api/v1alpha1/gateway_types.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,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.
//
Expand Down Expand Up @@ -179,8 +178,6 @@ 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]
Expand All @@ -195,40 +192,80 @@ type GatewayStatus struct {

// 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"`
// 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"`
// M+essage 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"`
}

// GatewayRouteStatus is the status associated with a given (Gateway,
// Route) pair.
// GatewayRouteStatus is the status associated with each route block.
type GatewayRouteStatus struct {
// Conditions describe the current condition of this route.
Conditions []GatewayRouteCondition `json:"conditions"`
}

// GatewayRouteConditionType is a type of condition associated with the route.
type GatewayRouteConditionType string

const (
// ConditionInvalidRoute 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.
ConditionInvalidRoute GatewayRouteConditionType = "InvalidRoute"
// ConditionNoSuchRoute indicates the route does not exist.
ConditionNoSuchRoute GatewayRouteConditionType = "NoSuchRoute"
)

// GatewayRouteCondition is an error status for a given route.
type GatewayRouteCondition struct {
// Type indicates the type of condition. Can be "InvalidRoute" or
// "NoSuchRoute".
Type ListenerConditionType `json:"type"`
// Status describes the current state of this condition. Can be "True",
// "False", or "Unknown".
Status core.ConditionStatus `json:"status"`
// M+essage 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"`
}

func init() {
Expand Down
51 changes: 42 additions & 9 deletions api/v1alpha1/zz_generated.deepcopy.go
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 25 additions & 8 deletions docs-src/concepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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

Expand All @@ -185,6 +186,22 @@ 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 Listeners and Routes. This is in addition to status
that can be tracked indepently on each Listener or Route resource, providing a
consistent status API for both Listeners and Routes. This is important because
Listeners and Routes can be a variety of different resources with different
status fields.

Within Gateway status, Listeners and Routes will have status entries
corresponding to their placement in the Gateway spec. A Route that is listed
second in the Gateway spec will also be listed second in the Gateway status.

Status for both Listeners and Routes here follows 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
Expand Down
43 changes: 35 additions & 8 deletions docs/concepts/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,13 @@
Deployment models
</a>

</li>

<li class="md-nav__item">
<a href="#gateway-status" class="md-nav__link">
Gateway Status
</a>

</li>

<li class="md-nav__item">
Expand Down Expand Up @@ -558,6 +565,13 @@
Deployment models
</a>

</li>

<li class="md-nav__item">
<a href="#gateway-status" class="md-nav__link">
Gateway Status
</a>

</li>

<li class="md-nav__item">
Expand Down Expand Up @@ -660,7 +674,7 @@

<h1 id="api-concepts">API Concepts</h1>
<p>This document is a deep dive into the reasoning and design for the API. The
content of this document is taken from the <a href="https://docs.google.com/document/d/1BxYbDovMwnEqe8lj8JwHo8YxHAt3oC7ezhlFsG_tyag/preview">API sketch</a>. </p>
content of this document is taken from the <a href="https://docs.google.com/document/d/1BxYbDovMwnEqe8lj8JwHo8YxHAt3oC7ezhlFsG_tyag/preview">API sketch</a>.</p>
<blockquote>
<p>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
Expand All @@ -670,7 +684,7 @@ <h2 id="roles-and-personas">Roles and personas</h2>
<p>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. </p>
their users.</p>
<p>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
Gateway/Routes API will target the following personas:</p>
Expand Down Expand Up @@ -748,7 +762,7 @@ <h3 id="gatewayclass">GatewayClass</h3>
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
</code></pre>
Expand Down Expand Up @@ -784,13 +798,14 @@ <h3 id="gateway">Gateway</h3>
<ul>
<li>GatewayClass used to instantiate this Gateway.</li>
<li>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)</li>
TLS-settings.</li>
</ul>
<p>. In this case, the Gateway will be in an error state, signalled by the status field.
<p>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.</p>
A Gateway can point directly to Kubernetes Service if no advanced routing is
required.</p>
<h4 id="deployment-models">Deployment models</h4>
<p>Depending on the <code>GatewayClass</code>, the creation of the <code>Gateway</code> could do any of
the following actions:</p>
Expand All @@ -805,6 +820,18 @@ <h4 id="deployment-models">Deployment models</h4>
<p>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.</p>
<h4 id="gateway-status">Gateway Status</h4>
<p>Gateways track status for Listeners and Routes. This is in addition to status
that can be tracked indepently on each Listener or Route resource, providing a
consistent status API for both Listeners and Routes. This is important because
Listeners and Routes can be a variety of different resources with different
status fields.</p>
<p>Within Gateway status, Listeners and Routes will have status entries
corresponding to their placement in the Gateway spec. A Route that is listed
second in the Gateway spec will also be listed second in the Gateway status.</p>
<p>Status for both Listeners and Routes here follows 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.</p>
<h4 id="listeners">Listeners</h4>
<p>TODO</p>
<h3 id="routes">Routes</h3>
Expand Down
2 changes: 1 addition & 1 deletion docs/search/search_index.json
View file

Large diffs are not rendered by default.

Loading

0 comments on commit 2b8bd7e

Please sign in to comment.