|
| 1 | +# The GAMMA initiative |
| 2 | + |
| 3 | +!!! danger "Experimental in v0.8.0" |
| 4 | + |
| 5 | + GAMMA support for service mesh use cases is _experimental_ in `v0.8.0`. |
| 6 | + It is possible that it will change; we do not recommend it in production |
| 7 | + at this point. |
| 8 | + |
| 9 | +The Gateway API was originally designed to manage traffic from clients outside |
| 10 | +the cluster to services inside the cluster -- the _ingress_ or |
| 11 | +[_north/south_][north/south traffic] case. Over time, though, interest from |
| 12 | +[service mesh] users prompted the creation of the GAMMA (**G**ateway **A**PI |
| 13 | +for **M**esh **M**anagement and **A**dministration) initiative in 2022 to |
| 14 | +define how the Gateway API could also be used for inter-service or |
| 15 | +[_east/west_ traffic][east/west traffic] within the same cluster. |
| 16 | + |
| 17 | +The GAMMA initiative is a dedicated workstream within the Gateway API |
| 18 | +subproject, rather than being a separate subproject. GAMMA’s goal is to define |
| 19 | +how the Gateway API can be used to configure a service mesh, with the |
| 20 | +intention of making minimal changes to the Gateway API and always preserving |
| 21 | +the [role-oriented] nature of the Gateway API. Additionally, we strive to |
| 22 | +advocate for consistency between implementations of the Gateway API by service |
| 23 | +mesh projects, regardless of their technology stack or proxy. |
| 24 | + |
| 25 | +## Deliverables |
| 26 | + |
| 27 | +The work of the GAMMA intiative will be captured in [Gateway Enhancement |
| 28 | +Proposals][geps] that extend or refine the Gateway API specification to cover |
| 29 | +mesh and mesh-adjacent use cases. To date, these have been relatively small |
| 30 | +changes (albeit sometimes with relatively large impacts!) and we expect that |
| 31 | +to continue. Governance of the Gateway API specification remains solely with |
| 32 | +the maintainers of the Gateway API subproject. |
| 33 | + |
| 34 | +The ideal final outcome of the GAMMA initiative is that service mesh use cases |
| 35 | +become a first-party concern of the Gateway API, at which point there will be |
| 36 | +no further need for a separate initiative. |
| 37 | + |
| 38 | +## Contributing |
| 39 | + |
| 40 | +We welcome contributors of all levels! There are [many ways to |
| 41 | +contribute][contributor-ladder] to the Gateway API and GAMMA, both technical |
| 42 | +and non-technical. |
| 43 | + |
| 44 | +The simplest way to get started is to attend one of GAMMA's regular meetings, |
| 45 | +which happen every two weeks on Tuesdays for 1 hour (as found on the |
| 46 | +[sig-network calendar]), alternating between 3pm PT and 8am PT slots to try to |
| 47 | +be as time-zone inclusive as possible. GAMMA meetings will be moderated by the |
| 48 | +[GAMMA leads] with notes taken by a volunteer. Community members should feel |
| 49 | +free to attend both GAMMA and Gateway API meetings, but are by no means |
| 50 | +obligated to do so. |
| 51 | + |
| 52 | +[contributor-ladder]:/contributing/contributor-ladder |
| 53 | +[east/west traffic]:/concepts/glossary#eastwest-traffic |
| 54 | +[GAMMA leads]:https://github.com/kubernetes-sigs/gateway-api/blob/main/OWNERS_ALIASES#L23 |
| 55 | +[geps]:/geps/overview |
| 56 | +[north/south traffic]:/concepts/glossary#northsouth-traffic |
| 57 | +[service mesh]:/concepts/glossary#service-mesh |
| 58 | +[sig-network calendar]:/contributing/community/#meetings |
| 59 | +[role-oriented]:/concepts/roles-and-personas |
| 60 | + |
| 61 | +## An Overview of GAMMA |
| 62 | + |
| 63 | +!!! danger "Experimental in v0.8.0" |
| 64 | + |
| 65 | + GAMMA support for service mesh use cases is _experimental_ in `v0.8.0`. |
| 66 | + It is possible that it will change; we do not recommend it in production |
| 67 | + at this point. |
| 68 | + |
| 69 | +GAMMA has, to date, been able to define service mesh support in the Gateway |
| 70 | +API with relatively small changes. The most significant change that GAMMA has |
| 71 | +introduced to date is that, when configuring a service mesh, individual route |
| 72 | +resources (such as [HTTPRoute]) are [associated directly with Service |
| 73 | +resources](#how-gamma-works). |
| 74 | + |
| 75 | +This is primarily because there will typically only be one mesh active in the |
| 76 | +cluster, so the [Gateway] and [GatewayClass] resources are not used when |
| 77 | +working with a mesh. In turn, this leaves the Service resource as the most |
| 78 | +universal binding point for routing information. |
| 79 | + |
| 80 | +Since the Service resource is unfortunately complex, with several overloaded |
| 81 | +or underspecified aspects, GAMMA has also found it critical to formally define |
| 82 | +the [Service _frontend_ and _backend_ facets][service-facets]. In brief: |
| 83 | + |
| 84 | +- The Service frontend is its name and cluster IP, and |
| 85 | +- The Service backend is its collection of endpoint IPs. |
| 86 | + |
| 87 | +This distinction helps GAMMA to be exact about how routing within the mesh |
| 88 | +functions, without requiring new resources that largely duplicate the Service. |
| 89 | + |
| 90 | +[GatewayClass]: /api-types/gatewayclass |
| 91 | +[Gateway]: /api-types/gateway |
| 92 | +[HTTPRoute]: /api-types/httproute |
| 93 | +[TCPRoute]: /api-types/tcproute |
| 94 | +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ |
| 95 | +[service-mesh]:/concepts/glossary#service-mesh |
| 96 | +[service-facets]:/concepts/service-facets |
| 97 | + |
| 98 | +## How GAMMA Works |
| 99 | + |
| 100 | +GAMMA specifies that individual Route resources attach directly to a Service, |
| 101 | +representing configuration meant to be applied to _any traffic directed to the |
| 102 | +Service_. |
| 103 | + |
| 104 | +!!! danger "Experimental in v0.8.0" |
| 105 | + |
| 106 | + Binding Routes directly to Services seems to be the current best choice |
| 107 | + for configuring mesh routing, but it is still **experimental** and thus |
| 108 | + **subject to change**. |
| 109 | + |
| 110 | +When one or more Routes are attached to a Service, **requests that do not |
| 111 | +match at least one of the Routes will be rejected**. If no Routes are attached |
| 112 | +to a Service, requests to the Service simply proceed per the mesh's default |
| 113 | +behavior (usually resulting in the request being forwarded as if the mesh were |
| 114 | +not present). |
| 115 | + |
| 116 | +Which Routes attach to a given Service is controlled by the Routes themselves |
| 117 | +(working with Kubernetes RBAC): the Route simply specifies a `parentRef` that |
| 118 | +is a Service, rather than a Gateway. |
| 119 | + |
| 120 | +```yaml |
| 121 | +kind: HTTPRoute |
| 122 | +metadata: |
| 123 | + name: smiley-route |
| 124 | + namespace: faces |
| 125 | +spec: |
| 126 | + parentRefs: |
| 127 | + - name: smiley |
| 128 | + kind: Service |
| 129 | + group: core |
| 130 | + port: 80 |
| 131 | + rules: |
| 132 | + ... |
| 133 | +``` |
| 134 | +
|
| 135 | +The relationship between the Route's Namespace and the Service's Namespace is |
| 136 | +important: |
| 137 | +
|
| 138 | +- Same Namespace <a name="producer-routes"></a> |
| 139 | +
|
| 140 | + !!! note "Work in Progress" |
| 141 | +
|
| 142 | + There is ongoing work around the relationship between producer |
| 143 | + routes and consumer routes. |
| 144 | +
|
| 145 | + A Route in the same Namespace as its Service is called a [producer route], |
| 146 | + since it is typically created by the creator of the workload in order to |
| 147 | + define acceptable usage of the workload (for example, [Ana] would deploy |
| 148 | + both the workload and the Route). All requests from any client of the |
| 149 | + workload, from any Namespace, will be affected by this Route. |
| 150 | +
|
| 151 | + The Route shown above is a producer route. |
| 152 | +
|
| 153 | +- Different Namespaces <a name="consumer-routes"></a> |
| 154 | +
|
| 155 | + !!! note "Work in Progress" |
| 156 | +
|
| 157 | + There is ongoing work around the relationship between producer |
| 158 | + routes and consumer routes. |
| 159 | +
|
| 160 | + A Route in a different Namespace than its Service is called a [consumer |
| 161 | + route]. Typically, this is a Route meant to refine how a consumer of a |
| 162 | + given workload makes request of that workload (for example, configuring |
| 163 | + custom timeouts for that consumer's use of the workload). This Route will |
| 164 | + only affect requests from workloads in the same Namespace as the Route. |
| 165 | +
|
| 166 | + For example, this HTTPRoute would cause all clients of the `smiley` workload in the `fast-clients` Namespace to have a 100ms timeout: |
| 167 | + |
| 168 | + ```yaml |
| 169 | + kind: HTTPRoute |
| 170 | + metadata: |
| 171 | + name: smiley-route |
| 172 | + namespace: fast-clients |
| 173 | + spec: |
| 174 | + parentRefs: |
| 175 | + - name: smiley |
| 176 | + namespace: faces |
| 177 | + kind: Service |
| 178 | + group: core |
| 179 | + port: 80 |
| 180 | + rules: |
| 181 | + ... |
| 182 | + timeouts: |
| 183 | + request: 100ms |
| 184 | + ``` |
| 185 | + |
| 186 | +One important note about Routes bound to Services is that multiple Routes for |
| 187 | +the same Service in a single Namespace - whether producer routes or consumer |
| 188 | +routes - will be combined according to the Gateway API [Route merging rules]. |
| 189 | +As such, it is not currently possible to define distinct consumer routes for |
| 190 | +multiple consumers in the same Namespace. |
| 191 | + |
| 192 | +For example, if the `blender` workload and the `mixer` workload both live in |
| 193 | +the `foodprep` Namespace, and both call the `oven` workload using the same |
| 194 | +Service, it is not currently possible for `blender` and `mixer` to use |
| 195 | +HTTPRoutes to set different timeouts for their calls to the `oven` workload. |
| 196 | +`blender` and `mixer` would need to be moved into separate Namespaces to allow |
| 197 | +this. |
| 198 | + |
| 199 | +[Ana]:/concepts/roles-and-personas#ana |
| 200 | +[producer route]:/concepts/glossary#producer-route |
| 201 | +[consumer route]:/concepts/glossary#consumer-route |
| 202 | +[service mesh]:/concepts/glossary#service-mesh |
| 203 | +[Route merging rules]:/api-types/httproute#merging |
| 204 | + |
| 205 | +## Request Flow |
| 206 | + |
| 207 | +A typical [east/west] API request flow when a GAMMA-compliant mesh is in use |
| 208 | +looks like: |
| 209 | + |
| 210 | +1. A client workload makes a request to <http://foo.ns.service.cluster.local>. |
| 211 | +2. The mesh data plane intercepts the request and identifies it as traffic for |
| 212 | + the Service `foo` in Namespace `ns`. |
| 213 | +3. The data plane locates Routes associated with the `foo` Service, then: |
| 214 | + |
| 215 | + a. If there are no associated Routes, the request is always allowed, and |
| 216 | + the `foo` workload itself is considered the destination workload. |
| 217 | + |
| 218 | + b. If there are associated Routes and the request matches at least one of |
| 219 | + them, the `backendRefs` of the highest-priority matching Route are used |
| 220 | + to select the destination workload. |
| 221 | + |
| 222 | + c. If there are associated Routes, but the request matches none of them, |
| 223 | + the request is rejected. |
| 224 | + |
| 225 | +6. The data plane routes the request on to the destination workload (most |
| 226 | + likely using [endpoint routing], but it is allowed to use [Service |
| 227 | + routing]). |
| 228 | + |
| 229 | +[east/west]:/concepts/glossary#eastwest-traffic |
| 230 | +[endpoint routing]:/concepts/glossary#endpoint-routing |
| 231 | +[Service routing]:/concepts/glossary#service-routing |
| 232 | + |
| 233 | +## Contributing |
| 234 | + |
0 commit comments