=doc #18163 More visible docs about NAT support

akka-docs/rst/general/remoting.rst

@@ -70,23 +70,13 @@ The consequence of these decisions is that it is not possible to safely create
 pure client-server setups with predefined roles (violates assumption 2).
 For client-server setups it is better to use HTTP or Akka I/O.
 
-Using setups involving Network Address Translation, Load Balancers or Docker
+**Important**: Using setups involving Network Address Translation, Load Balancers or Docker
 containers violates assumption 1, unless additional steps are taken in the
 network configuration to allow symmetric communication between involved systems.
 In such situations Akka can be configured to bind to a different network
-address than the one used for establishing connections between Akka nodes::
+address than the one used for establishing connections between Akka nodes.
+See :ref:`remote-configuration-nat`.
 
-  akka {
-    remote {
-      netty.tcp {
-        hostname = my.domain.com      # external (logical) hostname
-        port = 8000                   # external (logical) port
-
-        bind-hostname = local.address # internal (bind) hostname
-        bind-port = 2552              # internal (bind) port
-      }
-   }
-  }
 
 Marking Points for Scaling Up with Routers
 ------------------------------------------

akka-docs/rst/java/cluster-usage.rst

@@ -34,6 +34,10 @@ To enable cluster capabilities in your Akka project you should, at a minimum, ad
 settings, but with ``akka.cluster.ClusterActorRefProvider``.
 The ``akka.cluster.seed-nodes`` should normally also be added to your ``application.conf`` file.
 
+.. note::
+  If you are using Docker or the nodes for some other reason have separate internal and external ip addresses
+  you must configure remoting according to :ref:`remote-configuration-nat-java`
+
 The seed nodes are configured contact points for initial, automatic, join of the cluster.
 
 Note that if you are going to start the nodes on different machines you need to specify the

akka-docs/rst/java/remoting.rst

@@ -469,3 +469,27 @@ There are lots of configuration properties that are related to remoting in Akka.
    best done by using something like the following:
 
    .. includecode:: code/docs/remoting/RemoteDeploymentDocTest.java#programmatic
+
+.. _remote-configuration-nat-java:
+
+Remote configuration for NAT and Docker
+---------------------------------------
+
+In setups involving Network Address Translation (NAT), Load Balancers or Docker
+containers the hostname and port pair that akka binds to will be different than the "logical"
+host name and port pair that is used to connect to the system from the outside. This requires
+special configuration that sets both the logical and the bind pairs for remoting.
+
+.. code-block:: ruby
+
+  akka {
+    remote {
+      netty.tcp {
+        hostname = my.domain.com      # external (logical) hostname
+        port = 8000                   # external (logical) port
+
+        bind-hostname = local.address # internal (bind) hostname
+        bind-port = 2552              # internal (bind) port
+      }
+   }
+  }

akka-docs/rst/scala/cluster-usage.rst

@@ -28,6 +28,10 @@ To enable cluster capabilities in your Akka project you should, at a minimum, ad
 settings, but with ``akka.cluster.ClusterActorRefProvider``.
 The ``akka.cluster.seed-nodes`` should normally also be added to your ``application.conf`` file.
 
+.. note::
+  If you are using Docker or the nodes for some other reason have separate internal and external ip addresses
+  you must configure remoting according to :ref:`remote-configuration-nat`
+
 The seed nodes are configured contact points for initial, automatic, join of the cluster.
 
 Note that if you are going to start the nodes on different machines you need to specify the

akka-docs/rst/scala/remoting.rst

@@ -13,7 +13,7 @@ For an introduction of remoting capabilities of Akka please see :ref:`remoting`.
   particular Akka Remoting does not work transparently with Network Address Translation,
   Load Balancers, or in Docker containers. For symmetric communication in these situations
   network and/or Akka configuration will have to be changed as described in
-  :ref:`symmetric-communication`.
+  :ref:`remote-configuration-nat`.
 
 Preparing your ActorSystem for Remoting
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -474,3 +474,27 @@ There are lots of configuration properties that are related to remoting in Akka.
 
    .. includecode:: ../java/code/docs/remoting/RemoteDeploymentDocTest.java#programmatic
 
+
+.. _remote-configuration-nat:
+
+Remote configuration for NAT and Docker
+---------------------------------------
+
+In setups involving Network Address Translation (NAT), Load Balancers or Docker
+containers the hostname and port pair that akka binds to will be different than the "logical"
+host name and port pair that is used to connect to the system from the outside. This requires
+special configuration that sets both the logical and the bind pairs for remoting.
+
+.. code-block:: ruby
+
+  akka {
+    remote {
+      netty.tcp {
+        hostname = my.domain.com      # external (logical) hostname
+        port = 8000                   # external (logical) port
+
+        bind-hostname = local.address # internal (bind) hostname
+        bind-port = 2552              # internal (bind) port
+      }
+   }
+  }