Initial GAMMA docs take

Signed-off-by: [email protected]

mkdocs.yml

@@ -53,8 +53,11 @@ nav:
     - Concepts:
         API Overview: concepts/api-overview.md
         Conformance: concepts/conformance.md
-        Security Model: concepts/security-model.md
         Implementation Guidelines: concepts/guidelines.md
+        Roles and Personas: concepts/roles-and-personas.md
+        Service Facets: concepts/service-facets.md
+        Security Model: concepts/security-model.md
+        Use Cases: concepts/use-cases.md
         Versioning: concepts/versioning.md
     - Implementations: implementations.md
     - FAQ: faq.md
@@ -112,6 +115,7 @@ nav:
         - geps/gep-724.md
         - geps/gep-718.md
         - geps/gep-709.md
+      - Glossary: concepts/glossary.md
   - Contributing:
     - How to Get Involved: contributing/index.md
     - Developer Guide: contributing/devguide.md

site-src/concepts/api-overview.md

@@ -4,16 +4,13 @@ This document provides an overview of Gateway API.
 
 ## Roles and personas
 
-There are 3 primary roles in Gateway API:
+There are 3 primary roles in Gateway API, as described in [roles and personas]:
 
-- Infrastructure Provider
-- Cluster Operator
-- Application Developer
+- **Ian** (he/him): Infrastructure Provider
+- **Charlie** (they/them): Cluster Operator
+- **Ana** (she/her): Application Developer
 
