Kubernetes Prow Robot
GitHub
commit
9f22b77310
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 {{<glossary_tooltip text="add-on" term_id="addons">}}
|
||||
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/).
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
Make network services available by using an extensible, role-oriented, protocol-aware configuration
|
||||
mechanism. [Gateway API](https://gateway-api.sigs.k8s.io/) is an {{<glossary_tooltip text="add-on" term_id="addons">}}
|
||||
containing API [kinds](https://gateway-api.sigs.k8s.io/references/spec/) that provide dynamic infrastructure
|
||||
provisioning and advanced traffic routing.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## 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
|
||||
{{<glossary_tooltip text="Service" term_id="service">}}.
|
||||
|
||||
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.
|
||||
|
|
@ -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 >}}
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Terminology
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 6.6 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 32 KiB |
|
|
@ -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.
|
||||
|
||||
<!--more-->
|
||||
|
||||
Gateway API provides a family of extensible, role-oriented, protocol-aware
|
||||
API kinds for modeling service networking in Kubernetes.
|
||||
Loading…
Reference in New Issue