Document how to migrate from Ingress to Gateway API

Documentation/network/servicemesh/index.rst

@@ -16,3 +16,4 @@ Service Mesh
    ingress
    l7-traffic-management
    gateway-api/gateway-api
+   ingress-to-gateway/ingress-to-gateway

Documentation/network/servicemesh/ingress-to-gateway/http-migration.rst

@@ -0,0 +1,189 @@
+.. only:: not (epub or latex or html)
+
+    WARNING: You are looking at unreleased Cilium documentation.
+    Please use the official rendered version released here:
+    https://docs.cilium.io
+
+.. _gs_gateway_http_migration:
+
+**********************
+HTTP Migration Example
+**********************
+
+In this example, we will show how to take an existing Ingress configuration and migrate it to the equivalent Gateway API resource.
+
+We will use the Cilium :ref:`gs_ingress_http` as the starting Ingress configuration. 
+The same approach will apply to other controllers, albeit each Ingress controller configuration varies.
+
+The example Ingress configuration routes traffic to backend services from the
+``bookinfo`` demo microservices app from the Istio project.
+
+Review Ingress Configuration
+============================
+
+You'll find the example Ingress definition in ``basic-ingress.yaml``.
+
+.. literalinclude:: ../../../../examples/kubernetes/servicemesh/basic-ingress.yaml
+
+This example listens for traffic on port 80, routes requests for the path ``/details`` to the ``details`` service,
+and ``/`` to the ``productpage`` service.
+
+
+Create Equivalent Gateway Configuration
+=======================================
+
+To create the equivalent Gateway configuration, you must consider the following:
+
+- Entry Point
+
+The entry point is a combination of an IP address and port through which the data plane is accessible to external clients.
+
+.. tabs::
+
+    .. group-tab:: Ingress
+
+        Every Ingress resource has two implicit entry points -- one for HTTP and the other for HTTPS traffic. 
+        An Ingress controller provides those entry points. Typically, they will either be shared by all Ingress resources, or every Ingress resource will get dedicated entry points.
+
+        .. code-block:: shell-session
+
+            apiVersion: networking.k8s.io/v1
+            kind: Ingress
+            spec:
+              ingressClassName: cilium
+
+    .. group-tab:: Gateway API
+
+        In the Gateway API, entry points must be explicitly defined in a Gateway resource. 
+        For example, if you want the data plane to handle HTTP traffic on port 80, you need to define a listener for that traffic. 
+        Typically, a Gateway implementation provides a dedicated data plane for each Gateway resource.
+
+        .. code-block:: shell-session
+
+            apiVersion: gateway.networking.k8s.io/v1beta1
+            kind: Gateway
+            metadata:
+              name: cilium
+            spec:
+              gatewayClassName: cilium
+              listeners:
+              - name: http
+                port: 80
+                protocol: HTTP
+
+- Routing Rules
+
+When using Ingress or Gateway API, routing rules need to be defined to attach applications to those entry points.
+
+.. tabs::
+
+    .. group-tab:: Ingress
+
+        The path-based routing rules are configured in the Ingress resource map directly to the routing rules of the HTTPRoute.
+
+        In the Ingress, each hostname has separate routing rules, 
+
+        .. code-block:: shell-session
+
+            apiVersion: networking.k8s.io/v1
+            kind: Ingress
+            [...]
+            rules:
+            - http:
+                paths:
+                - backend:
+                    service:
+                      name: details
+                      port:
+                        number: 9080
+                  path: /details
+                  pathType: Prefix
+                - backend:
+                    service:
+                      name: productpage
+                      port:
+                        number: 9080
+                  path: /
+                  pathType: Prefix
+
+    .. group-tab:: Gateway API
+
+        The routing rules are configured in the HTTPRoute.
+
+        .. code-block:: shell-session
+
+            ---
+            apiVersion: gateway.networking.k8s.io/v1beta1
+            kind: HTTPRoute
+            spec:
+              parentRefs:
+              - name: cilium
+            rules:
+            - backendRefs:
+              - name: productpage
+                port: 9080
+              matches:
+              - path:
+                  type: PathPrefix
+                  value: /
+            - backendRefs:
+              - name: details
+                port: 9080
+              matches:
+              - path:
+                  type: PathPrefix
+                  value: /details
+
+- Selecting Data Plane to Attach to:
+
+Both Ingress and Gateway API resources need to be explicitly attached to a Dataplane.  
+
+.. tabs::
+
+    .. group-tab:: Ingress
+
+        An Ingress resource must specify a class to select which Ingress controller to use. 
+
+        .. code-block:: shell-session
+
+            apiVersion: networking.k8s.io/v1
+            kind: Ingress
+            spec:
+              ingressClassName: cilium
+
+    .. group-tab:: Gateway API
+
+        A Gateway resource must also specify a class: in our case, it will always be the ``cilium`` class. 
+        An HTTPRoute must specify which Gateway (or Gateways) to attach to via a ``parentRef``.
+
+        .. code-block:: shell-session
+
+            apiVersion: gateway.networking.k8s.io/v1beta1
+            kind: Gateway
+            metadata:
+              name: cilium
+              namespace: default
+            spec:
+              gatewayClassName: cilium
+            [...]
+            ---
+            apiVersion: gateway.networking.k8s.io/v1beta1
+            kind: HTTPRoute
+            spec:
+              parentRefs:
+              - name: cilium
+
+
+Review Equivalent Gateway Configuration
+=======================================
+
+You'll find the equivalent final Gateway and HTTPRoute definition in ``http-migration.yaml``.
+
+.. literalinclude:: ../../../../examples/kubernetes/gateway/http-migration.yaml
+
+The above example creates a Gateway named ``cilium`` that listens on port 80 for HTTP traffic.
+Two routes are defined, one for ``/details`` to the ``details`` service, and
+one for ``/`` to the ``productpage`` service.
+
+Deploy the resources and verify that the HTTP requests are routed successfully to the services.
+For more information, consult the Gateway API :ref:`gs_gateway_http`.

