Replace ClusterRouterGroup/Pool "use-role" with "use-role-set" #23496

akka-docs/src/main/paradox/scala/cluster-metrics.md

@@ -185,7 +185,7 @@ akka.actor.deployment {
     routees.paths = ["/user/factorialBackend"]
     cluster {
       enabled = on
-      use-role = backend
+      use-roles = ["backend"]
       allow-local-routees = off
     }
   }

akka-docs/src/main/paradox/scala/cluster-usage.md

@@ -606,7 +606,7 @@ akka.actor.deployment {
       cluster {
         enabled = on
         allow-local-routees = on
-        use-role = compute
+        use-roles = ["compute"]
       }
     }
 }
@@ -622,7 +622,7 @@ the router will try to use them as soon as the member status is changed to 'Up'.
 The actor paths without address information that are defined in `routees.paths` are used for selecting the
 actors to which the messages will be forwarded to by the router.
 Messages will be forwarded to the routees using @ref:[ActorSelection](actors.md#actorselection), so the same delivery semantics should be expected.
-It is possible to limit the lookup of routees to member nodes tagged with a certain role by specifying `use-role`.
+It is possible to limit the lookup of routees to member nodes tagged with a particular set of roles by specifying `use-roles`.
 
 `max-total-nr-of-instances` defines total number of routees in the cluster. By default `max-total-nr-of-instances`
 is set to a high value (10000) that will result in new routees added to the router when nodes join the cluster.
@@ -693,7 +693,7 @@ akka.actor.deployment {
     cluster {
       enabled = on
       allow-local-routees = on
-      use-role = compute
+      use-roles = ["compute"]
     }
   }
 }
