diff --git a/mkdocs.yml b/mkdocs.yml index dcdf5c91dd..5c024c8ca3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,7 @@ plugins: redirect_maps: 'guides/getting-started.md': 'guides/index.md' 'contributing/community.md': 'contributing/index.md' + 'contributing/gamma.md': 'concepts/gamma.md#contributing' - mermaid2 markdown_extensions: - admonition @@ -52,12 +53,17 @@ nav: - Introduction: index.md - Concepts: API Overview: concepts/api-overview.md + GAMMA: concepts/gamma.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 + - Glossary: concepts/glossary.md - Guides: - Getting started: guides/index.md - Simple Gateway: guides/simple-gateway.md @@ -112,6 +118,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 diff --git a/site-src/blog/2022/graduating-to-beta.md b/site-src/blog/2022/graduating-to-beta.md index 428fdf9de8..84c37a0deb 100644 --- a/site-src/blog/2022/graduating-to-beta.md +++ b/site-src/blog/2022/graduating-to-beta.md @@ -146,7 +146,7 @@ possible integration. We are pleased to announce that the service mesh community, including representatives from Cilium Service Mesh, Consul, Istio, Kuma, Linkerd, NGINX Service Mesh and Open Service Mesh, is coming together to form the [GAMMA -Initiative](https://gateway-api.sigs.k8s.io/contributing/gamma/), a dedicated +Initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/), a dedicated workstream within the Gateway API subproject focused on Gateway API for Mesh Management and Administration. @@ -169,7 +169,7 @@ As we continue to mature the API for production use cases, here are some of the - [Route delegation][pr1085] - Layer 4 API maturity: Graduating [TCPRoute][tcpr], [UDPRoute][udpr] and [TLSRoute][tlsr] to beta -- [GAMMA Initiative](https://gateway-api.sigs.k8s.io/contributing/gamma/) - Gateway API for Service Mesh +- [GAMMA Initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) - Gateway API for Service Mesh If there's something on this list you want to get involved in, or there's something not on this list that you want to advocate for to get on the roadmap diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index 3ab9b19d55..747f6430f3 100644 --- a/site-src/concepts/api-overview.md +++ b/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 +- **Chihiro** (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. +[Chihiro] 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. ![route binding](/images/gateway-route-binding.png) +[Chihiro]:/concepts/roles-and-personas#Chihiro + ### How it Works The following is required for a Route to be attached to a Gateway: @@ -279,29 +278,53 @@ relationships between the different resources: ![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 . - 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 . +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#northsouth-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 + +!!! danger "Experimental in v0.8.0" + + The [GAMMA initiative][gamma] work for supporting service mesh use cases + is _experimental_ in `v0.8.0`. It is possible that it will change; we do + not recommend it in production at this point. + + In particular, binding Routes directly to Services seems to be the current + best choice for configuring mesh routing, but it is still **experimental** + and thus **subject to change**. + +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), +as covered in the [GAMMA routing documentation]. + +[GAMMA]:/concepts/gamma +[GAMMA routing documentation]:/concepts/gamma#gateway-api-for-mesh +[service mesh]:/concepts/glossary#service-mesh + ## Extension points A number of extension points are provided in the API to provide flexibility in diff --git a/site-src/concepts/gamma.md b/site-src/concepts/gamma.md new file mode 100644 index 0000000000..21ce8562d8 --- /dev/null +++ b/site-src/concepts/gamma.md @@ -0,0 +1,233 @@ +# The GAMMA initiative (Gateway API for Service Mesh) + +!!! danger "Experimental in v0.8.0" + + GAMMA support for service mesh use cases is _experimental_ in `v0.8.0`. + It is possible that it will change; we do not recommend it in production + at this point. + +The Gateway API was originally designed to manage traffic from clients outside +the cluster to services inside the cluster -- the _ingress_ or +[_north/south_][north/south traffic] case. Over time, though, interest from +[service mesh] users prompted the creation of the GAMMA (**G**ateway **A**PI +for **M**esh **M**anagement and **A**dministration) initiative in 2022 to +define how the Gateway API could also be used for inter-service or +[_east/west_ traffic][east/west traffic] within the same cluster. + +The GAMMA initiative is a dedicated workstream within the Gateway API +subproject, rather than being a separate subproject. GAMMA’s goal is to define +how the Gateway API can be used to configure a service mesh, with the +intention of making minimal changes to the Gateway API and always preserving +the [role-oriented] nature of the Gateway API. Additionally, we strive to +advocate for consistency between implementations of the Gateway API by service +mesh projects, regardless of their technology stack or proxy. + +## Deliverables + +The work of the GAMMA intiative will be captured in [Gateway Enhancement +Proposals][geps] that extend or refine the Gateway API specification to cover +mesh and mesh-adjacent use cases. To date, these have been relatively small +changes (albeit sometimes with relatively large impacts!) and we expect that +to continue. Governance of the Gateway API specification remains solely with +the maintainers of the Gateway API subproject. + +The ideal final outcome of the GAMMA initiative is that service mesh use cases +become a first-party concern of the Gateway API, at which point there will be +no further need for a separate initiative. + +## Contributing + +We welcome contributors of all levels! There are [many ways to +contribute][contributor-ladder] to the Gateway API and GAMMA, both technical +and non-technical. + +The simplest way to get started is to attend one of GAMMA's regular meetings, +which happen every two weeks on Tuesdays for 1 hour (as found on the +[sig-network calendar]), alternating between 3pm PT and 8am PT slots to try to +be as time-zone inclusive as possible. GAMMA meetings will be moderated by the +[GAMMA leads] with notes taken by a volunteer. Community members should feel +free to attend both GAMMA and Gateway API meetings, but are by no means +obligated to do so. + +[contributor-ladder]:/contributing/contributor-ladder +[east/west traffic]:/concepts/glossary#eastwest-traffic +[GAMMA leads]:https://github.com/kubernetes-sigs/gateway-api/blob/main/OWNERS_ALIASES#L23 +[geps]:/geps/overview +[north/south traffic]:/concepts/glossary#northsouth-traffic +[service mesh]:/concepts/glossary#service-mesh +[sig-network calendar]:/contributing/community/#meetings +[role-oriented]:/concepts/roles-and-personas + +## An Overview of the Gateway API for Service Mesh + +!!! danger "Experimental in v0.8.0" + + GAMMA support for service mesh use cases is _experimental_ in `v0.8.0`. + It is possible that it will change; we do not recommend it in production + at this point. + +GAMMA has, to date, been able to define service mesh support in the Gateway +API with relatively small changes. The most significant change that GAMMA has +introduced to date is that, when configuring a service mesh, individual route +resources (such as [HTTPRoute]) are [associated directly with Service +resources](#gateway-api-for-mesh). + +This is primarily because there will typically only be one mesh active in the +cluster, so the [Gateway] and [GatewayClass] resources are not used when +working with a mesh. In turn, this leaves the Service resource as the most +universal binding point for routing information. + +Since the Service resource is unfortunately complex, with several overloaded +or underspecified aspects, GAMMA has also found it critical to formally define +the [Service _frontend_ and _backend_ facets][service-facets]. In brief: + +- The Service frontend is its name and cluster IP, and +- The Service backend is its collection of endpoint IPs. + +This distinction helps the Gateway API to be exact about how routing within a +mesh functions, without requiring new resources that largely duplicate the +Service. + +[GatewayClass]: /api-types/gatewayclass +[Gateway]: /api-types/gateway +[HTTPRoute]: /api-types/httproute +[TCPRoute]: /api-types/tcproute +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[service-mesh]:/concepts/glossary#service-mesh +[service-facets]:/concepts/service-facets + +## How the Gateway API works for Service Mesh + +GAMMA specifies that individual Route resources attach directly to a Service, +representing configuration meant to be applied to _any traffic directed to the +Service_. + +!!! danger "Experimental in v0.8.0" + + Binding Routes directly to Services seems to be the current best choice + for configuring mesh routing, but it is still **experimental** and thus + **subject to change**. + +When one or more Routes are attached to a Service, **requests that do not +match at least one of the Routes will be rejected**. If no Routes are attached +to a Service, requests to the Service simply proceed per the mesh's default +behavior (usually resulting in the request being forwarded as if the mesh were +not present). + +Which Routes attach to a given Service is controlled by the Routes themselves +(working with Kubernetes RBAC): the Route simply specifies a `parentRef` that +is a Service, rather than a Gateway. + +```yaml +kind: HTTPRoute +metadata: + name: smiley-route + namespace: faces +spec: + parentRefs: + - name: smiley + kind: Service + group: core + port: 80 + rules: + ... +``` + +The relationship between the Route's Namespace and the Service's Namespace is +important: + +- Same Namespace + + !!! note "Work in Progress" + + There is ongoing work around the relationship between producer + routes and consumer routes. + + 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. + + The Route shown above is a producer route. + +- Different Namespaces + + !!! note "Work in Progress" + + There is ongoing work around the relationship between producer + routes and consumer routes. + + 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. + + For example, this HTTPRoute would cause all clients of the `smiley` + workload in the `fast-clients` Namespace to have a 100ms timeout: + + ```yaml + kind: HTTPRoute + metadata: + name: smiley-route + namespace: fast-clients + spec: + parentRefs: + - name: smiley + namespace: faces + kind: Service + group: core + port: 80 + rules: + ... + timeouts: + request: 100ms + ``` + +One important note about Routes bound to Services is that multiple Routes for +the same Service in a single Namespace - whether producer routes or consumer +routes - will be combined according to the Gateway API [Route merging rules]. +As such, it is not currently possible to define distinct consumer routes for +multiple consumers in the same Namespace. + +For example, if the `blender` workload and the `mixer` workload both live in +the `foodprep` Namespace, and both call the `oven` workload using the same +Service, it is not currently possible for `blender` and `mixer` to use +HTTPRoutes to set different timeouts for their calls to the `oven` workload. +`blender` and `mixer` would need to be moved into separate Namespaces to allow +this. + +[Ana]:/concepts/roles-and-personas#ana +[producer route]:/concepts/glossary#producer-route +[consumer route]:/concepts/glossary#consumer-route +[service mesh]:/concepts/glossary#service-mesh +[Route merging rules]:/api-types/httproute#merging + +## Request Flow + +A typical [east/west] API request flow when a GAMMA-compliant mesh is in use +looks like: + +1. A client workload makes a request to . +2. The mesh data plane intercepts the request and identifies it as traffic for + the Service `foo` in Namespace `ns`. +3. The data plane locates Routes associated with the `foo` Service, then: + + a. If there are no associated Routes, the request is always allowed, and + the `foo` workload itself is considered the destination workload. + + b. If there are associated Routes and the request matches at least one of + them, the `backendRefs` of the highest-priority matching Route are used + to select the destination workload. + + c. If there are associated Routes, but the request matches none of them, + the request is rejected. + +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#eastwest-traffic +[endpoint routing]:/concepts/glossary#endpoint-routing +[Service routing]:/concepts/glossary#service-routing diff --git a/site-src/concepts/glossary.md b/site-src/concepts/glossary.md new file mode 100644 index 0000000000..ba9d211c57 --- /dev/null +++ b/site-src/concepts/glossary.md @@ -0,0 +1,69 @@ +# 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 manages the infrastructure associated +with routing traffic across contexts using the Gateway API, analogous to the +earlier _ingress controller_ concept. Gateway controllers often, but not +always, run in the cluster where they're managing infrastructure. + +### East/West traffic + +Traffic from workload to workload within a cluster. + +### 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. + +### 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 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 mesh + +A _service mesh_ is software that manages infrastructure providing security, +reliability, and observability for communications between workloads (east/west +traffic). Service meshes generally work by intercepting communications between +workloads at a very low level, often (though not always) by inserting proxies +next to the workload's Pods. + +### 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. + +### Workload + +An instance of computation that provides a function within a cluster, +comprising the Pods providing the compute, and the +Deployment/Job/ReplicaSet/etc which owns those Pods. diff --git a/site-src/concepts/roles-and-personas.md b/site-src/concepts/roles-and-personas.md new file mode 100644 index 0000000000..73da3744a9 --- /dev/null +++ b/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: + +* **Ian** (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. + +* **Chihiro** (they/them) is a _cluster operator_, + responsible for managing clusters to ensure that they meet the needs of + their several users. Chihiro 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. + +* **Ana** (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 Chihiro 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 diff --git a/site-src/concepts/security-model.md b/site-src/concepts/security-model.md index 9cda29b917..3774fc9867 100644 --- a/site-src/concepts/security-model.md +++ b/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 +- **Chihiro** (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 diff --git a/site-src/concepts/service-facets.md b/site-src/concepts/service-facets.md new file mode 100644 index 0000000000..5e2d39a488 --- /dev/null +++ b/site-src/concepts/service-facets.md @@ -0,0 +1,49 @@ +# The Different Facets of a Service + +The Kubernetes [Service] resource is considerably more complex than people +often realize. When you create a Service, typically the cluster machinery will: + +- Allocate a cluster-wide IP address for the Service itself (its _cluster IP_); +- Allocate a DNS name for the Service, resolving to the cluster IP (its _DNS name_); +- Collect the separate cluster-wide IP addresses assigned to each Pod matched + by the Service's selector (the _endpoint IPs_) into the Service's Endpoints + or EndpointSlices. +- Configure the network such that traffic to the cluster IP will be + load-balanced across all the endpoint IPs. + +Unfortunately, these implementation details become very important when +considering how the Gateway API can work for service meshes! + +In [GAMMA initiative][gamma] work, it has become useful to consider Services +as comprising two separate _facets_: + +- The **frontend** of the Service is the combination of the cluster IP and + its DNS name. + +- The **backend** of the Service is the collection of endpoint IPs. (The Pods + are not part of the Service backend, but they are of course strongly + associated with the endpoint IPs.) + +The distinction between the facets is critical because the [gateway] and the +[mesh] each need to decide whether a request that mentions a given Service +should be directed to the Service's frontend or its backend: + +- Directing the request to the Service's frontend (_Service routing_) leaves + the decision of which endpoint IP to use to the underlying network + infrastructure (which might be `kube-proxy`, a service mesh, or something + else). + +- Directing the request to the Service's backend (_endpoint routing_) is + often necessary to enable more advanced load balancing decisions (for + example, a gateway implementing sticky sessions). + +While Service routing may be the most direct fit for [Ana]'s sense of routing, +endpoint routing can be more predictable when using the Gateway API for both +[north/south] and [east/west traffic]. The [GAMMA initiative][gamma] is working to +formalize guidance for this use case. + +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[north/south]:/concepts/glossary#northsouth-traffic +[east/west traffic]:/concepts/glossary#eastwest-traffic +[gamma]:/concepts/gamma/ +[Ana]:/concepts/roles-and-personas#ana diff --git a/site-src/concepts/use-cases.md b/site-src/concepts/use-cases.md new file mode 100644 index 0000000000..7b5edae7e4 --- /dev/null +++ b/site-src/concepts/use-cases.md @@ -0,0 +1,202 @@ +# Gateway API Use Cases + +The Gateway API covers a _very_ wide range of use cases (which is both a +strength and a weakness!). This page is emphatically _not_ meant to be an +exhaustive list of these use cases: rather, it is meant to provide some +examples that can be helpful to demonstrate how the API can be used. + +In all cases, it's very important to bear in mind the [roles and personas] +used in the Gateway API. The use cases presented here are deliberately +described in terms of [Ana], [Chihiro], and [Ian]: they are the ones for whom +the API must be usable. (It's also important to remember that even though +these roles might be filled by the same person, especially in smaller +organizations, they all have distinct concerns that we need to consider +separately.) + +[roles and personas]:/concepts/roles-and-personas +[Ana]:/concepts/roles-and-personas#ana +[Chihiro]:/concepts/roles-and-personas#chihiro +[Ian]:/concepts/roles-and-personas#ian + +## The Use Cases + +- [Basic north/south use case](#basic-northsouth-use-case) +- [Multiple applications behind a single + Gateway](#multiple-applications-behind-a-single-gateway) +- [Basic east/west use case](#basic-eastwest-use-case) -- **experimental** +- [Gateway and mesh use case](#gateway-and-mesh-use-case) -- **experimental** + +[role and personas]:/concepts/roles-and-personas + +## Basic [north/south] use case + +??? success "Standard Channel in v0.8.0+" + + The [north/south] use case is fully supported by the Standard Channel + in `v0.8.0+`. + +Ana has created a microservice application which she wants to run in +Kubernetes. Her application will be used by clients outside the cluster, and +while Ana has created the application, setting up the cluster is not in her +wheelhouse. + +1. Ana goes to Chihiro to ask them to set up a cluster. Ana tells Chihiro that + her clients will expect her APIs to be available using URLs rooted at + `https://ana.application.com/`. + +2. Chihiro goes to Ian and requests a cluster. + +3. Ian provisions a cluster running a gateway controller with a [GatewayClass] + resource named `basic-gateway-class`. The gateway controller manages the + infrastructure associated with routing traffic from outside the cluster to + inside the cluster. + +4. Ian gives Chihiro credentials to the new cluster, and tells Chihiro that + they can use GatewayClass `basic-gateway-class` to set things up. + +5. Chihiro applies a [Gateway] named `ana-gateway` to the cluster, telling it + to listen on port 443 for TLS traffic, and providing it a TLS certificate + with a Subject CN of `ana.application.com`. They associate this Gateway with the `basic-gateway-class` GatewayClass. + +6. The gateway controller that Ian provisioned in step 3 allocates a load + balancer and an IP address for `ana-gateway`, provisions data-plane + components that can route requests arriving at the load balancer on port + 443, and starts watching for routing resources associated with + `ana-gateway`. + +7. Chihiro gets the IP address of `ana-gateway` and creates a DNS record + outside the cluster for `ana.application.com` to match. + +8. Chihiro tells Ana that she's good to go, using the Gateway named + `ana-gateway`. + +9. Ana writes and applies [HTTPRoute] resources to configure which URL paths + are allowed and which microservices should handle them. She associates + these HTTPRoutes with Gateway `ana-gateway` using the Gateway API [Route + Attachment Process]. + +10. At this point, when requests arrive at the load balancer, they are routed + to Ana's application according to her routing specification. + +This allows Chihiro to enforce centralized policies [such as +TLS](/guides/tls#downstream-tls) at the Gateway, while simultaneously allowing +Ana and her colleagues control over the application's [routing +logic](/guides/http-routing) and rollout plans (e.g. [traffic splitting +rollouts](/guides/traffic-splitting)). + +[north/south]:/concepts/glossary#northsouth-traffic + +## Multiple applications behind a single Gateway + +??? success "Standard Channel in v0.8.0+" + + The [north/south] use case is fully supported by the Standard Channel + in `v0.8.0+`. + +This is remarkably similar to the [basic north/south use +case](#basic-northsouth-use-case), but there are multiple application teams: +Ana and her team are managing a storefront application in the `store` +Namespace, while Allison and her team are managing a website in the `site` +Namespace. + +- Ian and Chihiro work together to provide a cluster, `GatewayClass`, and + `Gateway`, as above. + +- Ana and Allison independently deploy workloads and HTTPRoutes bound to the + same `Gateway` resource. + +Again, this separation of concerns allows Chihiro to enforce centralized +policies [such as TLS](/guides/tls#downstream-tls) can be enforced at the +Gateway. Meanwhile, Ana and Allison run their applications [in their own +Namespaces](/guides/multiple-ns), but attach their Routes to the same shared +Gateway, allowing them to independently control their [routing +logic](/guides/http-routing), [traffic splitting +rollout](/guides/traffic-splitting), etc., while not worrying about the things +that Chihiro and Ian are handling. + +[HTTPRoute]:/api-types/httproute +[GatewayClass]:/api-types/gatewayclass +[Gateway]:/api-types/gateway +[Route Attachment Process]:/concepts/api-overview#attaching-routes-to-gateways + +![Gateway API Roles](/images/gateway-roles.png) + +## Basic [east/west] use case + +!!! danger "Experimental in v0.8.0" + + The [GAMMA initiative][gamma] work for supporting service mesh use cases + is _experimental_ in `v0.8.0`. It is possible that it will change; we do + not recommend it in production at this point. + +In this scenario, Ana has built a workload which is already running in a +cluster with a [GAMMA]-compliant [service mesh]. She wants to use the mesh to +protect her workload by rejecting calls to her workload with incorrect +URL paths, and by enforcing timeouts whenever anyone makes a request of her +workload. + +- Chihiro and Ian have already provided a cluster with a running service mesh. + Ana doesn't need to make any requests of them. + +- Ana writes an HTTPRoute that defines acceptable routes and timeouts and has + a `parentRef` of her workload's Service. + +- Ana applies her HTTPRoute in the same Namespace as her workload. + +- The mesh automatically starts enforcing the routing policy described by + Ana's HTTPRoute. + +In this case, the separation of concerns across roles allows Ana to take +advantage of the service mesh, with custom routing logic, without any +bottlenecks in requests to Chihiro or Ian. + +[east/west]:/concepts/glossary#eastwest-traffic +[GAMMA]:/concepts/gamma/ +[service mesh]:/concepts/glossary#service-mesh + +## Gateway and mesh use case + +!!! danger "Experimental in v0.8.0" + + The [GAMMA initiative][gamma] work for supporting service mesh use cases + is _experimental_ in `v0.8.0`. It is possible that it will change; we do + not recommend it in production at this point. + +This is effectively a combination of the [multiple applications behind a +single Gateway](#multiple-applications-behind-a-single-gateway) and [basic +east/west](#basic-eastwest-use-case) use cases: + +- Chihiro and Ian will provision a cluster, a [GatewayClass], and a [Gateway]. + +- Ana and Allison will deploy their applications in the appropriate + Namespaces. + +- Ana and Allison will then apply HTTPRoute resources as appropriate. + +There are two very important changes in this scenario, though, since a mesh is +involved: + +1. If Chihiro has deployed a [gateway controller] that defaults to [Service + routing], they will probably need to reconfigure it for [endpoint routing]. + (This is an ongoing area of work for [GAMMA], but the expectation is that + endpoint routing will be recommended.) + +2. Ana and/or Allison will need to bind HTTPRoutes to their respective + workloads' Services to configure mesh routing logic. These could be + distinct HTTPRoutes solely for the mesh, or they could apply single + HTTPRoutes that bind to both the Gateway and a Service. + +As always, the ultimate point of separating concerns in this way is that it +permits Chihiro to enforce centralized policies [such as +TLS](/guides/tls#downstream-tls) at the Gateway, while allowing Ana and +Allison to retain independent control of [routing +logic](/guides/http-routing), [traffic splitting +rollout](/guides/traffic-splitting), etc., both for [north/south] and for +[east/west] routing. + + + + +[gateway controller]:/concepts/glossary#gateway-controller +[Service routing]:/concepts/glossary#service-routing +[endpoint routing]:/concepts/glossary#endpoint-routing diff --git a/site-src/contributing/gamma.md b/site-src/contributing/gamma.md deleted file mode 100644 index fb7f94e1dc..0000000000 --- a/site-src/contributing/gamma.md +++ /dev/null @@ -1,28 +0,0 @@ -# The GAMMA Initiative - -The GAMMA (Gateway API for Mesh Management and Administration) initiative is a -dedicated workstream within the Gateway API subproject. This group’s goal is to -investigate, design, and track Gateway API resources, semantics, and other -artifacts related to service mesh technology and use-cases. Additionally, we -strive to advocate for consistency between implementations of the Gateway API by -service mesh projects, regardless of their technology stack or proxy. - -## Deliverables - -This group will deliver [Gateway Enhancement Proposals](/geps/overview) -consisting of resources, additions, and modifications to the Gateway API -specification for mesh and mesh-adjacent use-cases. Governance of the Gateway -API specification remains solely with the maintainers of the Gateway API -subproject. Ideally, once service mesh use-cases become a first-party concern of -the spec, there will be no further need for a separate initiative. - -## Meeting mechanics - -GAMMA meetings will occur weekly on Tuesdays for 1 hour, alternating between 3pm -PT and 8am PT slots to try to be as time-zone inclusive as possible. Meetings -will be moderated by the [GAMMA -leads](https://github.com/kubernetes-sigs/gateway-api/blob/main/OWNERS_ALIASES#L23) -with notes taken by a volunteer. Meeting occurrences can be found on the -[sig-network calendar](/contributing/community/#meetings). Community members -should feel free to attend both GAMMA and Gateway API meetings, but are by no -means obligated to do so. diff --git a/site-src/contributing/index.md b/site-src/contributing/index.md index a2f17263a0..eb79977e5c 100644 --- a/site-src/contributing/index.md +++ b/site-src/contributing/index.md @@ -63,7 +63,7 @@ interested in the ingress use case, this is the common forum for that. ### Mesh Meeting (GAMMA) -[GAMMA](/contributing/gamma/) is the initative within Gateway API to use the +[GAMMA](/concepts/gamma/) is the initative within Gateway API to use the resources provided by Gateway API for service mesh use cases. Meetings happen every other week on Tuesdays, alternating between 3pm Pacific Time (23:00 UTC) and 8AM Pacific Time (16:00 UTC): diff --git a/site-src/implementations.md b/site-src/implementations.md index 8c1bee1d94..de246b3937 100644 --- a/site-src/implementations.md +++ b/site-src/implementations.md @@ -4,7 +4,7 @@ This document tracks downstream implementations and integrations of Gateway API Implementors and integrators of Gateway API are encouraged to update this document with status information about their implementations, the versions they cover, and documentation to help users get started. -## Implementation Status +## Gateway Controller Implementation Status - [Acnodal EPIC][1] (public preview) - [Amazon Elastic Kubernetes Service][23] (alpha) @@ -29,7 +29,13 @@ Implementors and integrators of Gateway API are encouraged to update this docume - [Traefik][13] (alpha) - [WSO2 APK][25] (pre-alpha) -## Integration Status +## Service Mesh Implementation Status + +- [Istio][9] (experimental) +- [Kuma][11] (experimental) +- [Linkerd][28] (experimental) + +## Integrations - [Flagger][14] (public preview) - [cert-manager][15] (alpha) @@ -64,6 +70,9 @@ Implementors and integrators of Gateway API are encouraged to update this docume [25]:#wso2-apk [26]:#kuadrant [27]:#azure-application-gateway-for-containers +[28]:#linkerd + +[gamma]:/concepts/gamma/ ## Implementations @@ -126,7 +135,7 @@ performance, and avoid the operational complexity of sidecars. Cilium also supports the sidecar proxy model, offering choice to users. As of [Cilium 1.13][cilium113blog], Cilium supports Gateway API, passing conformance for v0.5.1. -Cilium is open source and is a CNCF incubation project. +Cilium is open source and is a CNCF incubation project. If you have questions about Cilium Service Mesh the #service-mesh channel on [Cilium Slack][cilium-slack] is a good place to start. For contributing to the development @@ -174,7 +183,7 @@ See [here][emissary-gateway-api] for more details on using the Gateway API with ### Envoy Gateway [Envoy Gateway][eg-home] is an [Envoy][envoy-org] subproject for managing Envoy-based application gateways. The supported -APIs and fields of the Gateway API are outlined [here][eg-supported]. +APIs and fields of the Gateway API are outlined [here][eg-supported]. Use the [quickstart][eg-quickstart] to get Envoy Gateway running with Gateway API in a few simple steps. @@ -227,7 +236,7 @@ HAProxy Ingress v0.13 partially supports the Gateway API's v1alpha1 specificatio ### HashiCorp Consul -[Consul][consul], by [HashiCorp][hashicorp], is an open source control plane for multi-cloud networking. A single Consul deployment can span bare metal, VM and container environments. +[Consul][consul], by [HashiCorp][hashicorp], is an open source control plane for multi-cloud networking. A single Consul deployment can span bare metal, VM and container environments. Consul service mesh works on any Kubernetes distribution, connects multiple clusters, and Consul CRDs provide a Kubernetes native workflow to manage traffic patterns and permissions in the mesh. [Consul API Gateway][consul-api-gw-doocs] supports Gatewway API for managing North-South traffic. @@ -239,18 +248,20 @@ Please see the [Consul API Gateway documentation][consul-api-gw-doocs] for curre ### Istio -[Istio][istio] is an open source [service mesh][mesh] and gateway implementation. +[Istio][istio] is an open source [service mesh][istio-mesh] and gateway implementation. -A light-weight minimal install of Istio can be used to provide a Beta-quality implementation of the Kubernetes Gateway API for cluster ingress traffic control. For service mesh users, -the Istio implementation also lets you start trying out the experimental Gateway API [support for east-west traffic management][gamma] within the mesh. +A light-weight minimal install of Istio can be used to provide a Beta-quality +implementation of the Kubernetes Gateway API for cluster ingress traffic +control. For service mesh users, Istio 1.16 and later support the [GAMMA +initiative's][gamma] experimental Gateway API [support for east-west traffic +management][gamma] within the mesh. Much of Istio's documentation, including all of the [ingress tasks][istio-1] and several mesh-internal traffic management tasks, already includes parallel instructions for configuring traffic using either the Gateway API or the Istio configuration API. Check out the [Gateway API task][istio-2] for more information about the Gateway API implementation in Istio. [istio]:https://istio.io -[mesh]:https://istio.io/latest/docs/concepts/what-is-istio/#what-is-a-service-mesh -[gamma]:https://gateway-api.sigs.k8s.io/contributing/gamma/ +[istio-mesh]:https://istio.io/latest/docs/concepts/what-is-istio/#what-is-a-service-mesh [istio-1]:https://istio.io/latest/docs/tasks/traffic-management/ingress/ [istio-2]:https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/ @@ -278,9 +289,25 @@ For help and support with Kong's implementations please feel free to [create an Kuma is actively working on an implementation of Gateway API specification for the Kuma builtin Gateway. Check the [Gateway API Documentation][kuma-1] for information on how to setup a Kuma builtin gateway using the Gateway API. +Kuma 2.3 and later support the [GAMMA initiative's][gamma] experimental +Gateway API [support for east-west traffic management][gamma] within the mesh. + [kuma]:https://kuma.io [kuma-1]:https://kuma.io/docs/latest/explore/gateway-api/ +### Linkerd + +[Linkerd][linkerd] is the first CNCF graduated [service mesh][linkerd-mesh]. +It is the only major mesh not based on Envoy, instead relying on a +purpose-built Rust micro-proxy to bring security, observability, and +reliability to Kubernetes, without the complexity. + +Linkerd 2.14 and later support the [GAMMA initiative's][gamma] experimental +Gateway API [support for east-west traffic management][gamma] within the mesh. + +[linkerd]:https://linkerd.io/ +[linkerd-mesh]:https://buoyant.io/service-mesh-manifesto + ### LiteSpeed Ingress Controller The [LiteSpeed Ingress Controller](https://litespeedtech.com/products/litespeed-web-adc/features/litespeed-ingress-controller) uses the LiteSpeed WebADC controller to operate as an Ingress Controller and Load Balancer to manage your traffic on your Kubernetes cluster. It implements the full core Gateway API including Gateway, GatewayClass, HTTPRoute and ReferenceGrant and the Gateway functions of cert-manager. Gateway is fully integrated into the LiteSpeed Ingress Controller. diff --git a/site-src/index.md b/site-src/index.md index 5b78f0a0f3..d763face69 100644 --- a/site-src/index.md +++ b/site-src/index.md @@ -1,98 +1,186 @@ ## What is the Gateway API? -Gateway API is an open source project managed by the [SIG-NETWORK][sig-network] -community. It is an API (collection of resources) that model service networking -in Kubernetes. These resources - `GatewayClass`, `Gateway`, `HTTPRoute`, -`TCPRoute`, `Service`, etc - aim to evolve Kubernetes service networking through -expressive, extensible, and role-oriented interfaces that are implemented by -many vendors and have broad industry support. +Gateway API is an open source project managed by the +[SIG-NETWORK][sig-network] community. It is an API (collection of resources) +that model service networking in Kubernetes. These resources - +[`GatewayClass`][GatewayClass], [`Gateway`][Gateway], +[`HTTPRoute`][HTTPRoute], [`TCPRoute`][TCPRoute], etc., as well as the +Kubernetes [`Service`][Service] resource - aim to evolve Kubernetes service +networking through expressive, extensible, and role-oriented interfaces that +are implemented by many vendors and have broad industry support. + +[GatewayClass]: /api-types/gatewayclass +[Gateway]: /api-types/gateway +[HTTPRoute]: /api-types/httproute +[TCPRoute]: /api-types/tcproute +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ ![Gateway API Model](./images/api-model.png) +The Gateway API was originally designed to manage traffic from clients outside +the cluster to services inside the cluster -- the _ingress_ or +[_north/south_][north/south traffic] case. Over time, interest from service +mesh users prompted the creation of the [GAMMA initiative][gamma] to define +how the Gateway API could also be used for inter-service or [_east/west_ +traffic][east/west traffic] within the same cluster. + +If you're familiar with the older [Ingress API], you can think of the Gateway +API as analogous to a more-expressive next-generation version of that API. + +## Gateway API for Ingress + +When using the Gateway API to manage ingress traffic, the [Gateway] resource +defines a point of access at which traffic can be routed across multiple +contexts -- for example, from outside the cluster to inside the cluster +([north/south traffic]). + +Each Gateway is associated with a [GatewayClass], which describes the actual +kind of [gateway controller] that will handle traffic for the Gateway; +individual routing resources (such as [HTTPRoute]) are then [associated with +the Gateway resources][gateway-attachment]. Separating these different +concerns into distinct resources is a critical part of the role-oriented +nature of the Gateway API, as well as allowing for multiple kinds of gateway +controllers (represented by GatewayClass resources), each with multiple +instances (represented by Gateway resources), in the same cluster. + +[Ingress API]:https://kubernetes.io/docs/concepts/services-networking/ingress/ +[north/south traffic]:/concepts/glossary#northsouth-traffic +[east/west traffic]:/concepts/glossary#eastwest-traffic +[gateway controller]:/concepts/glossary#gateway-controller +[gateway-attachment]:/concepts/api-overview#attaching-routes-to-gateways + +## Gateway API for Service Mesh (the [GAMMA initiative][gamma]) + +!!! danger "Experimental in v0.8.0" + + The [GAMMA initiative][gamma] work for supporting service mesh use cases + is _experimental_ in `v0.8.0`. It is possible that it will change; we do + not recommend it in production at this point. + +Things are a bit different when using the Gateway API to manage a [service +mesh][service-mesh]. Since there will usually only be one mesh active in the +cluster, the [Gateway] and [GatewayClass] resources are not used; instead, +individual route resources (such as [HTTPRoute]) are [associated directly with +Service resources][mesh-attachment], permitting the mesh to manage traffic +from any traffic directed to that Service while preserving the role-oriented +nature of the Gateway API. + +To date, [GAMMA][gamma] has been able to support mesh functionality with +fairly minimal changes to the Gateway API. One particular area that has +rapidly become critical for GAMMA, though, is the definition of the different +[facets of the Service resource][service-facets]. + +In Gateway API v0.8.0, GAMMA support for service mesh is **experimental**. We +encourage working with it and providing feedback, but you **must** be prepared +for change in the GAMMA APIs. + +[gamma]:/concepts/gamma/ +[service-mesh]:/concepts/glossary#service-mesh +[service-facets]:/concepts/service-facets +[mesh-attachment]:/concepts/gamma#gateway-api-for-mesh + ## Getting started -Whether you are a user interested in using the Gateway API or an implementer -interested in conforming to the API, the following resources will help give +Whether you are a user interested in using the Gateway API or an implementer +interested in conforming to the API, the following resources will help give you the necessary background: - [API overview](/concepts/api-overview) - [User guides](/guides) -- [Gateway controller implementations](/implementations) +- [Gateway controller implementations](/implementations#gateways) +- [Service Mesh implementations](/implementations#meshes) - [API reference spec](/references/spec) - [Community links](/contributing/community) and [developer guide](/contributing/devguide) - ## Gateway API concepts -The following design goals drive the concepts of the Gateway API. These +The following design goals drive the concepts of the Gateway API. These demonstrate how Gateway aims to improve upon current standards like Ingress. - -- **Role-oriented** - Gateway is composed of API resources which model -organizational roles that use and configure Kubernetes service networking. +- **Role-oriented** - Gateway is composed of API resources which model +organizational roles that use and configure Kubernetes service networking. - **Portable** - This isn't an improvement but rather something that should stay the same. Just as Ingress is a universal specification with [numerous implementations](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), Gateway API is designed to be a portable specification supported by many implementations. -- **Expressive** - Gateway API resources support core functionality for things -like header-based matching, traffic weighting, and other capabilities that +- **Expressive** - Gateway API resources support core functionality for things +like header-based matching, traffic weighting, and other capabilities that were only possible in Ingress through custom annotations. -- **Extensible** - Gateway API allows for custom resources to be linked at +- **Extensible** - Gateway API allows for custom resources to be linked at various layers of the API. This makes granular customization possible at the appropriate places within the API structure. Some other notable capabilities include: -- **GatewayClasses** - GatewayClasses formalize types of load balancing -implementations. These classes make it easy and explicit for users to -understand what kind of capabilities are available via the Kubernetes resource +- **GatewayClasses** - GatewayClasses formalize types of load balancing +implementations. These classes make it easy and explicit for users to +understand what kind of capabilities are available via the Kubernetes resource model. - **Shared Gateways and cross-Namespace support** - They allow the sharing of load balancers and VIPs by permitting independent Route resources to attach to the same Gateway. This allows teams (even across Namespaces) to share infrastructure safely without direct coordination. -- **Typed Routes and typed backends** - The Gateway API supports typed Route -resources and also different types of backends. This allows the API to be +- **Typed Routes and typed backends** - The Gateway API supports typed Route +resources and also different types of backends. This allows the API to be flexible in supporting various protocols (like HTTP and gRPC) and various backend targets (like Kubernetes Services, storage buckets, or -functions). - +functions). +- Experimental **Service mesh support** with the [GAMMA initiative][gamma] - +The Gateway API supports associating routing resources with Service resources, +to configure service meshes as well as ingress controllers. ## Why does a role-oriented API matter? Whether it’s roads, power, data centers, or Kubernetes clusters, infrastructure is built to be shared. However, shared infrastructure raises a common challenge - how to provide flexibility to users of the infrastructure -while maintaining control by owners of the infrastructure? +while maintaining control by owners of the infrastructure? The Gateway API accomplishes this through a role-oriented design for Kubernetes service networking that strikes a balance between distributed flexibility and centralized control. It allows shared network infrastructure (hardware load balancers, cloud networking, cluster-hosted proxies etc) to be used by many different and non-coordinating teams, all bound by the policies -and constraints set by cluster operators. The following example shows how this -works in practice. - -A cluster operator creates a [Gateway](/api-types/gateway) resource derived from a -[GatewayClass](/api-types/gatewayclass). This Gateway deploys or configures the -underlying network resources that it represents. Through the -[Route Attachment Process](/concepts/api-overview#attaching-routes-to-gateways) -between the Gateway and Routes, the cluster operator and specific teams must -agree on what can attach to this Gateway and expose their applications through -it. Centralized policies [such as TLS](/guides/tls#downstream-tls) can -be enforced on the Gateway by the cluster operator. Meanwhile, the store and site -teams run [in their own Namespaces](/guides/multiple-ns), but attach their -Routes to the same shared Gateway, allowing them to independently control -their [routing logic](/guides/http-routing). This separation of concerns -allows the store team to manage their own -[traffic splitting rollout](/guides/traffic-splitting) while -leaving centralized policies and control to the cluster operators. - -![Gateway API Roles](./images/gateway-roles.png) - -This flexibility allows the API to adapt to vastly different -organizational models and implementations while remaining a portable and -standard API. +and constraints set by cluster operators. + +The roles used for the Gateway API's design are defined by three personas: + +### Personas + +- **Ian** (he/him) is an _infrastructure provider_. His role is 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. + +- **Chihiro** (they/them) is a _cluster operator_. Their role is to manage a + single cluster, ensuring that it meets the needs of its several users. + Again, Chihiro is beholden to no single user of their cluster; they need to + make sure that the cluster serves all of them as needed. + +- **Ana** (she/her) is an _application developer_. Ana is in a unique position + among the Gateway API roles: 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. + +(These three are discussed in more detail in [Roles and +Personas](/concepts/roles-and-personas).) + +It should be clear that while Ana, Chihiro, and Ian do not necessarily see +eye-to-eye about everything, they need to work together to keep things running +smoothly. This is the core challenge of the Gateway API in a nutshell. + +### Use Cases + +The [example use cases][use-cases] show this role-oriented model at work. Its +flexibility allows the API to adapt to vastly different organizational models +and implementations while remaining a portable and standard API. + +The use cases presented are deliberately cast in terms of the roles presented +above. Ultimately the Gateway API is meant for use by humans, which means that +it must fit the uses to which each of Ana, Chihiro, and Ian will put it. + +[use-cases]:/concepts/use-cases ## What's the difference between Gateway API and an API Gateway? @@ -102,11 +190,11 @@ traffic routing and manipulation, such as load balancing, request and response transformation, and sometimes more advanced features like authentication and authorization, rate limiting, and circuit breaking. -Gateway API is an interface, or set of resources, that model service networking -in Kubernetes. One of the main resources is a `Gateway`, which declares the -Gateway type (or class) to instantiate and its configuration. As a Gateway -Provider, you can implement the Gateway API to model Kubernetes service -networking in an expressive, extensible, and role-oriented way. +The Gateway API is an interface, or set of resources, that model service +networking in Kubernetes. One of the main resources is a `Gateway`, which +declares the Gateway type (or class) to instantiate and its configuration. As +a Gateway Provider, you can implement the Gateway API to model Kubernetes +service networking in an expressive, extensible, and role-oriented way. Most Gateway API implementations are API Gateways to some extent, but not all API Gateways are Gateway API implementations. @@ -117,11 +205,11 @@ The Gateway API is a [SIG-Network](https://github.com/kubernetes/community/tree/master/sig-network) project being built to improve and standardize service networking in Kubernetes. Current and in-progress implementations include Contour, -Emissary-Ingress (Ambassador API Gateway), Google Kubernetes Engine (GKE), Istio, -Kong, and Traefik. Check out the [implementations -reference](implementations.md) to see the latest projects & -products that support Gateway. If you are interested in contributing to or -building an implementation using the Gateway API then don’t hesitate to [get +Emissary-ingress (Ambassador API Gateway), Google Kubernetes Engine (GKE), +Istio, Kong, Linkerd, and Traefik. Check out the [implementations +reference](implementations.md) to see the latest projects & products that +support Gateway. If you are interested in contributing to or building an +implementation using the Gateway API then don’t hesitate to [get involved!](/contributing/community) [sig-network]: https://github.com/kubernetes/community/tree/master/sig-network