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

     1  # Gateway API Use Cases
     2  
     3  The Gateway API covers a _very_ wide range of use cases (which is both a
     4  strength and a weakness!). This page is emphatically _not_ meant to be an
     5  exhaustive list of these use cases: rather, it is meant to provide some
     6  examples that can be helpful to demonstrate how the API can be used.
     7  
     8  In all cases, it's very important to bear in mind the [roles and personas]
     9  used in the Gateway API. The use cases presented here are deliberately
    10  described in terms of [Ana], [Chihiro], and [Ian]: they are the ones for whom
    11  the API must be usable. (It's also important to remember that even though
    12  these roles might be filled by the same person, especially in smaller
    13  organizations, they all have distinct concerns that we need to consider
    14  separately.)
    15  
    16  [roles and personas]:/concepts/roles-and-personas
    17  [Ana]:/concepts/roles-and-personas#ana
    18  [Chihiro]:/concepts/roles-and-personas#chihiro
    19  [Ian]:/concepts/roles-and-personas#ian
    20  
    21  ## The Use Cases
    22  
    23  - [Basic north/south use case](#basic-northsouth-use-case)
    24  - [Multiple applications behind a single
    25    Gateway](#multiple-applications-behind-a-single-gateway)
    26  - [Basic east/west use case](#basic-eastwest-use-case) -- **experimental**
    27  - [Gateway and mesh use case](#gateway-and-mesh-use-case) -- **experimental**
    28  
    29  [role and personas]:/concepts/roles-and-personas
    30  
    31  ## Basic [north/south] use case
    32  
    33  ??? success "Standard Channel in v0.8.0+"
    34  
    35      The [north/south] use case is fully supported by the Standard Channel
    36      in `v0.8.0+`.
    37  
    38  Ana has created a microservice application which she wants to run in
    39  Kubernetes. Her application will be used by clients outside the cluster, and
    40  while Ana has created the application, setting up the cluster is not in her
    41  wheelhouse.
    42  
    43  1. Ana goes to Chihiro to ask them to set up a cluster. Ana tells Chihiro that
    44     her clients will expect her APIs to be available using URLs rooted at
    45     `https://ana.application.com/`.
    46  
    47  2. Chihiro goes to Ian and requests a cluster.
    48  
    49  3. Ian provisions a cluster running a gateway controller with a [GatewayClass]
    50     resource named `basic-gateway-class`. The gateway controller manages the
    51     infrastructure associated with routing traffic from outside the cluster to
    52     inside the cluster.
    53  
    54  4. Ian gives Chihiro credentials to the new cluster, and tells Chihiro that
    55     they can use GatewayClass `basic-gateway-class` to set things up.
    56  
    57  5. Chihiro applies a [Gateway] named `ana-gateway` to the cluster, telling it
    58     to listen on port 443 for TLS traffic, and providing it a TLS certificate
    59     with a Subject CN of `ana.application.com`. They associate this Gateway with the `basic-gateway-class` GatewayClass.
    60  
    61  6. The gateway controller that Ian provisioned in step 3 allocates a load
    62     balancer and an IP address for `ana-gateway`, provisions data-plane
    63     components that can route requests arriving at the load balancer on port
    64     443, and starts watching for routing resources associated with
    65     `ana-gateway`.
    66  
    67  7. Chihiro gets the IP address of `ana-gateway` and creates a DNS record
    68     outside the cluster for `ana.application.com` to match.
    69  
    70  8. Chihiro tells Ana that she's good to go, using the Gateway named
    71     `ana-gateway`.
    72  
    73  9. Ana writes and applies [HTTPRoute] resources to configure which URL paths
    74     are allowed and which microservices should handle them. She associates
    75     these HTTPRoutes with Gateway `ana-gateway` using the Gateway API [Route
    76     Attachment Process].
    77  
    78  10. At this point, when requests arrive at the load balancer, they are routed
    79      to Ana's application according to her routing specification.
    80  
    81  This allows Chihiro to enforce centralized policies [such as
    82  TLS](/guides/tls#downstream-tls) at the Gateway, while simultaneously allowing
    83  Ana and her colleagues control over the application's [routing
    84  logic](/guides/http-routing) and rollout plans (e.g. [traffic splitting
    85  rollouts](/guides/traffic-splitting)).
    86  
    87  [north/south]:/concepts/glossary#northsouth-traffic
    88  
    89  ## Multiple applications behind a single Gateway
    90  
    91  ??? success "Standard Channel in v0.8.0+"
    92  
    93      The [north/south] use case is fully supported by the Standard Channel
    94      in `v0.8.0+`.
    95  
    96  This is remarkably similar to the [basic north/south use
    97  case](#basic-northsouth-use-case), but there are multiple application teams:
    98  Ana and her team are managing a storefront application in the `store`
    99  Namespace, while Allison and her team are managing a website in the `site`
   100  Namespace.
   101  
   102  - Ian and Chihiro work together to provide a cluster, `GatewayClass`, and
   103    `Gateway`, as above.
   104  
   105  - Ana and Allison independently deploy workloads and HTTPRoutes bound to the
   106    same `Gateway` resource.
   107  
   108  Again, this separation of concerns allows Chihiro to enforce centralized
   109  policies [such as TLS](/guides/tls#downstream-tls) can be enforced at the
   110  Gateway. Meanwhile, Ana and Allison run their applications [in their own
   111  Namespaces](/guides/multiple-ns), but attach their Routes to the same shared
   112  Gateway, allowing them to independently control their [routing
   113  logic](/guides/http-routing), [traffic splitting
   114  rollout](/guides/traffic-splitting), etc., while not worrying about the things
   115  that Chihiro and Ian are handling.
   116  
   117  [HTTPRoute]:/api-types/httproute
   118  [GatewayClass]:/api-types/gatewayclass
   119  [Gateway]:/api-types/gateway
   120  [Route Attachment Process]:/concepts/api-overview#attaching-routes-to-gateways
   121  
   122  ![Gateway API Roles](/images/gateway-roles.png)
   123  
   124  ## Basic [east/west] use case
   125  
   126  !!! danger "Experimental in v0.8.0"
   127  
   128      The [GAMMA initiative][gamma] work for supporting service mesh use cases
   129      is _experimental_ in `v0.8.0`. It is possible that it will change; we do
   130      not recommend it in production at this point.
   131  
   132  In this scenario, Ana has built a workload which is already running in a
   133  cluster with a [GAMMA]-compliant [service mesh]. She wants to use the mesh to
   134  protect her workload by rejecting calls to her workload with incorrect
   135  URL paths, and by enforcing timeouts whenever anyone makes a request of her
   136  workload.
   137  
   138  - Chihiro and Ian have already provided a cluster with a running service mesh.
   139    Ana doesn't need to make any requests of them.
   140  
   141  - Ana writes an HTTPRoute that defines acceptable routes and timeouts and has
   142    a `parentRef` of her workload's Service.
   143  
   144  - Ana applies her HTTPRoute in the same Namespace as her workload.
   145  
   146  - The mesh automatically starts enforcing the routing policy described by
   147    Ana's HTTPRoute.
   148  
   149  In this case, the separation of concerns across roles allows Ana to take
   150  advantage of the service mesh, with custom routing logic, without any
   151  bottlenecks in requests to Chihiro or Ian.
   152  
   153  [east/west]:/concepts/glossary#eastwest-traffic
   154  [GAMMA]:/concepts/gamma/
   155  [service mesh]:/concepts/glossary#service-mesh
   156  
   157  ## Gateway and mesh use case
   158  
   159  !!! danger "Experimental in v0.8.0"
   160  
   161      The [GAMMA initiative][gamma] work for supporting service mesh use cases
   162      is _experimental_ in `v0.8.0`. It is possible that it will change; we do
   163      not recommend it in production at this point.
   164  
   165  This is effectively a combination of the [multiple applications behind a
   166  single Gateway](#multiple-applications-behind-a-single-gateway) and [basic
   167  east/west](#basic-eastwest-use-case) use cases:
   168  
   169  - Chihiro and Ian will provision a cluster, a [GatewayClass], and a [Gateway].
   170  
   171  - Ana and Allison will deploy their applications in the appropriate
   172    Namespaces.
   173  
   174  - Ana and Allison will then apply HTTPRoute resources as appropriate.
   175  
   176  There are two very important changes in this scenario, though, since a mesh is
   177  involved:
   178  
   179  1. If Chihiro has deployed a [gateway controller] that defaults to [Service
   180     routing], they will probably need to reconfigure it for [endpoint routing].
   181     (This is an ongoing area of work for [GAMMA], but the expectation is that
   182     endpoint routing will be recommended.)
   183  
   184  2. Ana and/or Allison will need to bind HTTPRoutes to their respective
   185     workloads' Services to configure mesh routing logic. These could be
   186     distinct HTTPRoutes solely for the mesh, or they could apply single
   187     HTTPRoutes that bind to both the Gateway and a Service.
   188  
   189  As always, the ultimate point of separating concerns in this way is that it
   190  permits Chihiro to enforce centralized policies [such as
   191  TLS](/guides/tls#downstream-tls) at the Gateway, while allowing Ana and
   192  Allison to retain independent control of [routing
   193  logic](/guides/http-routing), [traffic splitting
   194  rollout](/guides/traffic-splitting), etc., both for [north/south] and for
   195  [east/west] routing.
   196  
   197  
   198  
   199  
   200  [gateway controller]:/concepts/glossary#gateway-controller
   201  [Service routing]:/concepts/glossary#service-routing
   202  [endpoint routing]:/concepts/glossary#endpoint-routing