Adds Gateway API docs

- Adds Gateway API term to the glossary.
- Adds Gateway API as reference in the addons page.
- Adds a page to the Service networking docs that explains Gateway API.
- Updates existing docs to reference the newly added Gateway API docs.

Signed-off-by: Daneyon Hansen <daneyon.hansen@solo.io>

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

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 {{<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/).
 

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
+---
+
+<!-- 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.

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 >}}
+
 <!-- body -->
 
 ## Terminology

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:

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.
+
+<!--more--> 
+
+Gateway API provides a family of extensible, role-oriented, protocol-aware
+API kinds for modeling service networking in Kubernetes.