One of the absolute coolest things you can do in Akka.NET is remotely deploy actors over the internet to other machines. You can literally deploy code somewhere other than the immediate, local process making the call.

And the way this is accomplished is with the Akka.Remote package - it’s the module that adds remoting capabilities to our Akka.NET applications.

When Would I Want to Remotely Deploy an Actor?

There are two common scenarios for when you would want to deploy an actor remotely:

  1. Work distribution - you need to be able to push work onto remote machines using a remote or clustered router. This is exactly what the Cluster.WebCrawler sample does.
  2. Accessing machine-specific resources - if you wanted to gather PerformanceCounter data from an array of remote machines in order to get specific metrics from each machine, remote deployment is an effective tool for accomplishing that.

Outside of these two use cases, it’s far more efficient to contact remote actor systems via ActorSelection and remote IActorRefs than it is to work via remote deployments.

How Do I Deploy an Actor to a Remote System?

After you’ve enabled Akka.Remote inside your Akka.NET application, you it’s pretty easy to remotely deploy an actor over the network.

Check out the video I’ve created below - it’s 23:40 long but it explains all of the details behind remote actor deployments in extensive detail.



The full video transcript is below.

Code Sample

RemoteDeploy sample from the video.

Learn Akka.NET and Akka.Remote

If you think this is cool and want to know how to do this yourself, take some of our Akka.NET training:

  • Beginning Akka.NET: Akka.NET Bootcamp - our popular free, self-directed Akka.NET training that over 1,500 developers have done!
  • Advanced Akka.NET: Petabridge Akka.NET Virtual Training - we offer live virtual training on Akka.Remote, Akka.Cluster, and Akka.NET design patterns.


Hello everybody, my name is Aaron Stannard I am the Chief Technology Officer and Co-Founder of Petabridge, a company that provides Akka.NET services training and support and I’m also one of the co-founder of Akka.NET project. And today we’re going to talk about but I think is one of the absolutely coolest thing that Akka.NET can do, which is the ability to deploy actors remotely over the network. So talk a little bit about Akka.NET its extensibility model. We have those concepts

[0:30] that the we’ve expressed says about the Petabridge at the Home Depot extensibility model and if you’re not from United States the Home Depot’s like the world’s largest harbor store has everything from different types of knobs and handles for doors, to sinks, to paint, to lumber, to gardening supplies you name it. If you want to build a house you can just go and pick the needs you need from home depot and make it work and same idea applies to Akka.NET apps. All you need to build a basic Akka.NET app is the

[1:00] Nuget package and the common language run time. You don’t need anything else to make it work but if you want to integrate with your favorite dependency injection library, your favorite .net logging library or a test a unit testing framework like NUnit or XUnit. Akka.NET has a additional modules that you can use to add those capabilities to your Akka.NET applications, we have a couple dozen different law of extensibility up points within our Akka.NET. And we’re gonna talk about the most powerful

[1:30] modules of all today which is Akka.Remote, when an Akka.Remote does takes all the capabilities that you got in the core in Akka.NET package and then allows them to work transparently over the network, so if you want to do something like communicate with the actors on remote systems so send a message to a remote actor or remote actor selection that exist somewhere else on the network Akka.Remote makes that possible or

[2:00] if you want to deploy an actor onto some process that isn’t the local process making the deployment call, you can do that on Akka.Remote. That’s the focus of today’s video and then the last thing on Akka.Remote allows you to do is to configure and support mobile network transports. So if you want to use the combination of TCP and UDP sockets for whatever reason Akka.Remote makes that possible to. So let’s talk about a little bit of how actually enable and use Akka.Remote

[2:30] within your own apps. The process of enabling Akka.Remote is as simple using as you get, so the first thing you need to do is install the Akka.Remote new get package that’s what to contains all the binary is that there are needed to make this work and within your hoc on configuration when you’re starting up your Akka.NET application, you need to enable the remote actor provider and I’ll show you how to do that in just a moment. The next thing we need to do is enable

[3:00] at least one transport so Akka.Remote wouldn’t be very useful for didn’t have some way of communicating over the network. Then they configure an address for each transport, so you need some IP address and port combination that each of the transports can use and then you can start your actor system and that’s all it really takes to turn on the Akka.Remote, pretty simple. And the configuration details for how you turn it on aren’t so bad either. So one thing your notice is that both the server

