listener: Support for Linux network namespaces (#39517)

This changes the listener to make use of the
`network_namespace_filepath` field of the
`SocketAddress` that specifies the address/port to listen on. When the
field is specified, the
underlying sockets used to listen are created in the network namespace
referenced by the filepath.
This allows the Envoy process to listen for connections from _other_
network namespaces, but to
proxy those connections through the Envoy's network namespace.

### What is a network namespace?
Each Linux network namespace has its own independent network devices, IP
addresses, routing tables,
and firewall rules. This isolation allows multiple processes or
containers to run on the same host
machine with their own distinct network configurations, preventing
conflicts.

### Motivation
Currently, Envoy listeners bind to network interfaces on the host's
default network namespace. In
environments where Envoy needs to operate within a specific, isolated
network namespace (like a
container with a custom network configuration or a mesh sidecar within a
k8s pod), this change
allows a single Envoy process to act like a sidecar for multiple pods.

Since network namespaces are a Linux feature, there is no change for
other OSes.

Risk Level:
Low. Only matters if the field is configured and only on Linux.

Testing:
Unit testing w/ mocks. Direct verification or integration testing
requires privileges.

Docs Changes:
Proto docs updated.

Release Notes:
Done

Platform Specific Features:
Linux, only.

Progress toward issue #38947

---------

Signed-off-by: Tony Allen <txallen@google.com>
Signed-off-by: Tony Allen <tony@allen.gg>

Author: tonya11en

api/envoy/config/core/v3/address.proto

@@ -98,9 +98,18 @@ message SocketAddress {
   // IPv6 space as ``::FFFF:<IPv4-address>``.
   bool ipv4_compat = 6;
 
-  // The Linux network namespace to bind the socket to. If this is set, Envoy will
-  // create the socket in the specified network namespace. Only supported on Linux.
-  // [#not-implemented-hide:]
+  // Filepath that specifies the Linux network namespace this socket will be created in (see ``man 7
+  // network_namespaces``).  If this field is set, Envoy will create the socket in the specified
+  // network namespace.
+  //
+  // .. note::
+  //    Setting this parameter requires Envoy to run with the ``CAP_NET_ADMIN`` capability.
+  //
+  // .. note::
+  //    Currently only used for Listener sockets.
+  //
+  // .. attention::
+  //     Network namespaces are only configurable on Linux. Otherwise, this field has no effect.
   string network_namespace_filepath = 7;
 }
 

changelogs/current.yaml

@@ -160,6 +160,9 @@ new_features:
     Included the asterisk ``*`` in the match pattern when using the * or ** operators in the URL template.
     This behavioral change can be temporarily reverted by setting runtime guard
     ``envoy.reloadable_features.uri_template_match_on_asterisk`` to ``false``.
+- area: socket
+  change: |
+    Added ``network_namespace_filepath`` to ``SocketAddress``. Currently only used by listeners.
 - area: rbac filter
   change: |
     allow listed ``FilterStateInput`` to be used with the xDS matcher in the HTTP RBAC filter.

envoy/api/os_sys_calls.h

@@ -12,8 +12,6 @@
 #include "envoy/common/pure.h"
 #include "envoy/network/address.h"
 
-#include "absl/types/optional.h"
-
 namespace Envoy {
 namespace Api {
 

envoy/api/os_sys_calls_linux.h

@@ -16,6 +16,11 @@ class LinuxOsSysCalls {
 public:
   virtual ~LinuxOsSysCalls() = default;
 
+  /**
+   * @see man 2 setns
+   */
+  virtual SysCallIntResult setns(int fd, int nstype) const PURE;
+
   /**
    * @see sched_getaffinity (man 2 sched_getaffinity)
    */

envoy/network/address.h

@@ -239,6 +239,11 @@ class Instance {
    * @return SocketInterface to be used with the address.
    */
   virtual const Network::SocketInterface& socketInterface() const PURE;
+
+  /**
+   * @return filepath of the network namespace for the address.
+   */
+  virtual absl::optional<std::string> networkNamespace() const PURE;
 };
 
 /*

mobile/library/common/network/synthetic_address_impl.h

@@ -54,6 +54,8 @@ class SyntheticAddressImpl : public Instance {
     return SocketInterfaceSingleton::get();
   }
 
+  absl::optional<std::string> networkNamespace() const override { return absl::nullopt; }
+
 private:
   const std::string address_{"synthetic"};
 };

source/common/api/posix/os_sys_calls_impl_linux.cc

@@ -17,5 +17,10 @@ SysCallIntResult LinuxOsSysCallsImpl::sched_getaffinity(pid_t pid, size_t cpuset
   return {rc, errno};
 }
 
+SysCallIntResult LinuxOsSysCallsImpl::setns(int fd, int nstype) const {
+  const int rc = ::setns(fd, nstype);
+  return {rc, errno};
+}
+
 } // namespace Api
 } // namespace Envoy

source/common/api/posix/os_sys_calls_impl_linux.h

@@ -15,6 +15,7 @@ class LinuxOsSysCallsImpl : public LinuxOsSysCalls {
 public:
   // Api::LinuxOsSysCalls
   SysCallIntResult sched_getaffinity(pid_t pid, size_t cpusetsize, cpu_set_t* mask) override;
+  SysCallIntResult setns(int fd, int nstype) const override;
 };
 
 using LinuxOsSysCallsSingleton = ThreadSafeSingleton<LinuxOsSysCallsImpl>;

source/common/listener_manager/BUILD

@@ -36,6 +36,7 @@ envoy_cc_library(
         "//envoy/server:transport_socket_config_interface",
         "//envoy/server:worker_interface",
         "//source/common/access_log:access_log_lib",
+        "//source/common/api:os_sys_calls_lib",
         "//source/common/common:basic_resource_lib",
         "//source/common/common:empty_string",
         "//source/common/config:utility_lib",

source/common/listener_manager/listener_impl.cc

@@ -1155,15 +1155,17 @@ bool ListenerImpl::hasDuplicatedAddress(const ListenerImpl& other) const {
     return false;
   }
   // For listeners that do not bind or listeners that do not bind to port 0 we must check to make
-  // sure we are not duplicating the address. This avoids ambiguity about which non-binding
-  // listener is used or even worse for the binding to port != 0 and reuse port case multiple
-  // different listeners receiving connections destined for the same port.
+  // sure we are not duplicating the address in the same network namespace. This avoids ambiguity
+  // about which non-binding listener is used or even worse for the binding to port != 0 and reuse
+  // port case multiple different listeners receiving connections destined for the same port.
   for (auto& other_addr : other.addresses()) {
     if (other_addr->ip() == nullptr ||
         (other_addr->ip() != nullptr && (other_addr->ip()->port() != 0 || !bindToPort()))) {
       if (find_if(addresses_.begin(), addresses_.end(),
                   [&other_addr](const Network::Address::InstanceConstSharedPtr& addr) {
-                    return *other_addr == *addr;
+                    const bool same_netns =
+                        addr->networkNamespace() == other_addr->networkNamespace();
+                    return same_netns && *other_addr == *addr;
                   }) != addresses_.end()) {
         return true;
       }