@@ -722,14 +722,14 @@ akka.actor.deployment {
         enabled = on
         max-nr-of-instances-per-node = 3
         allow-local-routees = on
-        use-role = compute
+        use-roles = ["compute"]
       }
     }
 }
 ```
 
-It is possible to limit the deployment of routees to member nodes tagged with a certain role by
-specifying `use-role`.
+It is possible to limit the deployment of routees to member nodes tagged with a particular set of roles by
+specifying `use-roles`.
 
 `max-total-nr-of-instances` defines total number of routees in the cluster, but the number of routees
 per node, `max-nr-of-instances-per-node`, will not be exceeded. By default `max-total-nr-of-instances`
@@ -797,7 +797,7 @@ akka.actor.deployment {
       enabled = on
       max-nr-of-instances-per-node = 3
       allow-local-routees = on
-      use-role = compute
+      use-roles = ["compute"]
     }
   }
 }

akka-docs/src/main/paradox/scala/project/migration-guide-2.4.x-2.5.x.md

@@ -420,6 +420,14 @@ and here is a summary of things to consider.
  * [mig25_weaklyup](#mig25-weaklyup)
  * [mig25_sharding_store](#mig25-sharding-store)
  * [mig25_mutual](#mig25-mutual)
+ 
+#### Limit lookup of routees to nodes tagged with multiple roles
+
+Starting with 2.5.4, cluster routing supports delivering messages to routees tagged with all specified roles
+using `use-roles` (instead of `use-role` in previous versions). When doing rolling upgrades and using this new feature,
+it is important to first upgrade the existing nodes to the latest version of Akka
+and then start using multiple roles in a separate rolling upgrade. Otherwise, if a new node sends a message 
+with the restriction `use-roles = ["a", "b"]`, that will only require the "a" role on old nodes.
 
 ### Coordinated Shutdown
 

akka-docs/src/test/java/jdocs/cluster/FactorialFrontend.java

@@ -2,6 +2,8 @@ package jdocs.cluster;
 
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
 import java.util.concurrent.TimeUnit;
 
 import akka.actor.Props;
@@ -77,12 +79,12 @@ abstract class FactorialFrontend2 extends AbstractActor {
   int totalInstances = 100;
   Iterable<String> routeesPaths = Arrays.asList("/user/factorialBackend", "");
   boolean allowLocalRoutees = true;
-  String useRole = "backend";
+  Set<String> useRoles = new HashSet<>(Arrays.asList("backend"));
   ActorRef backend = getContext().actorOf(
     new ClusterRouterGroup(new AdaptiveLoadBalancingGroup(
       HeapMetricsSelector.getInstance(), Collections.<String> emptyList()),
         new ClusterRouterGroupSettings(totalInstances, routeesPaths,
-          allowLocalRoutees, useRole)).props(), "factorialBackendRouter2");
+          allowLocalRoutees, useRoles)).props(), "factorialBackendRouter2");
 
   //#router-lookup-in-code
 }
@@ -93,12 +95,12 @@ abstract class FactorialFrontend3 extends AbstractActor {
   int totalInstances = 100;
   int maxInstancesPerNode = 3;
   boolean allowLocalRoutees = false;
-  String useRole = "backend";
+  Set<String> useRoles = new HashSet<>(Arrays.asList("backend"));
   ActorRef backend = getContext().actorOf(
     new ClusterRouterPool(new AdaptiveLoadBalancingPool(
       SystemLoadAverageMetricsSelector.getInstance(), 0),
         new ClusterRouterPoolSettings(totalInstances, maxInstancesPerNode,
-          allowLocalRoutees, useRole)).props(Props
+          allowLocalRoutees, useRoles)).props(Props
             .create(FactorialBackend.class)), "factorialBackendRouter3");
   //#router-deploy-in-code
 }

akka-docs/src/test/java/jdocs/cluster/StatsService.java

@@ -13,7 +13,10 @@ import akka.actor.AbstractActor;
 import akka.routing.ConsistentHashingRouter.ConsistentHashableEnvelope;
 import akka.routing.FromConfig;
 
+import java.util.Arrays;
 import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
 
 //#service
 public class StatsService extends AbstractActor {
@@ -55,11 +58,11 @@ abstract class StatsService2 extends AbstractActor {
   Iterable<String> routeesPaths = Collections
     .singletonList("/user/statsWorker");
   boolean allowLocalRoutees = true;
-  String useRole = "compute";
+  Set<String> useRoles = new HashSet<>(Arrays.asList("compute"));
   ActorRef workerRouter = getContext().actorOf(
     new ClusterRouterGroup(new ConsistentHashingGroup(routeesPaths),
       new ClusterRouterGroupSettings(totalInstances, routeesPaths,
-        allowLocalRoutees, useRole)).props(), "workerRouter2");
+        allowLocalRoutees, useRoles)).props(), "workerRouter2");
   //#router-lookup-in-code
 }
 
@@ -69,11 +72,11 @@ abstract class StatsService3 extends AbstractActor {
   int totalInstances = 100;
   int maxInstancesPerNode = 3;
   boolean allowLocalRoutees = false;
-  String useRole = "compute";
+  Set<String> useRoles = new HashSet<>(Arrays.asList("compute"));
   ActorRef workerRouter = getContext().actorOf(
     new ClusterRouterPool(new ConsistentHashingPool(0),
       new ClusterRouterPoolSettings(totalInstances, maxInstancesPerNode,
-        allowLocalRoutees, useRole)).props(Props
+        allowLocalRoutees, useRoles)).props(Props
           .create(StatsWorker.class)), "workerRouter3");
   //#router-deploy-in-code
 }

akka-docs/src/test/scala/docs/cluster/FactorialFrontend.scala

@@ -78,7 +78,7 @@ abstract class FactorialFrontend2 extends Actor {
       AdaptiveLoadBalancingGroup(HeapMetricsSelector),
       ClusterRouterGroupSettings(
         totalInstances = 100, routeesPaths = List("/user/factorialBackend"),
-        allowLocalRoutees = true, useRole = Some("backend"))).props(),
+        allowLocalRoutees = true, useRoles = Set("backend"))).props(),
     name = "factorialBackendRouter2")
 
   //#router-lookup-in-code
@@ -96,7 +96,7 @@ abstract class FactorialFrontend3 extends Actor {
     ClusterRouterPool(AdaptiveLoadBalancingPool(
       SystemLoadAverageMetricsSelector), ClusterRouterPoolSettings(
       totalInstances = 100, maxInstancesPerNode = 3,
-      allowLocalRoutees = false, useRole = Some("backend"))).props(Props[FactorialBackend]),
+      allowLocalRoutees = false, useRoles = Set("backend"))).props(Props[FactorialBackend]),
     name = "factorialBackendRouter3")
   //#router-deploy-in-code
 }