sigs.k8s.io/gateway-api@v1.0.0/site-src/concepts/gamma.md (about)

     1  # The GAMMA initiative (Gateway API for Service Mesh)
     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 the Gateway API for Service Mesh
    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](#gateway-api-for-mesh).
    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 the Gateway API to be exact about how routing within a
    88  mesh functions, without requiring new resources that largely duplicate the
    89  Service.
    90  
    91  [GatewayClass]: /api-types/gatewayclass
    92  [Gateway]: /api-types/gateway
    93  [HTTPRoute]: /api-types/httproute
    94  [TCPRoute]: /api-types/tcproute
    95  [Service]: https://kubernetes.io/docs/concepts/services-networking/service/
    96  [service-mesh]:/concepts/glossary#service-mesh
    97  [service-facets]:/concepts/service-facets
    98  
    99  ## How the Gateway API works for Service Mesh <a name="gateway-api-for-mesh">
   100  
   101  GAMMA specifies that individual Route resources attach directly to a Service,
   102  representing configuration meant to be applied to _any traffic directed to the
   103  Service_.
   104  
   105  !!! danger "Experimental in v0.8.0"
   106  
   107      Binding Routes directly to Services seems to be the current best choice
   108      for configuring mesh routing, but it is still **experimental** and thus
   109      **subject to change**.
   110  
   111  When one or more Routes are attached to a Service, **requests that do not
   112  match at least one of the Routes will be rejected**. If no Routes are attached
   113  to a Service, requests to the Service simply proceed per the mesh's default
   114  behavior (usually resulting in the request being forwarded as if the mesh were
   115  not present).
   116  
   117  Which Routes attach to a given Service is controlled by the Routes themselves
   118  (working with Kubernetes RBAC): the Route simply specifies a `parentRef` that
   119  is a Service, rather than a Gateway.
   120  
   121  ```yaml
   122  kind: HTTPRoute
   123  metadata:
   124    name: smiley-route
   125    namespace: faces
   126  spec:
   127    parentRefs:
   128      - name: smiley
   129        kind: Service
   130        group: core
   131        port: 80
   132    rules:
   133      ...
   134  ```
   135  
   136  The relationship between the Route's Namespace and the Service's Namespace is
   137  important:
   138  
   139  - Same Namespace <a name="producer-routes"></a>
   140  
   141      !!! note "Work in Progress"
   142  
   143          There is ongoing work around the relationship between producer
   144          routes and consumer routes.
   145  
   146      A Route in the same Namespace as its Service is called a [producer route],
   147      since it is typically created by the creator of the workload in order to
   148      define acceptable usage of the workload (for example, [Ana] would deploy
   149      both the workload and the Route). All requests from any client of the
   150      workload, from any Namespace, will be affected by this Route.
   151  
   152      The Route shown above is a producer route.
   153  
   154  - Different Namespaces <a name="consumer-routes"></a>
   155  
   156      !!! note "Work in Progress"
   157  
   158          There is ongoing work around the relationship between producer
   159          routes and consumer routes.
   160  
   161      A Route in a different Namespace than its Service is called a [consumer
   162      route]. Typically, this is a Route meant to refine how a consumer of a
   163      given workload makes request of that workload (for example, configuring
   164      custom timeouts for that consumer's use of the workload). This Route will
   165      only affect requests from workloads in the same Namespace as the Route.
   166  
   167      For example, this HTTPRoute would cause all clients of the `smiley`
   168      workload in the `fast-clients` Namespace to have a 100ms timeout:
   169  
   170      ```yaml
   171      kind: HTTPRoute
   172      metadata:
   173        name: smiley-route
   174        namespace: fast-clients
   175      spec:
   176        parentRefs:
   177        - name: smiley
   178          namespace: faces
   179          kind: Service
   180          group: core
   181          port: 80
   182        rules:
   183          ...
   184          timeouts:
   185            request: 100ms
   186      ```
   187  
   188  One important note about Routes bound to Services is that multiple Routes for
   189  the same Service in a single Namespace - whether producer routes or consumer
   190  routes - will be combined according to the Gateway API [Route merging rules].
   191  As such, it is not currently possible to define distinct consumer routes for
   192  multiple consumers in the same Namespace.
   193  
   194  For example, if the `blender` workload and the `mixer` workload both live in
   195  the `foodprep` Namespace, and both call the `oven` workload using the same
   196  Service, it is not currently possible for `blender` and `mixer` to use
   197  HTTPRoutes to set different timeouts for their calls to the `oven` workload.
   198  `blender` and `mixer` would need to be moved into separate Namespaces to allow
   199  this.
   200  
   201  [Ana]:/concepts/roles-and-personas#ana
   202  [producer route]:/concepts/glossary#producer-route
   203  [consumer route]:/concepts/glossary#consumer-route
   204  [service mesh]:/concepts/glossary#service-mesh
   205  [Route merging rules]:/api-types/httproute#merging
   206  
   207  ## Request Flow
   208  
   209  A typical [east/west] API request flow when a GAMMA-compliant mesh is in use
   210  looks like:
   211  
   212  1. A client workload makes a request to <http://foo.ns.service.cluster.local>.
   213  2. The mesh data plane intercepts the request and identifies it as traffic for
   214     the Service `foo` in Namespace `ns`.
   215  3. The data plane locates Routes associated with the `foo` Service, then:
   216  
   217      a. If there are no associated Routes, the request is always allowed, and
   218         the `foo` workload itself is considered the destination workload.
   219  
   220      b. If there are associated Routes and the request matches at least one of
   221         them, the `backendRefs` of the highest-priority matching Route are used
   222         to select the destination workload.
   223  
   224      c. If there are associated Routes, but the request matches none of them,
   225         the request is rejected.
   226  
   227  6. The data plane routes the request on to the destination workload (most
   228     likely using [endpoint routing], but it is allowed to use [Service
   229     routing]).
   230  
   231  [east/west]:/concepts/glossary#eastwest-traffic
   232  [endpoint routing]:/concepts/glossary#endpoint-routing
   233  [Service routing]:/concepts/glossary#service-routing