[3:30] and the client and the sample, the is set to this fully qualified tight name here. That Akka.Remote the remote actor ref provider. The reason why, this is fully qualified name FQN shorthand for that. Other reason why this is a fully qualified name is because Akka.NET will dynamically load this for at runtime from that Akka.Remote library. So there’s a lot of different extensibility point such as loggers and even network

[4:00] transport Akka.Remote and serialize … where Akka.Remote can load user-defined types and configuration and use those at runtime without needing to need to be linked to them before … That’s how Akka.Remote is enable to provide this remote actor reference provider that the actor system or use. So the remote actor ref provider is basely piece of plumbing that makes all the remote in capabilities work. Next we have, a remote section that defines all transport

[4:30] that were gonna use. So here we using a Helios.TCP transport, now Helios is the socket server that comes in Akka.NET by default, a Helios supports both UDP and TCP sockets it’s, it’s high performance. We don’t have a UDP transport enabled just yet inside Akka.NET, we’ll get that eventually but for the most part 99.99 percent of our users who are using Akka.Remote are fine with TCP. So

[5:00] the first thing, you’ll notice that we do is when you configure the ports for the Helios transport for the server to be fixed number 8081 and we define a port for the client to be 0. Now the reason for that is that the server handles inbound connections from clients therefore the servers address needs to be well known, so the client … will configured to keep reach out to that server and contacted. So the server must have a fixed for now an IP address. The clients

[5:30] on the other hand when we pick port 0 that means the operating system will pick a randomly available free port for them, so that allows us to start multiple clients simultaneously from within Visual Studio or a command line and they can all pile independently connect to the server without having reconfigured that’s why we use port 0 for the client and then we’d issues local host is the IP address for now. So when you enable a remote transport at actually could have an impact on

[6:00] the address and the way it can address a remote actors, so this is what a local actor path looks like using a local address. So we have the default Akka protocol, we have the name for actor system then we have the warpath that represents where particular actor sets on the hierarchy. Without Akka.Remote, the address looks like different, first is that the protocol gets augmented with the scheme of the transport ever using. So the scheme with the TCP transport is

[6:31] stuck TCP the ski of the UDP transport might be .UDP and so forth. Then you have the actor system as some we did before then we also go on at this address to the name it to actor path itself, as this address represents the inbound Endpoint will be configured inside our configuration section. So every time we want to go and contact the server that’s gonna say local host nine thousand and one port or port 8081 whatever port

[7:00] weak it makes was … Every pick port 0 not address will contain the random port that the operating system pick for us. So this remote address is important because in order for us to establish contact between two remote systems. We need to know how we should address those messages, so the way a remote association works is let’s say we have two servers that are running across the network. One server who knows the second service address will send a message and

[7:30] that’s gonna be what will create the association between two systems. Association is a technical term that Akka uses for describing a connection between two remote actor systems and you should look at our internal video on how association are formed if you want more detail on that. The second system will reply back and say “Yes, let’s do that.” So this point, the two systems now share association, they can freely send messages are do remote deployments back and forth to each other no problems.

[8:00] As this stakes is to you, the two ways you can initiate remote connection between systems. … you want one actor system to be able to communicate another, you have to contacted connections are instantiated easily inside Akka.Remote, so the two ways you actually initiate the association process between two remote systems is by either sending a message to be an actor selections has one of those fall remote addresses like I showed you earlier or you try

[8:30] to do a remote deployment onto another system. So we’re gonna focus upon the remote deployment section for the rest of this video. Okay, so let’s talk about remotely deploying actor and what that actually means. So the concepts of deploying an actor is that’s you create an actor instance with configured properties like specified in that deployment section on your … on configuration and … an example of that moment and then once

[9:00] the actor instance that you define has been created so you created a actor a type Foo, once a Foo actors gets initiated and is configured with all buts up properties such as whether or not this actor running under the router and what dispatchers actors using one mailbox is using etc., then you finally get an actor reference to that actor, so the I actor ref class is what we use for holding onto an actor reference. So one of the interesting things that Akka.Remote does

[9:30] is it turns the location of an actor on the network into deployment detail, so where an actor lives is now something that you can configure through … configuration or through procedural code. … example is what remote deployment looks like so say we ever to actor systems again, first actor system contacts the second says, “hey, could you create a foo actor for me.” And the second system does it creates a foo actor

