dlb: add how to use

ci/verify_examples.sh

@@ -11,6 +11,8 @@ WARNINGS=()
 # Sandboxes listed here should be regarded as broken(/untested) until whatever
 # is causing them to flake is resolved!!!
 FLAKY_SANDBOXES=(
+    # no device available in CI
+    dlb
     # https://github.com/envoyproxy/envoy/issues/28542
     double-proxy
     # https://github.com/envoyproxy/envoy/issues/31347

docs/root/configuration/other_features/dlb.rst

@@ -33,7 +33,7 @@ If enabled, the DLB connection balancer will:
 When new connections come, one worker thread will accept it and send it to DLB hardware. DLB hardware
 does balancing then trigger one worker thread to receive via libevent.
 
-Installing DLB
---------------
+Using DLB
+---------
 
-For information on how to build/install and use libdlb see `the getting started guide <https://downloadmirror.intel.com/727424/DLB_Driver_User_Guide.pdf>`_.
+You can see full example in this [doc](https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/dlb.html).

examples/BUILD

@@ -23,6 +23,7 @@ filegroup(
             "opentelemetry/otel-collector-config.yaml",
             "**/*docker-compose*.yaml",
             # Contrib extensions tested over in contrib.
+            "dlb/*.yaml",
             "golang-http/*.yaml",
             "golang-network/*.yaml",
             "mysql/*",
@@ -43,6 +44,7 @@ filegroup(
             "kafka/*.yaml",
         ],
         exclude = [
+            "dlb/*.yaml",
             "**/*docker-compose*.yaml",
         ],
     ),

examples/dlb/dlb_example_config.yaml

@@ -0,0 +1,45 @@
+static_resources:
+  listeners:
+  - address:
+      socket_address:
+        address: 0.0.0.0
+        port_value: 10000
+    connection_balance_config:
+      extend_balance:
+        name: envoy.network.connection_balance.dlb
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.network.connection_balance.dlb.v3alpha.Dlb
+    filter_chains:
+    - filters:
+      - name: envoy.filters.network.http_connection_manager
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+          codec_type: AUTO
+          stat_prefix: ingress_http
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: backend
+              domains:
+              - "*"
+              routes:
+              - match:
+                  prefix: "/"
+                route:
+                  cluster: service1
+          http_filters:
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+  clusters:
+  - name: service1
+    load_assignment:
+      cluster_name: service1
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 12000

examples/dlb/example.rst

@@ -0,0 +1,105 @@
+.. _install_sandboxes_dlb:
+
+DLB
+===
+
+By enabling connection balancer in Envoy you can balance the connections cross the threads and improve performance.
+
+This sandbox provides an example about how to enable DLB connection balanace.
+
+.. note::
+   Please run below command to check your CPU supports DLB:
+
+   .. code-block:: console
+
+   $ lspci -d :2710
+
+   You should get output like below:
+
+   .. code-block:: text
+
+      5a:00.0 Co-processor: Intel Corporation Device 2710
+      6b:00.0 Co-processor: Intel Corporation Device 2710
+      7c:00.0 Co-processor: Intel Corporation Device 2710
+      8d:00.0 Co-processor: Intel Corporation Device 2710
+
+   The number and PCIE address of DLB devices vary from CPU to CPU.
+
+   Also check your kernel version, 5.15+ is good.
+
+Step 1: Install DLB Driver
+**************************
+
+You can download the DLB driver release tarball from the `DLB website <https://www.intel.com/content/www/us/en/download/686372/intel-dynamic-load-balancer.html>`_.
+
+To install it refer to `the getting started guide <https://downloadmirror.intel.com/727424/DLB_Driver_User_Guide.pdf>`_.
+
+Step 2: Run Envoy with DLB connection balanace enabled
+******************************************************
+
+With the example configuration Envoy listens on port 10000 and proxies to an upstream server listening on port 12000.
+
+.. literalinclude:: _include/dlb/dlb_example_config.yaml
+ :language: yaml
+ :lines: 7-11
+ :lineno-start: 7
+ :linenos:
+ :caption: :download:`dlb_example_config.yaml <_include/dlb/dlb_example_config.yaml>`
+
+.. code-block:: console
+
+ $ ./envoy --concurrency 2 -c dlb_example_config.yaml
+
+Step 3: Run the upstream service
+********************************
+
+.. code-block:: console
+
+ $ docker run -d -p 12000:80 nginx
+
+Step 3: Test
+************
+
+Visit the upstream service by Envoy endpoint:
+
+.. code-block:: console
+
+ $ curl localhost:10000
+
+You should get output from Nginx like below:
+
+.. code-block:: text
+
+  <!DOCTYPE html>
+  <html>
+  <head>
+  <title>Welcome to nginx!</title>
+  <style>
+  html { color-scheme: light dark; }
+  body { width: 35em; margin: 0 auto;
+  font-family: Tahoma, Verdana, Arial, sans-serif; }
+  </style>
+  </head>
+  <body>
+  <h1>Welcome to nginx!</h1>
+  <p>If you see this page, the nginx web server is successfully installed and
+  working. Further configuration is required.</p>
+
+  <p>For online documentation and support please refer to
+  <a href="http://nginx.org/">nginx.org</a>.<br/>
+  Commercial support is available at
+  <a href="http://nginx.com/">nginx.com</a>.</p>
+
+  <p><em>Thank you for using nginx.</em></p>
+  </body>
+  </html>
+
+.. seealso::
+   :ref:`DLB connection balanace API <envoy_v3_api_msg_extensions.network.connection_balance.dlb.v3alpha.Dlb>`
+      API and configuration reference for Envoy's DLB connection balanace.
+
+   :ref:`Connection balance configuration <envoy_v3_api_field_config.listener.v3.Listener.connection_balance_config>`
+      Configuration referenc for Envoy's connection balanace.
+
+  `DLB <https://networkbuilders.intel.com/solutionslibrary/queue-management-and-load-balancing-on-intel-architecture>`_
+    The Intel DLB website.