Releases: akkadotnet/Akka.Hosting
Akka.Hosting 1.5.0
Version 1.5.0 is the RTM release of Akka.Hosting and Akka.NET v1.5.0 RTM integration.
Full changes
• Update Akka.NET to 1.5.0
• Fix missing cluster configuration on certain edge cases
• Add new Cluster.Sharding RememberEntitiesStore
• Add Cluster.Sharding journal migration adapter convenience method
• Add LogMessageFormatter formatter support to logging
Upgrading From v1.4 To v1.5
As noted in the upgrade advisories%2C there was some major changes inside Akka.NET that directly affects Akka.Hosting. To upgrade from v1.4 to v1.5%2C please watch our video here covering this process.
1.5.0-beta6
1.5.0-beta4
Version 1.5.0-beta4 integrates Akka.NET v1.5 into Akka.Hosting
• Update Akka.NET to 1.5.0-beta4
Upgrading From v1.4 To v1.5
As noted in the upgrade advisories%2C there was a major change in Akka.Cluster.Sharding state storage. These notes contains the same documentation%2C but tailored for Akka.Hosting users
The recommended settings for maximum ease-of-use for Akka.Cluster.Sharding in new applications going forward will be:
var options = new ShardOptions
{
StateStoreMode = StateStoreMode.DData%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced
}
You will need to set these options manually because the default settings are set for backward compatibility.
Migrating to New Sharding Storage From Akka.Persistence
NOTE
This section applies only to users who were using StateStoreMode = StateStoreMode.Persistence.
Switching over to using RememberEntitiesStore = RememberEntitiesStore.Eventsourced will cause an initial migration of data from the ShardCoordinator's journal into separate event journals going forward.
Upgrading to Akka.NET v1.5 will *cause an irreversible migration of Akka.Cluster.Sharding data• for users who were previously running StateStoreMode = StateStoreMode.Persistence%2C so follow the steps below carefully:
Step 1 • Upgrade to Akka.NET v1.5 With New Options Setup
Update your Akka.Cluster.Sharding options to look like the following (adjust as necessary for your custom settings):
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
// If you don't run Akka.Cluster.Sharding with RememberEntities = true%2C
// then set this to false
RememberEntities = true%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
StateStoreMode = StateStoreMode.Persistence%2C
//fail if upgrade doesn't succeed
FailOnInvalidEntityStateTransition = true
}
// Modify these two options to suit your application%2C SqlServer used
// only as an illustration
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion<UserActionsEntity>(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
// shardOptions is being used here
shardOptions)%3B
// Add the Akka.Cluster.Sharding migration journal event adapter
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
// you can also declare the adapter by referencing the journal ID directly
builder.WithClusterShardingJournalMigrationAdapter("akka.persistence.journal.sql-server")%3B
})
```
With these HOCON settings in-place the following will happen:
1. The old PersitentShardCoordinator state will be broken up • Remember entities data will be distributed to each of the PersistentShard actors%2C who will now use the new RememberEntitiesStore = RememberEntitiesStore.Eventsourced setting going forward%3B
2. Old Akka.Cluster.Sharding.ShardCoordinator.IDomainEvent events will be upgraded to a new storage format via the injected Akka.Persistence event adapter%3B and
3. The PersistentShardCoordinator will migrate its journal to the new format as well.
##### Step 2 • Migrating Away From Persistence to DData
Once your cluster has successfully booted up with these settings%2C you can now optionally move to using distributed data to store sharding state by changing StateStoreMode = StateStoreMode.DData and deploying a second time:
```csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
// Change this line of code
StateStoreMode = StateStoreMode.DData%2C
FailOnInvalidEntityStateTransition = true
}%3B
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion<UserActionsEntity>(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
shardOptions)%3B
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})```
Now you'll be running Akka.Cluster.Sharding with the recommended settings.
#### Migrating to New Sharding Storage From Akka.DistributedData
The migration process onto Akka.NET v1.5's new Cluster.Sharding storage system is less involved for users who were already using StateStoreMode = StateStoreMode.DData. All these users need to do is change the RememberEntitiesStore option to RememberEntitiesStore.Eventsourced
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true%2C
// Use this option setting
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
StateStoreMode = StateStoreMode.DData%2C
FailOnInvalidEntityStateTransition = true
}%3B
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion<UserActionsEntity>(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
shardOptions)%3B
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})
1.5.0-beta3
Version 1.5.0-beta3 integrates Akka.NET v1.5 into Akka.Hosting
• Update Akka.NET to 1.5.0-beta3
Upgrading From v1.4 To v1.5
As noted in the upgrade advisories%2C there was a major change in Akka.Cluster.Sharding state storage. These notes contains the same documentation%2C but tailored for Akka.Hosting users
The recommended settings for maximum ease-of-use for Akka.Cluster.Sharding in new applications going forward will be:
csharp
var options = new ShardOptions
{
StateStoreMode = StateStoreMode.DData%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced
}%3B
You will need to set these options manually because the default settings are set for backward compatibility.
Migrating to New Sharding Storage From Akka.Persistence
NOTE
This section applies only to users who were using StateStoreMode = StateStoreMode.Persistence.
Switching over to using RememberEntitiesStore = RememberEntitiesStore.Eventsourced will cause an initial migration of data from the ShardCoordinator's journal into separate event journals going forward.
Upgrading to Akka.NET v1.5 will *cause an irreversible migration of Akka.Cluster.Sharding data• for users who were previously running StateStoreMode = StateStoreMode.Persistence%2C so follow the steps below carefully:
Step 1 • Upgrade to Akka.NET v1.5 With New Options Setup
Update your Akka.Cluster.Sharding options to look like the following (adjust as necessary for your custom settings):
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
// If you don't run Akka.Cluster.Sharding with RememberEntities = true%2C
// then set this to false
RememberEntities = true%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
StateStoreMode = StateStoreMode.Persistence%2C
//fail if upgrade doesn't succeed
FailOnInvalidEntityStateTransition = true
}%3B
// Modify these two options to suit your application%2C SqlServer used
// only as an illustration
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
// shardOptions is being used here
shardOptions)%3B
// Add the Akka.Cluster.Sharding migration journal event adapter
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
// you can also declare the adapter by referencing the journal ID directly
builder.WithClusterShardingJournalMigrationAdapter("akka.persistence.journal.sql-server")%3B
})
With these HOCON settings in-place the following will happen:
- The old PersitentShardCoordinator state will be broken up • Remember entities data will be distributed to each of the PersistentShard actors%2C who will now use the new RememberEntitiesStore = RememberEntitiesStore.Eventsourced setting going forward%3B
- Old Akka.Cluster.Sharding.ShardCoordinator.IDomainEvent events will be upgraded to a new storage format via the injected Akka.Persistence event adapter%3B and
- The PersistentShardCoordinator will migrate its journal to the new format as well.
Step 2 • Migrating Away From Persistence to DData
Once your cluster has successfully booted up with these settings%2C you can now optionally move to using distributed data to store sharding state by changing StateStoreMode = StateStoreMode.DData and deploying a second time:
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
// Change this line of code
StateStoreMode = StateStoreMode.DData%2C
FailOnInvalidEntityStateTransition = true
}%3B
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
shardOptions)%3B
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})
Now you'll be running Akka.Cluster.Sharding with the recommended settings.
Migrating to New Sharding Storage From Akka.DistributedData
The migration process onto Akka.NET v1.5's new Cluster.Sharding storage system is less involved for users who were already using StateStoreMode = StateStoreMode.DData. All these users need to do is change the RememberEntitiesStore option to RememberEntitiesStore.Eventsourced
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true%2C
// Use this option setting
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
StateStoreMode = StateStoreMode.DData%2C
FailOnInvalidEntityStateTransition = true
}%3B
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
shardOptions)%3B
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})
Akka.Hosting v1.5.0-alpha4
[1.5.0-alpha4] / 17 February 2023
Version 1.5.0-alpha4 integrates Akka.NET v1.5 into Akka.Hosting
- Implement new cluster sharding options
- Add cluster sharding migration journal event adapter extension method
- Update Akka.NET to 1.5.0-alpha4
Upgrading From v1.4 To v1.5
As noted in the upgrade advisories, there was a major change in Akka.Cluster.Sharding state storage. These notes contains the same documentation, but tailored for Akka.Hosting
users
The recommended settings for maximum ease-of-use for Akka.Cluster.Sharding in new applications going forward will be:
var options = new ShardOptions
{
StateStoreMode = StateStoreMode.DData,
RememberEntitiesStore = RememberEntitiesStore.Eventsourced
};
You will need to set these options manually because the default settings are set for backward compatibility.
Migrating to New Sharding Storage From Akka.Persistence
NOTE
This section applies only to users who were using
StateStoreMode = StateStoreMode.Persistence
.
Switching over to using RememberEntitiesStore = RememberEntitiesStore.Eventsourced
will cause an initial migration of data from the ShardCoordinator
's journal into separate event journals going forward.
Upgrading to Akka.NET v1.5 will cause an irreversible migration of Akka.Cluster.Sharding data for users who were previously running StateStoreMode = StateStoreMode.Persistence
, so follow the steps below carefully:
Step 1 - Upgrade to Akka.NET v1.5 With New Options Setup
Update your Akka.Cluster.Sharding options to look like the following (adjust as necessary for your custom settings):
hostBuilder.Services.AddAkka("MyActorSystem", builder =>
{
var shardOptions = new ShardOptions
{
// If you don't run Akka.Cluster.Sharding with `RememberEntities = true`,
// then set this to false
RememberEntities = true,
RememberEntitiesStore = RememberEntitiesStore.Eventsourced,
StateStoreMode = StateStoreMode.Persistence,
//fail if upgrade doesn't succeed
FailOnInvalidEntityStateTransition = true
};
// Modify these two options to suit your application, SqlServer used
// only as an illustration
var journalOptions = new SqlServerJournalOptions();
var snapshotOptions = new SqlServerSnapshotOptions();
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions, snapshotOptions)
.WithShardRegion<UserActionsEntity>(
"userActions",
s => UserActionsEntity.Props(s),
new UserMessageExtractor(),
// shardOptions is being used here
shardOptions);
// Add the Akka.Cluster.Sharding migration journal event adapter
builder.WithClusterShardingJournalMigrationAdapter(journalOptions);
// you can also declare the adapter by referencing the journal ID directly
builder.WithClusterShardingJournalMigrationAdapter("akka.persistence.journal.sql-server");
})
With these HOCON settings in-place the following will happen:
- The old
PersitentShardCoordinator
state will be broken up - Remember entities data will be distributed to each of thePersistentShard
actors, who will now use the newRememberEntitiesStore = RememberEntitiesStore.Eventsourced
setting going forward; - Old
Akka.Cluster.Sharding.ShardCoordinator.IDomainEvent
events will be upgraded to a new storage format via the injected Akka.Persistence event adapter; and - The
PersistentShardCoordinator
will migrate its journal to the new format as well.
Step 2 - Migrating Away From Persistence to DData
Once your cluster has successfully booted up with these settings, you can now optionally move to using distributed data to store sharding state by changing StateStoreMode = StateStoreMode.DData
and deploying a second time:
hostBuilder.Services.AddAkka("MyActorSystem", builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true,
RememberEntitiesStore = RememberEntitiesStore.Eventsourced,
// Change this line of code
StateStoreMode = StateStoreMode.DData,
FailOnInvalidEntityStateTransition = true
};
var journalOptions = new SqlServerJournalOptions();
var snapshotOptions = new SqlServerSnapshotOptions();
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions, snapshotOptions)
.WithShardRegion<UserActionsEntity>(
"userActions",
s => UserActionsEntity.Props(s),
new UserMessageExtractor(),
shardOptions);
builder.WithClusterShardingJournalMigrationAdapter(journalOptions);
})
Now you'll be running Akka.Cluster.Sharding with the recommended settings.
Migrating to New Sharding Storage From Akka.DistributedData
The migration process onto Akka.NET v1.5's new Cluster.Sharding storage system is less involved for users who were already using StateStoreMode = StateStoreMode.DData
. All these users need to do is change the RememberEntitiesStore
option to RememberEntitiesStore.Eventsourced
hostBuilder.Services.AddAkka("MyActorSystem", builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true,
// Use this option setting
RememberEntitiesStore = RememberEntitiesStore.Eventsourced,
StateStoreMode = StateStoreMode.DData,
FailOnInvalidEntityStateTransition = true
};
var journalOptions = new SqlServerJournalOptions();
var snapshotOptions = new SqlServerSnapshotOptions();
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions, snapshotOptions)
.WithShardRegion<UserActionsEntity>(
"userActions",
s => UserActionsEntity.Props(s),
new UserMessageExtractor(),
shardOptions);
builder.WithClusterShardingJournalMigrationAdapter(journalOptions);
})
1.0.3
1.0.2
Version 1.0.2 introduces a new method to the ActorRegistry.GetAsync
in order to allow users to force parts of their application to wait until a specific IActorRef
has been started and added to the ActorRegistry
.
// arrange
var registry = new ActorRegistry();
// act
var task = registry.GetAsync<Nobody>();
task.IsCompletedSuccessfully.Should().BeFalse();
registry.Register<Nobody>(Nobody.Instance);
var result = await task;
// assert
result.Should().Be(Nobody.Instance);
This method is designed to allow users to wait via async Task<IActorRef>
for an actor to be registered in the event that a specific IRequiredActor<TKey>
is needed before Akka.Hosting can start the ActorSystem
inside its IHostedService
.
Akka.Hosting 1.0.1
Version 1.0.1 fixes options bug used in the cluster sharding Akka.Hosting extension method.
Akka.Hosting v1.0.0
[1.0.0] / 27 December 2022
This 1.0.0 release is the RTM release for Akka.Hosting
and contains major API breaking changes with a lot of its API. All current API will be frozen for all future releases and will be backed with our backward compatibility promise.
Change List
- Update Akka.NET from 1.4.45 to 1.4.47
- The
HoconAddMode
argument inAddHocon()
andAddHoconFile()
extension methods are not optional anymore ActorRegistry.Get<T>
will throw if no actor with key T has been registered with theActorRegistry
- Modularize and make Hosting.Persistence methods use the options pattern
- Add lease support to singleton and sharding extensions
- Fix bug in
AddActor
andAddStartup
to make sure that they're executed in order - Add IConfiguration to HOCON adapter
- Make
JournalOptions
andSnapshotOptions
IConfigurable bindable - Make
RemoteOptions
IConfiguration bindable - Better integration with Akka.DependencyInjection
- Add
WithActorAskTimeout
and extends debug logging options - Updated NuGet package versions:
General Changes
- Almost all options properties are changed to value types to allow direct binding to
Miscosoft.Extensions.Configuration
IConfiguration
instance. - Implements
Nullable
on all projects.
Changes To Akka.Hosting
-
The
HoconAddMode
argument inAddHocon()
andAddHoconFile()
extension methods are not optional anymore; you will need to declare that your HOCON will to append, prepend, or replace existing HOCON configuration. In almost all cases, unless you're adding a default configuration, you only need to useHoconAddMode.Prepend
. -
ActorRegistry.Get<T>
will now throw anActorRegistryException
if no actor with key T has been registered with theActorRegistry
, this is done to make the API more consistent with all other .NET APIs. UseActorRegistry.TryGet<T>
if you do not want this behavior. -
Better integration with
Akka.DependencyInjection
. Documentation can be read here -
Added
WithActorAskTimeout()
extension method to configure the actor ask timeout settings. -
Added extended debug logging support for dead letters and actor messages and events.
-
Adds a variation to
AddHocon
that can convertMicrosoft.Extensions.Configuration
IConfiguration
into HOCONConfig
instance and adds it to the ActorSystem being configured.- All variable name are automatically converted to lower case.
- All "." (period) in the
IConfiguration
key will be treated as a HOCON object key separator - For environment variable configuration provider:
- "__" (double underline) will be converted to "." (period).
- "_" (single underline) will be converted to "-" (dash).
- If all keys are composed of integer parseable keys, the whole object is treated as an array
Example:
JSON configuration:
{ "akka.cluster": { "roles": [ "front-end", "back-end" ], "min-nr-of-members": 3, "log-info": true } }
and environment variables:
AKKA__CLUSTER__ROLES__0=front-end AKKA__CLUSTER__ROLES__1=back-end AKKA__CLUSTER__MIN_NR_OF_MEMBERS=3 AKKA__CLUSTER__LOG_INFO=true
is equivalent to HOCON configuration of:
akka { cluster { roles: [ front-end, back-end ] min-nr-of-members: 3 log-info: true } }
Changes to Akka.Persistence.Hosting
- You can now use option classes to configure persistence. Currently, the persistence plugins that supports this are
Akka.Persistence.PostgreSql.Hosting
andAkka.Persistence.SqlServer.Hosting
. Support for other Akka.Hosting enabled plugins will be rolled out after this release. - These option classes are modular:
- Multiple options can be registered with the builder using different names
- The same persistence plugin (e.g. PostgreSql) can be declared and registered multiple times using different names and configuration.
- Options can be declared as the default persistence plugin and not.
- Different or the same registered option can be used as the normal persistence options and
Akka.Cluster.Hosting
sharding extension methods. - There can only be one option declared as the default journal and one option declared as the default snapshot plugin. If multiple default plugin options are declared, only the last registered option will have an effect.
- Journal event adapters can now be composed directly using the
Adapters
property inside the journal option class. - An example project can be seen here
Example code:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
// Grab connection strings from appsettings.json
var localConn = builder.Configuration.GetConnectionString("sqlServerLocal");
var shardingConn = builder.Configuration.GetConnectionString("sqlServerSharding");
// Custom journal options with the id "sharding"
// The absolute id will be "akka.persistence.journal.sharding"
var shardingJournalOptions = new SqlServerJournalOptions(
isDefaultPlugin: false)
{
Identifier = "sharding",
ConnectionString = shardingConn,
AutoInitialize = true
};
// Custom snapshots options with the id "sharding"
// The absolute id will be "akka.persistence.snapshot-store.sharding"
var shardingSnapshotOptions = new SqlServerSnapshotOptions(
isDefaultPlugin: false)
{
Identifier = "sharding",
ConnectionString = shardingConn,
AutoInitialize = true
};
configurationBuilder
// Standard way to create a default persistence
// journal and snapshot
.WithSqlServerPersistence(localConn)
// This is a custom persistence setup using the options
// instances we've set up earlier.
// Note that we are calling WithSqlServerPersistence()
// twice, these two calls registers two different
// persistence options with two different identifier names.
.WithSqlServerPersistence(shardingJournalOptions, shardingSnapshotOptions)
.WithShardRegion<UserActionsEntity>(
"userActions",
s => UserActionsEntity.Props(s),
new UserMessageExtractor(),
new ShardOptions
{
StateStoreMode = StateStoreMode.Persistence,
Role = "myRole",
// Supplying sharding with separate persistence plugin options
JournalOptions = shardingJournalOptions,
SnapshotOptions = shardingSnapshotOptions
// NOTE: you can supply the plugin id instead
// JournalPluginId = shardingJournalOptions.PluginId,
// SnapshotPluginId = shardingSnapshotOptions.PluginId
});
})
Changes to Akka.Cluster.Hosting
ClusterOptions
are expanded with more properties to make it more configurable. These new properties are:MinimumNumberOfMembers
: Allows you to set the minimum number of joined cluster members for a cluster to be considered to be in theUp
state.MinimumNumberOfMembersPerRole
: Similar to ``MinimumNumberOfMembers`, but it is scoped to each cluster role.AppVersion
: Allows you to set the current cluster application version, useful for performing rolling update of the cluster members.LogInfo
: Enable info level logging of cluster events.LogInfoVerbose
: Enable a more verbose info level logging of cluster events, used for temporary troubleshooting.SplitBrainResolver
: The split brain resolver property is moved into the options class instead of being part of the extension method arguments.
ClusterSingletonOptions
andShardOptions
now have aLeaseImplementation
property that can be used to configure leasing for cluster singleton and sharding. Currently, two lease plugins are supported:Akka.Coordination.KubernetesApi
andAkka.Coordination.Azure
by assigningKubernetesLeaseOption.Instance
orAzureLeaseOption.Instance
respectively to the property.