[10:00] and it sends back an actor reference to the first system. So the for system can now communicate that actor as though we’re local actor even though it technically exists over the network on system 2. So got some code and see how this actually work. Okay so I have this Visual Studio open here, so this is a remote deployment sample that I put together and the first thing you wanna point out before we dive into the code is the structure the project.

[10:30] You notice that we have three projects deploy here, this is the actor system that’s going to be doing be deploying over the network. We have shared which defines a to a couple of classes that will look at the moment but this library get share between … and play target and then there’s two point target. This is our server, this is the application that’s going to be deployed onto. So let’s go ahead and take a look at the classes that make up this example. Blow that up

[11:00] and zoom in just a bit alright, so this is the deploy target project, so the first thing we notice is that’s rather than loading the … on configuration from App.Config is doing it right here parsing it from the string, makes the sample were easier to read but were initiating the other actor reference provider like we talked about earlier and were creating a Helios TCP transports on port 8090, this is a well-known port.

[11:30] What isn’t happening here, the answer is that this actor system is in creating any actors at all, its totally blank. Just sitting there not doing anything, and then the next thing you got to look at is our echo actor this … actor class that you’re under the zoom in be here, this is an actor class I defined that just simply takes a message type a low rights who the sender was and the message on the command line and

[12:00] then a sends the message back to the original sender, so does the echoes the message back and the low class preaches march to wrap around the string, then here, we have the remote deploy … this was the actor system that’s gonna be doing the deployment onto deploy target, so we have a actor call a hello actor takes a reference to remote actor and on timer it will go and scheduled itself,

[12:30] to repeatedly send a hello message over the network. So every time we received the say hello message here, were create a new below object and we’re going to hello plus some updated counter value that work for many, so case this actor does. Then here you can also see that we have a pretty at been actor system so we create an actor system called the player, we naval the road actor ref provider than a couple of interesting

[13:00] things happen inside the deployment section, we go and create actor called remote echo and which is about this property remote equals akka.TCP deploy target at local host 8090. Was that mean? More find out in the moment. Know we deploy define a promoting section here and we specify the port 0. That way I can fire up multiple player insists simultaneously, we’ll see what it happens. And then just to show you a couple of different

[13:30] ways are doing a remote acted upon in. I go and take the TCP address for the deployed target and … that an address object here, so I can use it with an procedural code. So first thing you got to notice is that were gonna create NECO actor here and great props for and were go ahead specify the name the remote echo which should correspond to what we’d this fine your … on configuration section here. And then down here,

[14:00] you’ll notice that we have a little bit more code and … great props and we do this with deploy method here. And we do with deploy in scope and a passing a remote scope and the server mode scope has the address that be parsed up for the remote system. And we call this code a remote echo. Okay, those member those name for a moment. And then down here you can see recreates to hello actors that are responsible for talking to the actor references we get back

[14:30] from these two samples here. So we go ahead back in to Visual Studio, we’re gonna start up the sample. All right, let’s go ahead and start both deployer and .the deploy target up. Okay, this is the deploy target on the right and the deployer on the left, now one thing you can notice right away is that the deployed target which had no actors is sitting

[15:00] here printing messages out. Well, what’s up with that and the answer is that we’re able to successfully instantiate an echo actor over the network and the two … two echo actors and two hello actors, and you can see here that the echo actor running on the point target is printing messages from two different actors running on the deployer process. You can see the Akka.TCP slash player local hosts and the this random port number that the OS picked

[15:30] for us, then we see two different actor names BNC showing up here, so we can see the messages are being successfully sent over the network. Now if we go and look at the deployer, we can see a pretty interesting reply back from the little boy target. We see that we’re receiving the messages that we sent echo back to us from an actor this address Akka.TCP slash deploy target at local host 8090 slash remote Akka TCP …

[16:00] these pointing out, is this part of path right here represents the deploy target but after that we have the slash remote will stop here on the actor path and then the rest of the path actually represents our local address information inside this instance on the deployer, so then we see the user name slash users slash remote echo or slash co remote echo for the remote actor to be deployed

[16:30] purely in code. What happens if go and start a second the deployer instance here. Here’s a new deployer for instance and boom we could see some new message is starting to show up here from an actor in a totally different port number this time was because this guy started up and the operating system picked another random port for him. More than this worth in work worth noting here is that this guy are the deploying actors onto this system

