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

     1  ## What is the Gateway API?
     2  
     3  Gateway API is an open source project managed by the
     4  [SIG-NETWORK][sig-network] community. It is an API (collection of resources)
     5  that model service networking in Kubernetes. These resources -
     6  [`GatewayClass`][GatewayClass], [`Gateway`][Gateway],
     7  [`HTTPRoute`][HTTPRoute], [`TCPRoute`][TCPRoute], etc., as well as the
     8  Kubernetes [`Service`][Service] resource - aim to evolve Kubernetes service
     9  networking through expressive, extensible, and role-oriented interfaces that
    10  are implemented by many vendors and have broad industry support.
    11  
    12  [GatewayClass]: /api-types/gatewayclass
    13  [Gateway]: /api-types/gateway
    14  [HTTPRoute]: /api-types/httproute
    15  [TCPRoute]: /api-types/tcproute
    16  [Service]: https://kubernetes.io/docs/concepts/services-networking/service/
    17  
    18  ![Gateway API Model](./images/api-model.png)
    19  
    20  The Gateway API was originally designed to manage traffic from clients outside
    21  the cluster to services inside the cluster -- the _ingress_ or
    22  [_north/south_][north/south traffic] case. Over time, interest from service
    23  mesh users prompted the creation of the [GAMMA initiative][gamma] to define
    24  how the Gateway API could also be used for inter-service or [_east/west_
    25  traffic][east/west traffic] within the same cluster.
    26  
    27  If you're familiar with the older [Ingress API], you can think of the Gateway
    28  API as analogous to a more-expressive next-generation version of that API.
    29  
    30  ## Gateway API for Ingress <a name="for-ingress"></a>
    31  
    32  When using the Gateway API to manage ingress traffic, the [Gateway] resource
    33  defines a point of access at which traffic can be routed across multiple
    34  contexts -- for example, from outside the cluster to inside the cluster
    35  ([north/south traffic]).
    36  
    37  Each Gateway is associated with a [GatewayClass], which describes the actual
    38  kind of [gateway controller] that will handle traffic for the Gateway;
    39  individual routing resources (such as [HTTPRoute]) are then [associated with
    40  the Gateway resources][gateway-attachment]. Separating these different
    41  concerns into distinct resources is a critical part of the role-oriented
    42  nature of the Gateway API, as well as allowing for multiple kinds of gateway
    43  controllers (represented by GatewayClass resources), each with multiple
    44  instances (represented by Gateway resources), in the same cluster.
    45  
    46  [Ingress API]:https://kubernetes.io/docs/concepts/services-networking/ingress/
    47  [north/south traffic]:/concepts/glossary#northsouth-traffic
    48  [east/west traffic]:/concepts/glossary#eastwest-traffic
    49  [gateway controller]:/concepts/glossary#gateway-controller
    50  [gateway-attachment]:/concepts/api-overview#attaching-routes-to-gateways
    51  
    52  ## Gateway API for Service Mesh (the [GAMMA initiative][gamma]) <a name="for-service-mesh"></a>
    53  
    54  !!! danger "Experimental in v0.8.0"
    55  
    56      The [GAMMA initiative][gamma] work for supporting service mesh use cases
    57      is _experimental_ in `v0.8.0`. It is possible that it will change; we do
    58      not recommend it in production at this point.
    59  
    60  Things are a bit different when using the Gateway API to manage a [service
    61  mesh][service-mesh]. Since there will usually only be one mesh active in the
    62  cluster, the [Gateway] and [GatewayClass] resources are not used; instead,
    63  individual route resources (such as [HTTPRoute]) are [associated directly with
    64  Service resources][mesh-attachment], permitting the mesh to manage traffic
    65  from any traffic directed to that Service while preserving the role-oriented
    66  nature of the Gateway API.
    67  
    68  To date, [GAMMA][gamma] has been able to support mesh functionality with
    69  fairly minimal changes to the Gateway API. One particular area that has
    70  rapidly become critical for GAMMA, though, is the definition of the different
    71  [facets of the Service resource][service-facets].
    72  
    73  In Gateway API v0.8.0, GAMMA support for service mesh is **experimental**. We
    74  encourage working with it and providing feedback, but you **must** be prepared
    75  for change in the GAMMA APIs.
    76  
    77  [gamma]:/concepts/gamma/
    78  [service-mesh]:/concepts/glossary#service-mesh
    79  [service-facets]:/concepts/service-facets
    80  [mesh-attachment]:/concepts/gamma#gateway-api-for-mesh
    81  
    82  ## Getting started
    83  
    84  Whether you are a user interested in using the Gateway API or an implementer
    85  interested in conforming to the API, the following resources will help give
    86  you the necessary background:
    87  
    88  - [API overview](/concepts/api-overview)
    89  - [User guides](/guides)
    90  - [Gateway controller implementations](/implementations#gateways)
    91  - [Service Mesh implementations](/implementations#meshes)
    92  - [API reference spec](/reference/spec)
    93  - [Community links](/contributing/community) and [developer guide](/contributing/devguide)
    94  
    95  ## Gateway API concepts
    96  The following design goals drive the concepts of the Gateway API. These
    97  demonstrate how Gateway aims to improve upon current standards like Ingress.
    98  
    99  - **Role-oriented** - Gateway is composed of API resources which model
   100  organizational roles that use and configure Kubernetes service networking.
   101  - **Portable** - This isn't an improvement but rather something
   102  that should stay the same. Just as Ingress is a universal specification with
   103  [numerous implementations](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/),
   104  Gateway API is designed to be a portable specification supported by many
   105  implementations.
   106  - **Expressive** - Gateway API resources support core functionality for things
   107  like header-based matching, traffic weighting, and other capabilities that
   108  were only possible in Ingress through custom annotations.
   109  - **Extensible** - Gateway API allows for custom resources to be linked at
   110  various layers of the API. This makes granular customization possible at the
   111  appropriate places within the API structure.
   112  
   113  Some other notable capabilities include:
   114  
   115  - **GatewayClasses** - GatewayClasses formalize types of load balancing
   116  implementations. These classes make it easy and explicit for users to
   117  understand what kind of capabilities are available via the Kubernetes resource
   118  model.
   119  - **Shared Gateways and cross-Namespace support** - They allow the sharing of
   120  load balancers and VIPs by permitting independent Route resources to attach to
   121  the same Gateway. This allows teams (even across Namespaces) to share
   122  infrastructure safely without direct coordination.
   123  - **Typed Routes and typed backends** - The Gateway API supports typed Route
   124  resources and also different types of backends. This allows the API to be
   125  flexible in supporting various protocols (like HTTP and gRPC) and
   126  various backend targets (like Kubernetes Services, storage buckets, or
   127  functions).
   128  - Experimental **Service mesh support** with the [GAMMA initiative][gamma] -
   129  The Gateway API supports associating routing resources with Service resources,
   130  to configure service meshes as well as ingress controllers.
   131  
   132  ## Why does a role-oriented API matter?
   133  
   134  Whether it’s roads, power, data centers, or Kubernetes clusters,
   135  infrastructure is built to be shared. However, shared infrastructure raises a
   136  common challenge - how to provide flexibility to users of the infrastructure
   137  while maintaining control by owners of the infrastructure?
   138  
   139  The Gateway API accomplishes this through a role-oriented design for
   140  Kubernetes service networking that strikes a balance between distributed
   141  flexibility and centralized control. It allows shared network infrastructure
   142  (hardware load balancers, cloud networking, cluster-hosted proxies etc) to be
   143  used by many different and non-coordinating teams, all bound by the policies
   144  and constraints set by cluster operators.
   145  
   146  The roles used for the Gateway API's design are defined by three personas:
   147  
   148  ### Personas
   149  
   150  - **Ian** (he/him) is an _infrastructure provider_. His role is the care and
   151    feeding of a set of infrastructure that permits multiple isolated clusters
   152    to serve multiple tenants. He is not beholden to any single tenant; rather,
   153    he worries about all of them collectively.
   154  
   155  - **Chihiro** (they/them) is a _cluster operator_. Their role is to manage a
   156    single cluster, ensuring that it meets the needs of its several users.
   157    Again, Chihiro is beholden to no single user of their cluster; they need to
   158    make sure that the cluster serves all of them as needed.
   159  
   160  - **Ana** (she/her) is an _application developer_. Ana is in a unique position
   161    among the Gateway API roles: her focus is on the business needs her
   162    application is meant to serve, _not_ Kubernetes or the Gateway API. In fact,
   163    Ana is likely to view the Gateway API and Kubernetes as pure friction
   164    getting in her way to get things done.
   165  
   166  (These three are discussed in more detail in [Roles and
   167  Personas](/concepts/roles-and-personas).)
   168  
   169  It should be clear that while Ana, Chihiro, and Ian do not necessarily see
   170  eye-to-eye about everything, they need to work together to keep things running
   171  smoothly. This is the core challenge of the Gateway API in a nutshell.
   172  
   173  ### Use Cases
   174  
   175  The [example use cases][use-cases] show this role-oriented model at work. Its
   176  flexibility allows the API to adapt to vastly different organizational models
   177  and implementations while remaining a portable and standard API.
   178  
   179  The use cases presented are deliberately cast in terms of the roles presented
   180  above. Ultimately the Gateway API is meant for use by humans, which means that
   181  it must fit the uses to which each of Ana, Chihiro, and Ian will put it.
   182  
   183  [use-cases]:/concepts/use-cases
   184  
   185  ## What's the difference between Gateway API and an API Gateway?
   186  
   187  An API Gateway is a general concept that describes anything that exposes
   188  capabilities of a backend service, while providing extra capabilities for
   189  traffic routing and manipulation, such as load balancing, request and response
   190  transformation, and sometimes more advanced features like authentication and
   191  authorization, rate limiting, and circuit breaking.
   192  
   193  The Gateway API is an interface, or set of resources, that model service
   194  networking in Kubernetes. One of the main resources is a `Gateway`, which
   195  declares the Gateway type (or class) to instantiate and its configuration. As
   196  a Gateway Provider, you can implement the Gateway API to model Kubernetes
   197  service networking in an expressive, extensible, and role-oriented way.
   198  
   199  Most Gateway API implementations are API Gateways to some extent, but not all
   200  API Gateways are Gateway API implementations.
   201  
   202  ## Who is working on Gateway API?
   203  
   204  The Gateway API is a
   205  [SIG-Network](https://github.com/kubernetes/community/tree/master/sig-network)
   206  project being built to improve and standardize service networking in
   207  Kubernetes. Current and in-progress implementations include Contour,
   208  Emissary-ingress (Ambassador API Gateway), Google Kubernetes Engine (GKE),
   209  Istio, Kong, Linkerd, and Traefik. Check out the [implementations
   210  reference](implementations.md) to see the latest projects & products that
   211  support Gateway. If you are interested in contributing to or building an
   212  implementation using the Gateway API then don’t hesitate to [get
   213  involved!](/contributing/community)
   214  
   215  [sig-network]: https://github.com/kubernetes/community/tree/master/sig-network
   216