github.com/cilium/cilium@v1.16.2/Documentation/network/servicemesh/ingress-to-gateway/http-migration.rst (about)

     1  .. only:: not (epub or latex or html)
     2  
     3      WARNING: You are looking at unreleased Cilium documentation.
     4      Please use the official rendered version released here:
     5      https://docs.cilium.io
     6  
     7  .. _gs_gateway_http_migration:
     8  
     9  **********************
    10  HTTP Migration Example
    11  **********************
    12  
    13  This example shows you how to migrate an existing Ingress configuration to the equivalent Gateway API resource.
    14  
    15  The Cilium :ref:`gs_ingress_http` serves as the starting Ingress configuration. 
    16  The same approach applies to other controllers, though each Ingress controller configuration varies.
    17  
    18  The example Ingress configuration routes traffic to backend services from the
    19  ``bookinfo`` demo microservices app from the Istio project.
    20  
    21  Review Ingress Configuration
    22  ============================
    23  
    24  You can find the example Ingress definition in ``basic-ingress.yaml``.
    25  
    26  .. literalinclude:: ../../../../examples/kubernetes/servicemesh/basic-ingress.yaml
    27  
    28  This example listens for traffic on port 80, routes requests for the path ``/details`` to the ``details`` service,
    29  and ``/`` to the ``productpage`` service.
    30  
    31  
    32  Create Equivalent Gateway Configuration
    33  =======================================
    34  
    35  To create the equivalent Gateway configuration, consider the following:
    36  
    37  - Entry Point
    38  
    39  The entry point is a combination of an IP address and port through which external clients access the data plane.
    40  
    41  .. tabs::
    42  
    43      .. group-tab:: Ingress
    44          
    45          Every Ingress resource has two implicit entry points -- one for HTTP and the other for HTTPS traffic. 
    46          An Ingress controller provides the entry points. Typically, entry points are either shared by all Ingress resources, or every Ingress resource has dedicated entry points.
    47  
    48          .. code-block:: shell-session
    49  
    50              apiVersion: networking.k8s.io/v1
    51              kind: Ingress
    52              spec:
    53                ingressClassName: cilium
    54  
    55      .. group-tab:: Gateway API
    56  
    57          In the Gateway API, entry points must be explicitly defined in a Gateway resource. 
    58          For example, for the data plane to handle HTTP traffic on port 80, you must define a listener for that traffic. 
    59          Typically, a Gateway implementation provides a dedicated data plane for each Gateway resource.
    60  
    61          .. code-block:: shell-session
    62  
    63              apiVersion: gateway.networking.k8s.io/v1beta1
    64              kind: Gateway
    65              metadata:
    66                name: cilium-gateway
    67              spec:
    68                gatewayClassName: cilium
    69                listeners:
    70                - name: http
    71                  port: 80
    72                  protocol: HTTP
    73  
    74  - Routing Rules
    75  
    76  When using Ingress or Gateway API, routing rules must be defined to attach applications to those entry points.
    77  
    78  .. tabs::
    79  
    80      .. group-tab:: Ingress
    81          
    82          The path-based routing rules are configured in the Ingress resource.
    83  
    84          In the Ingress resource, each hostname has separate routing rules:
    85  
    86          .. code-block:: shell-session
    87  
    88              apiVersion: networking.k8s.io/v1
    89              kind: Ingress
    90              [...]
    91              rules:
    92              - http:
    93                  paths:
    94                  - backend:
    95                      service:
    96                        name: details
    97                        port:
    98                          number: 9080
    99                    path: /details
   100                    pathType: Prefix
   101                  - backend:
   102                      service:
   103                        name: productpage
   104                        port:
   105                          number: 9080
   106                    path: /
   107                    pathType: Prefix
   108  
   109      .. group-tab:: Gateway API
   110  
   111          The routing rules are configured in the HTTPRoute.
   112  
   113          .. code-block:: shell-session
   114  
   115              ---
   116              apiVersion: gateway.networking.k8s.io/v1beta1
   117              kind: HTTPRoute
   118              spec:
   119                parentRefs:
   120                - name: cilium-gateway
   121              rules:
   122              - matches:
   123                - path:
   124                    type: PathPrefix
   125                    value: /
   126                backendRefs:
   127                - name: productpage
   128                  port: 9080
   129              - matches:
   130                - path:
   131                    type: PathPrefix
   132                    value: /details
   133                backendRefs:
   134                - name: details
   135                  port: 9080
   136                
   137  
   138  - Selecting Data Plane to Attach to:
   139  
   140  Both Ingress and Gateway API resources must be explicitly attached to a Dataplane.  
   141  
   142  .. tabs::
   143  
   144      .. group-tab:: Ingress
   145  
   146          An Ingress resource must specify a class that selects which Ingress controller to use. 
   147  
   148          .. code-block:: shell-session
   149  
   150              apiVersion: networking.k8s.io/v1
   151              kind: Ingress
   152              spec:
   153                ingressClassName: cilium
   154  
   155      .. group-tab:: Gateway API
   156  
   157          A Gateway resource must also specify a class: in this example, it is always the ``cilium`` class. 
   158          An HTTPRoute must specify which Gateway (or Gateways) to attach to via a ``parentRef``.
   159  
   160          .. code-block:: shell-session
   161  
   162              apiVersion: gateway.networking.k8s.io/v1beta1
   163              kind: Gateway
   164              metadata:
   165                name: cilium-gateway
   166                namespace: default
   167              spec:
   168                gatewayClassName: cilium
   169              [...]
   170              ---
   171              apiVersion: gateway.networking.k8s.io/v1beta1
   172              kind: HTTPRoute
   173              spec:
   174                parentRefs:
   175                - name: cilium-gateway
   176  
   177  
   178  Review Equivalent Gateway Configuration
   179  =======================================
   180  
   181  You can find the equivalent final Gateway and HTTPRoute definition in ``http-migration.yaml``.
   182  
   183  .. literalinclude:: ../../../../examples/kubernetes/gateway/http-migration.yaml
   184  
   185  The preceding example creates a Gateway named ``cilium-gateway`` that listens on port 80 for HTTP traffic.
   186  Two routes are defined, one for ``/details`` to the ``details`` service, and
   187  one for ``/`` to the ``productpage`` service.
   188  
   189  Deploy the resources and verify that the HTTP requests are routed successfully to the services.
   190  For more information, consult the Gateway API :ref:`gs_gateway_http`.