[17:00] with the exact name. So the reason why there’s no name collision there at all is the full path the actor includes the address up the system did the deployment on to it so one other thing that’s worth noting. Gonna go ahead shut the process is down here is that is actor remote actor as in remote echo and … echo both have name that’s for a local so what happens if I send it actor selection here, so its system …

[17:30] actor of and will do slash user slash remote echo and then will tell it that hello class the … using so hello hi from selection, so this, this the code like sending a message to a local actor but in reality, this is gonna delivered to that remote

[18:00] actor that deployed over the network, so see what happens here and boom because the very first message you received this from the no sender address a no actual actor we can reply back to here but we can see the address the system that sent it and it said hi selection. Alright so not code sample that we put together you could see how a local actor and everything had makings of a local actor

[18:30] remain able to send a selection to a purely local address and that message got delivered over the network to an actor that was actually running on the Endpoint target machine. So, what actually makes that work under the hood, so were gonna ahead and give you … some the internals that are going on to make this possible. So we have the two actor systems here, the deployer on the left and the point target on the right. So a call comes in to go and creates echo actor

[19:00] on the point target and the props to specify that this actor needs to be created on deployed targets remote address over the network. So the remote actor ref provider creates a remote actor rough that wall map to alive actor that lives on the deploy target system. So we get this remote actor ref back right away and then we serialize the props, the deployment info into a special type of message that

[19:30] we can send over the network and so that’s get handed off to what’s called the Endpoint writer as one of the built-in systems actors, do we talked about our internal video house association work. So the Endpoint writer transmit that the data over the configure transport to the endpoint reader that belongs to the remote actors system and the Endpoint reader will be serialized the props and the deployment information and a special built-in actor inside the road actor ref provider called the RemoteDaemon

[20:00] will go and create that echo actor on the remote system and then from that point onward all messages that sent to the original remote actor reference that we received on the endpoints on the endpoint was deploying the actor will all be delivered to that actor over the network. So this remote actor reference has the appearance of being a local actor even though it really maps to something that exists over the network and this is one of those it’ll instances where

[20:30] you can really see how location transparency can be powerful inside the context of Akka.NET. The ability to go and deployed code remotely over the network and so have it appear local allows us to program are actors and anything that takes an actor reference to not need to make distinction between what is the local and what is remote that details totally handled by the Akka.Remote framework for us. So a couple of important things to know about remote deployment, first

[21:00] is that remote actor names are determined by the system that is doing the deploying. That’s why we’re able to spin up multiple the player instances and not have any name collisions the the name of the actor system and the local address up its binding is what tells it gets factored into the full name of the system that’s being deployed onto. So since address is a unique and since actor names are unique for you know the every local system, if we have forty,

[21:30] you know four years as deploy target, I’ll try deploy the same echo actor name and know the mall collide with each other and the local actor system is gonna know if you try to deploy the same actor twice that it works exactly the same ways if you try to create the same in memory actor twice if you’re using just the normal Akka.NET package, says no different of names are determined by the system do in play. The second is that actor and message types must be present on both deployer

[22:00] and the … the C sharp and or F sharp type up the actor that is being deployed and the types of the arguments are being passed into its props. And the types of messages that is actor receives must be shared between the system doing the deploying another player. That’s why we had that shared middleware library from before. And in the final point as the all constructor arguments for deployed actors must be serializable. Don’t deploy anything that the that needs dependency injection

[22:30] in our needs to a sequel server connection. Our needs access to some resource that can be serialize like a … or a your disposable resource like a performance counter. You’re not going to be a little point in those things over the network but there are strategies to be a little ploy actors with complex requirements over the network to but that’s a subject for a more more advance video. So that’s wraps it up for this particular video and why like to point you

[23:00] to is a few really enjoy this content version burning more or go to our intro of Akka.NET boot camp so to learn our Akka.NET is the address for that. That covers all the Akka.NET basics in teaches you how to build up application using actors. If you are want to learn more about our Akka.Remote or you wanna learn about Akka.Cluster or any others are in advance concepts, we offer professional trainings on the subject we offer a few different times a month. You can go to our training page

[23:30] to get more info on those. Thanks again for watching and please leave any comments you have for us on the comment section, alright, thank you very much.


If you liked this post, you can share it with your followers or follow us on Twitter!
Written by Aaron Stannard on June 1, 2015



Observe and Monitor Your Akka.NET Applications with Phobos

Did you know that Phobos can automatically instrument your Akka.NET applications with OpenTelemetry?

Click here to learn more.