diff --git a/content/en/docs/concepts/cluster-administration/addons.md b/content/en/docs/concepts/cluster-administration/addons.md index aa36d4c97a..9565b37c8c 100644 --- a/content/en/docs/concepts/cluster-administration/addons.md +++ b/content/en/docs/concepts/cluster-administration/addons.md @@ -54,6 +54,9 @@ installation instructions. The list does not try to be exhaustive. and bare metal workloads. * [Flannel](https://github.com/flannel-io/flannel#deploying-flannel-manually) is an overlay network provider that can be used with Kubernetes. +* [Gateway API](/docs/concepts/services-networking/gateway/) is an open source project managed by + the [SIG Network](https://github.com/kubernetes/community/tree/master/sig-network) community and + provides an expressive, extensible, and role-oriented API for modeling service networking. * [Knitter](https://github.com/ZTE/Knitter/) is a plugin to support multiple network interfaces in a Kubernetes pod. * [Multus](https://github.com/k8snetworkplumbingwg/multus-cni) is a Multi plugin for diff --git a/content/en/docs/concepts/services-networking/_index.md b/content/en/docs/concepts/services-networking/_index.md index 25a59d536a..1f30d33e6f 100644 --- a/content/en/docs/concepts/services-networking/_index.md +++ b/content/en/docs/concepts/services-networking/_index.md @@ -54,6 +54,8 @@ Kubernetes networking addresses four concerns: to be reachable from outside your cluster. - [Ingress](/docs/concepts/services-networking/ingress/) provides extra functionality specifically for exposing HTTP applications, websites and APIs. + - [Gateway API](/docs/concepts/services-networking/gateway/) is an {{}} + that provides an expressive, extensible, and role-oriented family of API kinds for modeling service networking. - You can also use Services to [publish services only for consumption inside your cluster](/docs/concepts/services-networking/service-traffic-policy/). diff --git a/content/en/docs/concepts/services-networking/gateway.md b/content/en/docs/concepts/services-networking/gateway.md new file mode 100644 index 0000000000..52c019ece9 --- /dev/null +++ b/content/en/docs/concepts/services-networking/gateway.md @@ -0,0 +1,206 @@ +--- +title: Gateway API +content_type: concept +description: >- + Gateway API is a family of API kinds that provide dynamic infrastructure provisioning + and advanced traffic routing. +weight: 55 +--- + + + +Make network services available by using an extensible, role-oriented, protocol-aware configuration +mechanism. [Gateway API](https://gateway-api.sigs.k8s.io/) is an {{}} +containing API [kinds](https://gateway-api.sigs.k8s.io/references/spec/) that provide dynamic infrastructure +provisioning and advanced traffic routing. + + + +## Design principles + +The following principles shaped the design and architecture of Gateway API: + +* __Role-oriented:__ Gateway API kinds are modeled after organizational roles that are + responsible for managing Kubernetes service networking: + * __Infrastructure Provider:__ Manages infrastructure that allows multiple isolated clusters + to serve multiple tenants, e.g. a cloud provider. + * __Cluster Operator:__ Manages clusters and is typically concerned with policies, network + access, application permissions, etc. + * __Application Developer:__ Manages an application running in a cluster and is typically + concerned with application-level configuration and [Service](/docs/concepts/services-networking/service/) + composition. +* __Portable:__ Gateway API specifications are defined as [custom resources](docs/concepts/extend-kubernetes/api-extension/custom-resources) + and are supported by many [implementations](https://gateway-api.sigs.k8s.io/implementations/). +* __Expressive:__ Gateway API kinds support functionality for common traffic routing use cases + such as header-based matching, traffic weighting, and others that were only possible in + [Ingress](/docs/concepts/services-networking/ingress/) by using custom annotations. +* __Extensible:__ Gateway 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. + +## Resource model + +Gateway API has three stable API kinds: + +* __GatewayClass:__ Defines a set of gateways with common configuration and managed by a controller + that implements the class. + +* __Gateway:__ Defines an instance of traffic handling infrastructure, such as cloud load balancer. + +* __HTTPRoute:__ Defines HTTP-specific rules for mapping traffic from a Gateway listener to a + representation of backend network endpoints. These endpoints are often represented as a + {{}}. + +Gateway API is organized into different API kinds that have interdependent relationships to support +the role-oriented nature of organizations. A Gateway object is associated with exactly one GatewayClass; +the GatewayClass describes the gateway controller responsible for managing Gateways of this class. +One or more route kinds such as HTTPRoute, are then associated to Gateways. A Gateway can filter the routes +that may be attached to its `listeners`, forming a bidirectional trust model with routes. + +The following figure illustrates the relationships of the three stable Gateway API kinds: + +{{< figure src="/docs/images/gateway-kind-relationships.svg" alt="A figure illustrating the relationships of the three stable Gateway API kinds" class="diagram-medium" >}} + +### GatewayClass {#api-kind-gateway-class} + +Gateways can be implemented by different controllers, often with different configurations. A Gateway +must reference a GatewayClass that contains the name of the controller that implements the +class. + +A minimal GatewayClass example: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: example-class +spec: + controllerName: example.com/gateway-controller +``` + +In this example, a controller that has implemented Gateway API is configured to manage GatewayClasses +with the controller name `example.com/gateway-controller`. Gateways of this class will be managed by +the implementation's controller. + +See the [GatewayClass](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.GatewayClass) +reference for a full definition of this API kind. + +### Gateway {#api-kind-gateway} + +A Gateway describes an instance of traffic handling infrastructure. It defines a network endpoint +that can be used for processing traffic, i.e. filtering, balancing, splitting, etc. for backends +such as a Service. For example, a Gateway may represent a cloud load balancer or an in-cluster proxy +server that is configured to accept HTTP traffic. + +A minimal Gateway resource example: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: example-gateway +spec: + gatewayClassName: example-class + listeners: + - name: http + protocol: HTTP + port: 80 +``` + +In this example, an instance of traffic handling infrastructure is programmed to listen for HTTP +traffic on port 80. Since the `addresses` field is unspecified, an address or hostname is assigned +to the Gateway by the implementation's controller. This address is used as a network endpoint for +processing traffic of backend network endpoints defined in routes. + +See the [Gateway](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Gateway) +reference for a full definition of this API kind. + +### HTTPRoute {#api-kind-httproute} + +The HTTPRoute kind specifies routing behavior of HTTP requests from a Gateway listener to backend network +endpoints. For a Service backend, an implementation may represent the backend network endpoint as a Service +IP or the backing Endpoints of the Service. An HTTPRoute represents configuration that is applied to the +underlying Gateway implementation. For example, defining a new HTTPRoute may result in configuring additional +traffic routes in a cloud load balancer or in-cluster proxy server. + +A minimal HTTPRoute example: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: example-httproute +spec: + parentRefs: + - name: example-gateway + hostnames: + - "www.example.com" + rules: + - matches: + - path: + type: PathPrefix + value: /login + backendRefs: + - name: example-svc + port: 8080 +``` + +In this example, HTTP traffic from Gateway `example-gateway` with the Host: header set to `www.example.com` +and the request path specified as `/login` will be routed to Service `example-svc` on port `8080`. + +See the [HTTPRoute](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.HTTPRoute) +reference for a full definition of this API kind. + +## Request flow + +Here is a simple example of HTTP traffic being routed to a Service by using a Gateway and an HTTPRoute: + +{{< figure src="/docs/images/gateway-request-flow.svg" alt="A diagram that provides an example of HTTP traffic being routed to a Service by using a Gateway and an HTTPRoute" class="diagram-medium" >}} + +In this example, the request flow for a Gateway implemented as a reverse proxy is: + +1. The client starts to prepare an HTTP request for the URL `http://www.example.com` +2. The client's DNS resolver queries for the destination name and learns a mapping to + one or more IP addresses associated with the Gateway. +3. The client sends a request to the Gateway IP address; the reverse proxy receives the HTTP + request and uses the Host: header to match a configuration that was derived from the Gateway + and attached 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; for example, to add or emove headers, + based on filter rules of the HTTPRoute. +6. Lastly, the reverse proxy forwards the request to one or more backends. + +## Conformance + +Gateway API covers a broad set of features and is widely implemented. This combination requires +clear conformance definitions and tests to ensure that the API provides a consistent experience +wherever it is used. + +See the [conformance](https://gateway-api.sigs.k8s.io/concepts/conformance/) documentation to +understand details such as release channels, support levels, and running conformance tests. + +## Migrating from Ingress + +Gateway API is the successor to the [Ingress](/docs/concepts/services-networking/ingress/) API. +However, it does not include the Ingress kind. As a result, a one-time conversion from your existing +Ingress resources to Gateway API resources is necessary. + +Refer to the [ingress migration](https://gateway-api.sigs.k8s.io/guides/migrating-from-ingress/#migrating-from-ingress) +guide for details on migrating Ingress resources to Gateway API resources. + +## {{% heading "whatsnext" %}} + +Instead of Gateway API resources being natively implemented by Kubernetes, the specifications +are defined as [Custom Resources](docs/concepts/extend-kubernetes/api-extension/custom-resources) +supported by a wide range of [implementations](https://gateway-api.sigs.k8s.io/implementations/). +[Install](https://gateway-api.sigs.k8s.io/guides/#installing-gateway-api) the Gateway API CRDs or +follow the installation instructions of your selected implementation. After installing an +implementation, use the [Getting Started](https://gateway-api.sigs.k8s.io/guides/) guide to help +you quickly start working with Gateway API. + +{{< note >}} +Make sure to review the documentation of your selected implementation to understand any caveats. +{{< /note >}} + +Refer to the [API specification](https://gateway-api.sigs.k8s.io/reference/spec/) for additional +details of all Gateway API kinds. diff --git a/content/en/docs/concepts/services-networking/ingress.md b/content/en/docs/concepts/services-networking/ingress.md index cad103a7d0..89888cb5d3 100644 --- a/content/en/docs/concepts/services-networking/ingress.md +++ b/content/en/docs/concepts/services-networking/ingress.md @@ -15,6 +15,10 @@ weight: 30 {{< feature-state for_k8s_version="v1.19" state="stable" >}} {{< glossary_definition term_id="ingress" length="all" >}} +{{< note >}} +Ingress is frozen. New features are being added to the [Gateway API](/docs/concepts/services-networking/gateway/). +{{< /note >}} + ## Terminology diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index 70f148e3d2..8bf255efac 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -1006,7 +1006,7 @@ Learn more about Services and how they fit into Kubernetes: * Read about [Ingress](/docs/concepts/services-networking/ingress/), which exposes HTTP and HTTPS routes from outside the cluster to Services within your cluster. -* Read about [Gateway](https://gateway-api.sigs.k8s.io/), an extension to +* Read about [Gateway](/docs/concepts/services-networking/gateway/), an extension to Kubernetes that provides more flexibility than Ingress. For more context, read the following: diff --git a/content/en/docs/images/gateway-kind-relationships.svg b/content/en/docs/images/gateway-kind-relationships.svg new file mode 100644 index 0000000000..cca73e75ce --- /dev/null +++ b/content/en/docs/images/gateway-kind-relationships.svg @@ -0,0 +1 @@ +
cluster
GatewayClass
Gateway
HTTPRoute
 \ No newline at end of file diff --git a/content/en/docs/images/gateway-request-flow.svg b/content/en/docs/images/gateway-request-flow.svg new file mode 100644 index 0000000000..a02852868b --- /dev/null +++ b/content/en/docs/images/gateway-request-flow.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/reference/glossary/gateway.md b/content/en/docs/reference/glossary/gateway.md new file mode 100644 index 0000000000..1b8b647671 --- /dev/null +++ b/content/en/docs/reference/glossary/gateway.md @@ -0,0 +1,20 @@ +--- +title: Gateway API +id: gateway-api +date: 2023-10-19 +full_link: /docs/concepts/services-networking/gateway/ +short_description: > + An API for modeling service networking in Kubernetes. + +aka: +tags: +- networking +- architecture +- extension +--- + A family of API kinds for modeling service networking in Kubernetes. + + + +Gateway API provides a family of extensible, role-oriented, protocol-aware +API kinds for modeling service networking in Kubernetes.