Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Member Roles doc #5742

Merged
merged 23 commits into from
Mar 24, 2022
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions docs/articles/clustering/member-roles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
---
uid: member-roles
title: Member Roles
---

# Member Roles

![cluster roles](/images/cluster-roles.png)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this image should probably be moved into a "cluster" sub folder, rather than the root images folder. Don't want to clutter that up.


A cluster can have multiple Akka.NET applications in it, "roles" help to distinguish different Akka.NET applications within a cluster!
Not all Akka.NET applications in a cluster need to perform the same function. For example, there might be one sub-set which runs the web front-end, one which runs the data access layer and one for the number-crunching.
Choosing which actors to start on each node, for example cluster-aware routers, can take member roles into account to achieve this distribution of responsibilities.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something needs to be said about usage of roles being a best practice. There isn't a good reason not to do it. Just come out and say this along the following lines:

  1. Roles make it very easy to direct traffic to the right areas in your cluster;
  2. Even if you only have a single type of node in your cluster, you should still use roles for it so you can leverage this infrastructure as your cluster expands in the future; and
  3. They add zero overhead in any conceivable way.


# How to Use Role Information in Akka.NET
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"How to Use Roles"


The member roles are defined in the configuration property named `akka.cluster.roles` and typically defined in the start script as a system property or environment variable.:

```hocon
akka {
cluster {
roles = ["backend"]
}
}
```
# Programming Against Akka.Cluster Events
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Using Roles Within Your Cluster"


The roles are part of the membership information in `MemberEvent` that you can subscribe to. The roles of the local cluster member are available from the `SelfMember` and that can be used for conditionally starting certain actors:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

## How to Use Role Information in Akka.NET

### Programming Against Akka.Cluster Events

{rest of your language here}

### Akka.Cluster.Sharding

{example}

### `DistributedPubSub`

{example}

### `DData`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ClusterSingleton would be good too.


```csharp
var selfMember = Cluster.Get(_actorSystem).SelfMember;
if (selfMember.HasRole("backend"))
{
context.ActorOf(Backend.Prop(), "back");
}
else if (selfMember.HasRole("front"))
{
context.ActorOf(Frontend.Prop(), "front");
}
```

# Akka.Cluster.Sharding
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should really be H2, not H1 - same for all of these


Specifies that entities runs on cluster nodes with a specific role. If the role is not specified (or empty) all nodes in the cluster are used.

```hocon
akka {
cluster {
roles = ["worker", "notifier", "credit", "storage"]
sharding {
role = "worker"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And what does this do for Akka.Cluster.Sharding?

}
}
}
```

```csharp
var sharding = ClusterSharding.Get(system);
var shardRegion = await sharding.StartAsync(
typeName: "customer",
entityPropsFactory: e => Props.Create(() => new Customer(e)),
settings: ClusterShardingSettings.Create(system).WithRole("worker"),
messageExtractor: new MessageExtractor(10));

```

# `DistributedPubSub`

Start the mediator on members tagged with this role. All members are used if undefined or empty.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mediator will send messages to all nodes tagged with this role, otherwise all members will receive Mediator gossip.


```hocon
akka {
cluster {
roles = ["worker", "notifier", "credit", "storage"]
pub-sub {
role = "notifier"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And what does this do for DistributedPubSub?

}
}
}
```

# `DData`

Replicas are running on members tagged with this role. All members are used if undefined or empty

```hocon
akka {
cluster {
roles = ["worker", "notifier", "credit", "storage"]
distributed-data {
role = "storage"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And what does this do for DData?

}
}
}
```

# `ClusterSingleton`

Singleton among the nodes tagged with specified role. If the role is not specified it's a singleton among all nodes in the cluster.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Specifies which nodes might host a specific singleton - if the role is not specified than any node can, in theory, host a singleton.


```hocon
akka {
cluster {
roles = ["worker", "notifier", "credit", "storage"]
singleton {
role = "credit"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And what does this mean for Cluster Singleton?

}
}
}
```

# Putting It All Together

From the above, you can see that it is possible to have different .NET applications (or actors) in a cluster all performing different function:

```hocon
akka {
cluster {
roles = ["worker", "notifier", "credit", "storage"]
singleton {
role = "credit"
}
distributed-data {
role = "storage"
}
pub-sub {
role = "notifier"
}
sharding {
role = "worker"
}
}

```
4 changes: 3 additions & 1 deletion docs/articles/clustering/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,6 @@
- name: Distributed Data
href: distributed-data.md
- name: Split Brain Resolver
href: split-brain-resolver.md
href: split-brain-resolver.md
- name: Member Roles
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this much closer to the top - as this is a critical, fundamental concept to clustering.

Also, link to this page from the cluster overview early on.

href: member-roles.md
Binary file added docs/images/cluster-roles.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.