Documentation/network/servicemesh/ingress-to-gateway/ingress-to-gateway.rst

@@ -0,0 +1,108 @@
+.. only:: not (epub or latex or html)
+
+    WARNING: You are looking at unreleased Cilium documentation.
+    Please use the official rendered version released here:
+    https://docs.cilium.io
+
+.. _gs_ingress-to-gateway:
+
+*********************************
+Migrating from Ingress to Gateway
+*********************************
+
+The Gateway API is not only the long-term successor to the Ingress API ; it also supports use cases beyond HTTP/HTTPS-based applications.
+
+In this section, we will highlight some of the limitations with Ingress, explain some of the benefits of the Gateway API before explaining 
+some of the options available with migrating from Ingress API to Gateway API.
+
+Ingress API Limitations
+#######################
+
+The development of the Gateway API stemmed from the realization that the Kubernetes Ingress API had some limitations.
+
+- Limited support for advanced routing:
+
+The Ingress API supports basic routing based on path and host rules, but it lacks native support for more advanced routing 
+features such as traffic splitting, header modification, and URL rewriting.
+
+- Limited protocol support:
+
+The Ingress API only supports HTTP and HTTPS traffic, and does not natively support other protocols such as TCP or UDP.
+The specification of Ingress API was simply too limited and not extensible enough. To address these technical limitations, 
+software vendors and developers created vendor-specific annotations to provide these specific capabilities. But using annotations 
+ended up creating inconsistencies from one Ingress Controller to another. This means that, if you wanted to start using a different 
+Ingress Controller over another, you would likely face some conversion issues as annotations tend to be vendor-specific.
+
+- Operational constraints:
+
+Finally, the Ingress API suffers from operational constraints: it simply is not well-suited for multi-team clusters with shared load-balancing infrastructure.
+
+Benefits of Gateway API
+#######################
+
+The Gateway API was designed from the ground up to address the Ingress API limitations. The team behind the Gateway API is a Kubernetes SIG-Network project.
+
+.. note::
+
+    You can find out more information about the project on its `website <https://gateway-api.sigs.k8s.io/>`_.
+
+On the technical front, the Gateway API provides a centralized mechanism for managing and enforcing policies for external traffic, 
+including HTTP routing, TLS termination, traffic splitting/weighting, and header modification.
+
+Native support for these features means annotations are no longer needed to provide support for features that are commonly required
+for ingress traffic patterns. This means that Gateway API resources are more portable from one Gateway API implementation to another.
+
+When customization is required, Gateway API provides several flexible models, including specific extension points to enable diverse 
+traffic patterns. As extensions are added, the Gateway API team will keep looking for common denominators and will promote features 
+to the API conformance to avoid going back to some of the chaos seen with extending Ingress API resources.
+
+Finally, the Gateway API implementation was designed with role-based persona in mind. The Ingress model was based on a model where 
+it was assumed that developers managed and created Ingress and Services resources themselves.
+
+In many of the more complex deployments however, there are various personas involved:
+
+- Infrastructure Provider: the cloud provider (AWS, Azure, GCP) for example
+- Cluster Operator: responsible for the the administration of a cluster
+- Application Developer: responsible for defining application configuration and service composition
+
+By decomposing the Ingress API into several Gateway API objects, personas will be assigned the right access and privileges that their responsibilities require.
+
+For example, application developers in a specific team would be allowed to create Route objects in a specified namespace 
+but would not be able to modify the Gateway configuration or edit Route objects in namespaces other than theirs.
+
+Migration Methods
+#################
+
+There are currently two primary methods to migrate Ingress API resources to Gateway API:
+
+- *manual* - manually creating Gateway API resources based on existing Ingress API resources.
+- *automated*, creating rules using the `ingress2gateway tool <https://github.com/kubernetes-sigs/ingress2gateway>`_. 
+  This project reads Ingress resources from a Kubernetes cluster based on your current Kube Config. It will output YAML for equivalent Gateway API resources to stdout.
+  Note the ``ingress2gateway`` tool remains experimental at this stage.
+
+Ingress Annotations Migration
+#############################
+
+Most Ingress controllers make the use of annotations to provide support for specific features, such as HTTP request manipulation and routing. 
+As highlighted above, the Gateway API model avoids the use of implementation-specific annotations where possible to provide a portable configuration.
+
+Therefore, porting implementation-specific Ingress annotations to a Gateway API resource rarely applies. 
+Instead, the Gateway API provides native support for some of these features, including:
+
+- Request/response manipulation
+- Traffic splitting
+- Header, query parameter, or method-based routing
+
+Examples
+########
+
+Please refer to one of the below examples on how to migrate to 
+Cilium's Gateway API features:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   http-migration
+   tls-migration
+