Reorganizes Docs and Adds HTTPRoute Resource Doc

apis/v1alpha1/gateway_types.go

@@ -373,8 +373,8 @@ const (
 )
 
 // RouteBindingSelector defines a schema for associating routes with the Gateway.
-// If NamespaceSelector and RouteSelector are defined, only routes matching both
-// selectors are associated with the Gateway.
+// If Namespaces and Selector are defined, only routes matching both selectors are
+// associated with the Gateway.
 type RouteBindingSelector struct {
 	// Namespaces indicates in which namespaces Routes should be selected
 	// for this Gateway. This is restricted to the namespace of this Gateway by

apis/v1alpha1/httproute_types.go

@@ -116,7 +116,7 @@ type RouteTLSConfig struct {
 	// This certificate MUST be used for TLS handshakes for the domain
 	// this RouteTLSConfig is associated with.
 	// If an entry in this list omits or specifies the empty
-	// string for both the group and the resource, the resource defaults to "secrets".
+	// string for both the group and kind, the resource defaults to "secrets".
 	// An implementation may support other resources (for example, resource
 	// "mycertificates" in group "networking.acme.io").
 	// Support: Core (Kubernetes Secrets)
@@ -126,9 +126,9 @@ type RouteTLSConfig struct {
 	CertificateRef LocalObjectReference `json:"certificateRef"`
 }
 
-// HTTPRouteRule defines semantics for matching an incoming HTTP request against
-// a set of matching rules and executing an action (and optionally filters) on
-// the request.
+// HTTPRouteRule defines semantics for matching an HTTP request based on
+// conditions, optionally executing additional processing steps, and forwarding
+// the request to an API object.
 type HTTPRouteRule struct {
 	// Matches define conditions used for matching the rule against
 	// incoming HTTP requests.

docs-src/concepts.md → docs-src/api-overview.md

@@ -1,10 +1,10 @@
-# API Concepts
+# API Overview
 
-This document is a deep dive into the reasoning and design for Service APIs.
+This document provides an overview of Service APIs.
 
 ## Roles and personas.
 
-There are 3 primary roles in the API:
+There are 3 primary roles in Service APIs:
 
 - Infrastructure Provider
 - Cluster Operator

docs-src/gateway.md

@@ -0,0 +1,47 @@
+# Gateway
+
+A `Gateway` is 1:1 with the life cycle of the configuration of infrastructure.
+When a user creates a `Gateway`, some load balancing infrastructure is
+provisioned or configured (see below for details) by the `GatewayClass`
+controller. `Gateway` is the resource that triggers actions in this API. Other
+resources in this API are configuration snippets until a Gateway has been
+created to link the resources together.
+
+The `Gateway` spec defines the following:
+
+*   `GatewayClassName`- Defines the name of a `GatewayClass` object used by
+    this Gateway.
+*   `Listeners`-  Define the hostnames, ports, protocol, termination, TLS
+    settings and which routes should be associated to a listener.
+*   `Addresses`- Define the network addresses requested for this gateway.
+
+If the desired configuration specified in Gateway spec cannot be achieved, the
+Gateway will be in an error state with details provided by status conditions.
+
+### Deployment models
+
+Depending on the `GatewayClass`, the creation of a `Gateway` could do any of
+the following actions:
+
+* Use cloud APIs to create an LB instance.
+* Spawn a new instance of a software LB (in this or another cluster).
+* Add a configuration stanza to an already instantiated LB to handle the new
+  routes.
+* Program the SDN to implement the configuration.
+* Something else we haven’t thought of yet...
+
+The API does not specify which one of these actions will be taken.
+
+### Gateway Status
+
+`GatewayStatus` is used to surface the status of a `Gateway` relative to the
+desired state represented in `spec`. `GatewayStatus` consists of the following:
+
+- `Addresses`- Lists the IP addresses that have actually been bound to the
+  Gateway.
+- `Listeners`- Provide status for each unique listener port defined in `spec`.
+- `Conditions`- Describe the current status conditions of the Gateway.  
+
+Both `Conditions` and `Listeners.conditions` follow the conditions pattern used
+elsewhere in Kubernetes. This is a list that includes a type of condition, the
+status of the condition and the last time this condition changed.

docs-src/gatewayclass.md

@@ -0,0 +1,139 @@
+# GatewayClass
+
+[GatewayClass][gatewayclass] is cluster-scoped resource defined by the
+infrastructure provider. This resource represents a class of Gateways that can
+be instantiated.
+
+> Note: GatewayClass serves the same function as the
+> [`networking.IngressClass` resource][ingress-class-api].
+
+```yaml
+kind: GatewayClass
+metadata:
+  name: cluster-gateway
+spec:
+  controller: "acme.io/gateway-controller"
+```
+
+We expect that one or more `GatewayClasses` will be created by the
+infrastructure provider for the user. It allows decoupling of which mechanism
+(e.g. controller) implements the `Gateways` from the user. For instance, an
+infrastructure provider may create two `GatewayClasses` named `internet` and
+`private` to reflect `Gateways` that define Internet-facing vs private, internal
+applications.
+
+```yaml
+kind: GatewayClass
+metadata:
+  name: internet
+  ...
+---
+kind: GatewayClass
+metadata:
+  name: private
+  ...
+```
+
+The user of the classes will not need to know *how* `internet` and `private` are
+implemented. Instead, the user will only need to understand the resulting
+properties of the class that the `Gateway` was created with.
+
+### GatewayClass parameters
+
+Providers of the `Gateway` API may need to pass parameters to their controller
+as part of the class definition. This is done using the
+`GatewayClass.spec.parametersRef` field:
+
+```yaml
+# GatewayClass for Gateways that define Internet-facing applications.
+kind: GatewayClass
+metadata:
+  name: internet
+spec:
+  controller: "acme.io/gateway-controller"
+  parametersRef:
+    group: acme.io/v1alpha1
+    kind: Config
+    name: internet-gateway-config
+---
+kind: Config
+apiVersion: acme.io/v1alpha1
+metadata:
+  name: internet-gateway-config
+spec:
+  ip-address-pool: internet-vips
+  ...
+```
+
+Using a Custom Resource for `GatewayClass.spec.parametersRef` is encouraged
+but implementations may resort to using a ConfigMap if needed.
+
+### GatewayClass status
+
+`GatewayClasses` MUST be validated by the provider to ensure that the configured
+parameters are valid. The validity of the class will be signaled to the user via
+`GatewayClass.status`:
+
+```yaml
+kind: GatewayClass
+...
+status:
+  conditions:
+  - type: InvalidParameters
+    status: Unknown
+    ...
+```
+
+A new `GatewayClass` will start with the `InvalidParameters` condition set to
+`Unknown`. At this point the controller has not seen the configuration. Once the
+controller has processed the configuration, the condition will be set to
+`False`:
+
+```yaml
+kind: GatewayClass
+...
+status:
+  conditions:
+  - type: InvalidParameters
+    status: False
+    ...
+```
+
+If there is an error in the `GatewayClass.spec`, the conditions will be
+non-empty and contain information about the error.
+
+```yaml
+kind: GatewayClass
+...
+status:
+  conditions:
+  - type: InvalidParameters
+    status: True
+    Reason: BadFooBar
+    Message: "foobar" is an FooBar.
+```
+
+### GatewayClass controller selection
+
+The `GatewayClass.spec.controller` field determines the controller implementation
+responsible for managing the `GatewayClass`. The format of the field is opaque
+and specific to a particular controller. The GatewayClass selected by a given
+controller field depends on how various controller(s) in the cluster interpret
+this field.
+
+It is RECOMMENDED that controller authors/deployments make their selection
+unique by using a domain / path combination under their administrative control
+(e.g. controller managing of all `controller`s starting with `acme.io` is the
+owner of the `acme.io` domain) to avoid conflicts.
+
+Controller versioning can be done by encoding the version of a controller into
+the path portion. An example scheme could be (similar to container URIs):
+
+```text
+acme.io/gateway/v1   // Use version 1
+acme.io/gateway/v2   // Use version 2
+acme.io/gateway      // Use the default version
+```
+
+[gatewayclass]: https://kubernetes-sigs.github.io/service-apis/spec/#networking.x-k8s.io/v1alpha1.GatewayClass
+[ingress-class-api]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-network/20190125-ingress-api-group.md#ingressclass-resource