raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

Remote remoting deployment from artery docs (#26342)

Browse source 
* Remote deployment is not recommended and the section is duplicated
from classic remoting
* Move what's new lower down in prep for it becoming the main remoting
page but link to it for users are migration
This commit is contained in:
Christopher Batey 2019-02-13 07:57:34 +00:00 • committed by GitHub
parent 6d25b38e56
commit baf74a4fe6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 130 deletions
Download patch file Download diff file Expand all files Collapse all files

162
akka-docs/src/main/paradox/remoting-artery.md
View file

@ -10,6 +10,8 @@ To use Remoting (codename Artery), you must add the following dependency in your
version=$akka.version$ version=$akka.version$
} }
If migrating from classic remoting see @ref:[what's new in Artery](#what-is-new-in-artery)
## Configuration ## Configuration
To enable remote capabilities in your Akka project you should, at a minimum, add the following changes To enable remote capabilities in your Akka project you should, at a minimum, add the following changes
@ -18,12 +20,12 @@ to your `application.conf` file:
``` ```
akka { akka {
actor { actor {
provider = remote provider = cluster
} }
remote { remote {
artery { artery {
enabled = on enabled = on
transport = aeron-udp transport = aeron-udp # See Selecting a transport below
canonical.hostname = "127.0.0.1" canonical.hostname = "127.0.0.1"
canonical.port = 25520 canonical.port = 25520
} }
@ -33,7 +35,7 @@ akka {
As you can see in the example above there are four things you need to add to get started: As you can see in the example above there are four things you need to add to get started:
* Change provider from `local` to `remote` * Change provider from `local` to `cluster`
* Enable Artery to use it as the remoting implementation * Enable Artery to use it as the remoting implementation
* Add host name - the machine you want to run the actor system on; this host * Add host name - the machine you want to run the actor system on; this host
name is exactly what is passed to remote systems in order to identify this name is exactly what is passed to remote systems in order to identify this
@ -80,29 +82,7 @@ Remoting is not a server-client technology. All systems using remoting can conta
if they possess an `ActorRef` pointing to those system. This means that every system that is remoting enabled if they possess an `ActorRef` pointing to those system. This means that every system that is remoting enabled
acts as a "server" to which arbitrary systems on the same network can connect to. acts as a "server" to which arbitrary systems on the same network can connect to.
## What is new in Artery ## Selecting a transport
Artery is a reimplementation of the old remoting module aimed at improving performance and stability. It is mostly
source compatible with the old implementation and it is a drop-in replacement in many cases. Main features
of Artery compared to the previous implementation:
* Based on [Aeron](https://github.com/real-logic/Aeron) (UDP) and Akka Streams TCP/TLS instead of Netty TCP
* Focused on high-throughput, low-latency communication
* Isolation of internal control messages from user messages improving stability and reducing false failure detection
in case of heavy traffic by using a dedicated subchannel.
* Mostly allocation-free operation
* Support for a separate subchannel for large messages to avoid interference with smaller messages
* Compression of actor paths on the wire to reduce overhead for smaller messages
* Support for faster serialization/deserialization using ByteBuffers directly
* Built-in Flight-Recorder to help debugging implementation issues without polluting users logs with implementation
specific events
* Providing protocol stability across major Akka versions to support rolling updates of large-scale systems
The main incompatible change from the previous implementation that the protocol field of the string representation of an
`ActorRef` is always *akka* instead of the previously used *akka.tcp* or *akka.ssl.tcp*. Configuration properties
are also different.
### Selecting transport
There are three alternatives of which underlying transport to use. It is configured by property There are three alternatives of which underlying transport to use. It is configured by property
`akka.remote.artery.transport` with the possible values: `akka.remote.artery.transport` with the possible values:
@ -112,7 +92,7 @@ There are three alternatives of which underlying transport to use. It is configu
* `tls-tcp` - Same as `tcp` with encryption using @ref:[Akka Streams TLS](stream/stream-io.md#tls) * `tls-tcp` - Same as `tcp` with encryption using @ref:[Akka Streams TLS](stream/stream-io.md#tls)
The Aeron (UDP) transport is a high performance transport and should be used for systems The Aeron (UDP) transport is a high performance transport and should be used for systems
that require high throughput and low latency. It is using more CPU than TCP when the system that require high throughput and low latency. It uses more CPU than TCP when the system
is idle or at low message rates. There is no encryption for Aeron. is idle or at low message rates. There is no encryption for Aeron.
The TCP and TLS transport is implemented using Akka Streams TCP/TLS. This is the choice The TCP and TLS transport is implemented using Akka Streams TCP/TLS. This is the choice
@ -130,6 +110,8 @@ officially supported. If you're on a Big Endian processor, such as Sparc, it is
@@@ @@@
### Canonical address ### Canonical address
In order to remoting to work properly, where each system can send messages to any other system on the same network In order to remoting to work properly, where each system can send messages to any other system on the same network
@ -235,109 +217,6 @@ be delivered just fine.
@@@ @@@
### Creating Actors Remotely
If you want to use the creation functionality in Akka remoting you have to further amend the
`application.conf` file in the following way (only showing deployment section):
```
akka {
actor {
deployment {
/sampleActor {
remote = "akka://sampleActorSystem@127.0.0.1:2553"
}
}
}
}
```
The configuration above instructs Akka to react when an actor with path `/sampleActor` is created, i.e.
using `system.actorOf(Props(...), "sampleActor")`. This specific actor will not be directly instantiated,
but instead the remote daemon of the remote system will be asked to create the actor,
which in this sample corresponds to `sampleActorSystem@127.0.0.1:2553`.
Once you have configured the properties above you would do the following in code:
Scala
: @@snip [RemoteDeploymentDocSpec.scala](/akka-docs/src/test/scala/docs/remoting/RemoteDeploymentDocSpec.scala) { #sample-actor }
Java
: @@snip [RemoteDeploymentDocTest.java](/akka-docs/src/test/java/jdocs/remoting/RemoteDeploymentDocTest.java) { #sample-actor }
The actor class `SampleActor` has to be available to the runtimes using it, i.e. the classloader of the
actor systems has to have a JAR containing the class.
@@@ note
In order to ensure serializability of `Props` when passing constructor
arguments to the actor being created, do not make the factory an inner class:
this will inherently capture a reference to its enclosing object, which in
most cases is not serializable. It is best to create a factory method in the
companion object of the actor’s class.
Serializability of all Props can be tested by setting the configuration item
`akka.actor.serialize-creators=on`. Only Props whose `deploy` has
`LocalScope` are exempt from this check.
@@@
You can use asterisks as wildcard matches for the actor paths, so you could specify:
`/*/sampleActor` and that would match all `sampleActor` on that level in the hierarchy.
You can also use wildcard in the last position to match all actors at a certain level:
`/someParent/*`. Non-wildcard matches always have higher priority to match than wildcards, so:
`/foo/bar` is considered **more specific** than `/foo/*` and only the highest priority match is used.
Please note that it **cannot** be used to partially match section, like this: `/foo*/bar`, `/f*o/bar` etc.
### Programmatic Remote Deployment
To allow dynamically deployed systems, it is also possible to include
deployment configuration in the `Props` which are used to create an
actor: this information is the equivalent of a deployment section from the
configuration file, and if both are given, the external configuration takes
precedence.
With these imports:
Scala
: @@snip [RemoteDeploymentDocSpec.scala](/akka-docs/src/test/scala/docs/remoting/RemoteDeploymentDocSpec.scala) { #import }
Java
: @@snip [RemoteDeploymentDocTest.java](/akka-docs/src/test/java/jdocs/remoting/RemoteDeploymentDocTest.java) { #import }
and a remote address like this:
Scala
: @@snip [RemoteDeploymentDocSpec.scala](/akka-docs/src/test/scala/docs/remoting/RemoteDeploymentDocSpec.scala) { #make-address-artery }
Java
: @@snip [RemoteDeploymentDocTest.java](/akka-docs/src/test/java/jdocs/remoting/RemoteDeploymentDocTest.java) { #make-address-artery }
you can advise the system to create a child on that remote node like so:
Scala
: @@snip [RemoteDeploymentDocSpec.scala](/akka-docs/src/test/scala/docs/remoting/RemoteDeploymentDocSpec.scala) { #deploy }
Java
: @@snip [RemoteDeploymentDocTest.java](/akka-docs/src/test/java/jdocs/remoting/RemoteDeploymentDocTest.java) { #deploy }
### Remote deployment whitelist
As remote deployment can potentially be abused by both users and even attackers a whitelist feature
is available to guard the ActorSystem from deploying unexpected actors. Please note that remote deployment
is *not* remote code loading, the Actors class to be deployed onto a remote system needs to be present on that
remote system. This still however may pose a security risk, and one may want to restrict remote deployment to
only a specific set of known actors by enabling the whitelist feature.
To enable remote deployment whitelisting set the `akka.remote.deployment.enable-whitelist` value to `on`.
The list of allowed classes has to be configured on the "remote" system, in other words on the system onto which
others will be attempting to remote deploy Actors. That system, locally, knows best which Actors it should or
should not allow others to remote deploy onto it. The full settings section may for example look like this:
@@snip [RemoteDeploymentWhitelistSpec.scala](/akka-remote/src/test/scala/akka/remote/RemoteDeploymentWhitelistSpec.scala) { #whitelist-config }
Actor classes not included in the whitelist will not be allowed to be remote deployed onto this system.
## Remote Security ## Remote Security
An `ActorSystem` should not be exposed via Akka Remote (Artery) over plain Aeron/UDP or TCP to an untrusted An `ActorSystem` should not be exposed via Akka Remote (Artery) over plain Aeron/UDP or TCP to an untrusted
@ -706,6 +585,29 @@ This configuration setting will send messages to the defined remote actor paths.
It requires that you create the destination actors on the remote nodes with matching paths. It requires that you create the destination actors on the remote nodes with matching paths.
That is not done by the router. That is not done by the router.
## What is new in Artery
Artery is a reimplementation of the old remoting module aimed at improving performance and stability. It is mostly
source compatible with the old implementation and it is a drop-in replacement in many cases. Main features
of Artery compared to the previous implementation:
* Based on [Aeron](https://github.com/real-logic/Aeron) (UDP) and Akka Streams TCP/TLS instead of Netty TCP
* Focused on high-throughput, low-latency communication
* Isolation of internal control messages from user messages improving stability and reducing false failure detection
in case of heavy traffic by using a dedicated subchannel.
* Mostly allocation-free operation
* Support for a separate subchannel for large messages to avoid interference with smaller messages
* Compression of actor paths on the wire to reduce overhead for smaller messages
* Support for faster serialization/deserialization using ByteBuffers directly
* Built-in Flight-Recorder to help debugging implementation issues without polluting users logs with implementation
specific events
* Providing protocol stability across major Akka versions to support rolling updates of large-scale systems
The main incompatible change from the previous implementation that the protocol field of the string representation of an
`ActorRef` is always *akka* instead of the previously used *akka.tcp* or *akka.ssl.tcp*. Configuration properties
are also different.
## Performance tuning ## Performance tuning
### Lanes ### Lanes