-There could be a fourth role of Application Admin in some use cases.
-
-Please refer to the [roles and personas](/concepts/security-model#roles-and-personas)
-section in the Security model for details.
+[roles and personas]:/concepts/roles-and-personas
 
 ## Resource model
 
@@ -152,7 +149,7 @@ to configure that with existing Gateway API resources, but implementations may
 provide custom configuration for this until there is a standardized approach
 defined by Gateway API.
 
-### Attaching Routes to Gateways
+## Attaching Routes to Gateways
 
 !!! note
     This section has changed significantly between v1alpha1 and v1alpha2. This
@@ -179,20 +176,22 @@ different relationships that Gateways and Routes can have:
 
 ### Example
 
-A Kubernetes cluster admin has deployed a Gateway `shared-gw` in the `Infra`
-Namespace to be used by different application teams for exposing their
-applications outside the cluster. Teams A and B (in Namespaces `A` and `B`
-respectively) attach their Routes to this Gateway. They are unaware of each
-other and as long as their Route rules do not conflict with each other they
-can continue operating in isolation. Team C has special networking needs
-(perhaps performance, security, or criticality) and they need a dedicated
-Gateway to proxy their application to the outside world. Team C deploys their
-own Gateway `dedicated-gw`  in the `C` Namespace that can only be used by apps
-in the `C` Namespace.
+[Charlie] has deployed a Gateway `shared-gw` in the `infra` Namespace to be
+used by different application teams for exposing their applications outside
+the cluster. Teams A and B (in Namespaces `A` and `B` respectively) attach
+their Routes to this Gateway. They are unaware of each other and as long as
+their Route rules do not conflict with each other they can continue operating
+in isolation. Team C has special networking needs (perhaps performance,
+security, or criticality) and they need a dedicated Gateway to proxy their
+application to the outside world. Team C deploys their own Gateway
+`dedicated-gw`  in the `C` Namespace that can only be used by apps in the `C`
+Namespace.
 
 <!-- source: https://docs.google.com/presentation/d/1neBkFDTZ__vRoDXIWvAcxk2Pb7-evdBT6ykw_frf9QQ/edit?usp=sharing -->
 ![route binding](/images/gateway-route-binding.png)
 
+[Charlie]:/concepts/roles-and-personas#charlie
+
 ### How it Works
 
 The following is required for a Route to be attached to a Gateway:
@@ -279,29 +278,97 @@ relationships between the different resources:
 <!-- source: https://docs.google.com/document/d/1BxYbDovMwnEqe8lj8JwHo8YxHAt3oC7ezhlFsG_tyag/edit#heading=h.8du598fded3c -->
 ![schema](/images/schema-uml.svg)
 
-## Request flow
+### Request flow
 
-A typical client/gateway API request flow for a gateway implemented using a
+A typical [north/south] API request flow for a gateway implemented using a
 reverse proxy is:
 
- 1. A client makes a request to <http://foo.example.com>.
- 2. DNS resolves the name to a `Gateway` address.
- 3. The reverse proxy receives the request on a `Listener` and uses the [Host
- header](https://tools.ietf.org/html/rfc7230#section-5.4) to match an
- `HTTPRoute`.
- 4. Optionally, the reverse proxy can perform request header and/or path
- matching based on `match` rules of the `HTTPRoute`.
- 5. Optionally, the reverse proxy can modify the request, i.e. add/remove
- headers, based on `filter` rules of the `HTTPRoute`.
- 6. Lastly, the reverse proxy forwards the request to one or more objects, i.e.
- `Service`, in the cluster based on `backendRefs` rules of the `HTTPRoute`.
+1. A client makes a request to <http://foo.example.com>.
+2. DNS resolves the name to a `Gateway` address.
+3. The reverse proxy receives the request on a `Listener` and uses the [Host
+   header](https://tools.ietf.org/html/rfc7230#section-5.4) to match an
+   `HTTPRoute`.
+4. Optionally, the reverse proxy can perform request header and/or path
+   matching based on `match` rules of the `HTTPRoute`.
+5. Optionally, the reverse proxy can modify the request, i.e. add/remove
+   headers, based on `filter` rules of the `HTTPRoute`.
+6. Lastly, the reverse proxy forwards the request to one or more objects, i.e.
+   `Service`, in the cluster based on `backendRefs` rules of the `HTTPRoute`.
+
+[north/south]:/concepts/glossary#north-south-traffic
 
-## TLS Configuration
+### TLS Configuration
 
 TLS is configured on Gateway listeners, and may be referred to across namespaces.
 
 Please refer to the [TLS details](/guides/tls) guide for a deep dive on TLS.
 
+## Attaching Routes to Services
+
+When using the Gateway API to configure a [service mesh], the Route will
+attach directly to a Service, representing configuration meant to be applied
+to any traffic directed to the Service. How and which Routes attach to a given
+Service is controlled by the Routes themselves (working with Kubernetes RBAC).
+
+The relationship between the Route's Namespace and the Service's Namespace is
+important:
+
+- Same Namespace <a name="producer-routes"></a>
+
+    A Route in the same Namespace as its Service is called a [producer route]
+    since it is typically created by the creator of the workload in order to
+    define acceptable usage of the workload (for example, [Ana] would deploy
+    both the workload and the Route). All requests from any client of the
+    workload, from any Namespace, will be affected by this Route.
+
+- Different Namespaces <a name="consumer-routes"></a>
+
+    A Route in a different Namespace than its Service is called a [consumer
+    route]. Typically, this is a Route meant to refine how a consumer of a
+    given workload makes request of that workload (for example, configuring
+    custom timeouts for that consumer's use of the workload). This Route will
+    only affect requests from workloads in the same Namespace as the Route.
+
+    There is ongoing [GAMMA] work around the relationship between producer
+    routes and consumer routes. Note also that it is not currently possible to
+    define multiple consumer routes for the same Service in the same
+    Namespace.
+
+[Ana]:/concepts/roles-and-personas#ana
+[producer route]:/concepts/glossary#provider-route
+[consumer route]:/concepts/glossary#consumer-route
+[GAMMA]:/contributing/gamma
+[service mesh]:/concepts/glossary#service-mesh
+
+### How it Works
+
+To attach a Route to a Service, the Route needs an entry in its `parentRefs`
+field referencing the Service. If the Route and the Service are in the same
+Namespace, the Route is a [producer route](#producer-routes); otherwise, it is
+a [consumer route](#consumer-routes). It is not currently possible to define
+multiple consumer routes for the same Service in the same Namespace.
+
+When one or more Routes are attached to a Service, requests that do not match
+at least one of the Routes will be rejected.
+
+### Request flow
+
+A typical [east/west] API request flow is:
+
+1. A client workload makes a request to <http://foo.ns.service.cluster.local>.
+2. The data plane locates the Service matching `foo` in Namespace `ns`.
+3. The data plane locates Routes associated with the `foo` Service.
+4. If the request does not match any Route, it is rejected.
+5. The data plane uses the `backendRefs` of the highest-priority matching
+   Route to select a destination workload.
+6. The data plane routes the request on to the destination workload (most
+   likely using [endpoint routing], but it is allowed to use [Service
+   routing]).
+
+[east/west]:/concepts/glossary#east-west-traffic
+[endpoint routing]:/concepts/glossary#endpoint-routing
+[Service routing]:/concepts/glossary#service-routing
+
 ## Extension points
 
 A number of extension points are provided in the API to provide flexibility in

site-src/concepts/glossary.md

@@ -0,0 +1,66 @@
+# Gateway API Glossary
+
+### Consumer Route
+
+A Route bound to a workload's Service by a consumer of a given workload,
+refining the specific consumer's use of the workload.
+
+### Gateway Controller
+
+A _gateway controller_ is software that runs on a cluster to manage the
+infrastructure associated with routing traffic from outside the cluster to
+inside the cluster (north/south traffic), analogous to the earlier _ingress
+controller_ concept.
+
+### East/West traffic
+
+Traffic from workload to workload within a cluster.
+
+### North/South traffic
+
+Traffic from outside a cluster to inside a cluster (and vice versa).
+
+### Producer Route
+
+A Route bound to a workload's Service by the creator of a given workload,
+defining what is acceptable use of the workload. Producer routes must always
+be in the same Namespace as their workload's Service.
+
+### Service mesh
+
+A _service mesh_ is software that runs on a cluster to manage infrastructure
+providing security, reliability, and observability for communications between
+workloads (east/west traffic).
+
+### Service backend
+
+The part of a Kubernetes Service resource that is a set of endpoints
+associated with Pods and their IPs. Some east/west traffic happens by having
+workloads direct requests to specific endpoints within a Service backend.
+
+### Service frontend
+
+The part of a Kubernetes Service resource that allocates a DNS record and a
+cluster IP. East/west traffic often - but not always - works by having
+workloads direct requests to a Service frontend.
+
+### Service routing
+
+_Service routing_ is sending requests to a specific Service to the service
+frontend, allowing the underlying network infrastructure (usually `kube-proxy`
+or a [service mesh](#service-mesh)) to choose the specific endpoint to which
+the request is routed.
+
+### Endpoint routing
+
+_Endpoint routing_ is sending requests to a specific Service directly to one
+of the endpoints of the Service backend, bypassing routing decisions which
+might be made by the underlying network infrastructure. This is commonly
+necessary for advanced routing cases like sticky sessions, where the gateway
+will need to guarantee that every request for a specific session goes to the
+same endpoint.
+
+### Workload
+
+An instance of computation that provides a function within a cluster. A
+workload usually comprises a Service, some Pods, and often a Deployment.

site-src/concepts/roles-and-personas.md

@@ -0,0 +1,80 @@
+# Roles and personas
+
+## Introduction
+
+In the original design of Kubernetes, Ingress and Service resources were based
+on a usage model in which the developers who create Services and Ingresses
+controlled all aspects of defining and exposing their applications to their
+users.
+
+In practice, though, clusters and their infrastructure tend to be shared,
+which the original Ingress model doesn't capture very well. A critical factor
+is that when infrastructure is shared, not everyone using the infrastructure
+has the same concerns, and to be successful, an infrastructure project needs
+to address the needs of all the users.
+
+This raises a fundamental challenge: how do you provide the flexibility needed
+by the users of the infrastructure, while also maintaining control by the
+owners of the infrastructure?
+
+The Gateway API defines several distinct roles, each with an associated
+_persona_, as a tool for surfacing and discussing the differing needs of
+different users in order to balance usability, flexibility, and control.
+Design work within the Gateway API is deliberately cast in terms of these
+personas.
+
+Note that, depending on the environment, a single human may end up taking on
+multiple roles, as discussed below.
+
+## Roles and Personas
+
+The Gateway API defines three roles and personas:
+
+* <a name="ian">**Ian**</a> (he/him) is an _infrastructure provider_,
+  responsible for the care and feeding of a set of infrastructure that permits
+  multiple isolated clusters to serve multiple tenants. He is not beholden to
+  any single tenant; rather, he worries about all of them collectively. Ian
+  will often work for a cloud provider (AWS, Azure, GCP, ...) or for a PaaS
+  provider.
+
+* <a name="charlie">**Charlie**</a> (they/them) is a _cluster operator_,
+  responsible for managing clusters to ensure that they meet the needs of
+  their several users. Charlie will typically be concerned with policies,
+  network access, application permissions, etc. Again, they are beholden to no
+  single user of any cluster; rather, they need to make sure that the clusters
+  serve all users as needed.
+
+* <a name="ana">**Ana**</a> (she/her) is an _application developer_,
+  responsible for creating and managing an application running in a cluster.
+  From the Gateway API's point of view, Ana will need to manage configuration
+  (e.g. timeouts, request matching/filter) and Service composition (e.g. path
+  routing to backends). She is in a unique position among the Gateway API
+  personas, since her focus is on the business needs her application is meant
+  to serve, _not_ Kubernetes or the Gateway API. In fact, Ana is likely to
+  view the Gateway API and Kubernetes as pure friction getting in her way to
+  get things done.
+
+Depending on the environment, multiple roles can map to the same user:
+
+- Giving a single user all the above roles replicates the self-service model,
+  and may actually happen in a small startup running Kubernetes on bare metal.
+
+- A more typical small startup would use clusters from a cloud provider. In
+  this situation, Ana and Charlie may be embodied in the same person, with Ian
+  being an employee (or automated process!) within the cloud provider.
+
+- In a much larger organization, we would expect each persona above to be
+  embodied by a distinct person (most likely working in different groups,
+  perhaps with little direct contact).
+
+## RBAC
+
+RBAC (role-based access control) is the standard used for Kubernetes
+authorization. This allows users to configure who can perform actions on
+resources in specific scopes. We anticipate that each persona will map
+approximately to a `Role` in the Kubernetes Role-Based Authentication (RBAC)
+system and will define resource model responsibility and separation.
+
+RBAC is discussed further in the [Security Model] description.
+
+[Security Model]: /concepts/security-model#rbac

site-src/concepts/security-model.md

@@ -15,40 +15,16 @@ Gateway API has 3 primary API resources:
 
 ## Roles and personas
 
-In the original design of Kubernetes, 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.
-
-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. Gateway
-API is designed to target the following personas:
-
-* **Infrastructure provider**: The infrastructure provider (infra) is
-  responsible for the overall environment that the cluster(s) are operating in.
-  Examples include: the cloud provider (AWS, Azure, GCP, ...) or the PaaS
-  provider in a company.
-* **Cluster operator**: The cluster operator (ops) is responsible for
-  administration of entire clusters. They manage policies, network access,
-  application permissions.
-* **Application developer**: The application developer (dev) is responsible for
-  defining their application configuration (e.g. timeouts, request
-  matching/filter) and Service composition (e.g. path routing to backends).
-
-Although these roles can cover a wide variety of use cases, some organizations
-may be structured slightly differently. Many organizations may also have a
-fourth role that sits between "cluster operator" and "application developer":
-
-* **Application admin**: The application admin has administrative access to some
-  namespaces within a cluster, but not the cluster as a whole.
-
-We expect that each persona will map approximately to a `Role` in the Kubernetes
-Role-Based Authentication (RBAC) system and will define resource model
-responsibility and separation.
-
-Depending on the environment, multiple roles can map to the same user. For
-example, giving the user all the above roles replicates the self-service model.
+There are 3 primary roles in Gateway API, as described in [roles and personas]:
+
+- **Ian** (he/him): Infrastructure Provider
+- **Charlie** (they/them): Cluster Operator
+- **Ana** (she/her): Application Developer
+
+[roles and personas]:/concepts/roles-and-personas
 
 ### RBAC
+
 RBAC (role-based access control) is the standard used for Kubernetes
 authorization. This allows users to configure who can perform actions on
 resources in specific scopes. RBAC can be used to enable each of the roles