-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update RELEASE_NOTES.md for 1.5.0 RTM and update Akka,NET to 1.5.0 RTM (
#250) * Update RELEASE_NOTES.md for 1.5.0 RTM and update Akka,NET to 1.5.0 RTM * Update RELEASE_NOTES.md --------- Co-authored-by: Aaron Stannard <[email protected]>
- Loading branch information
1 parent
044f1e7
commit 4ea61d0
Showing
2 changed files
with
10 additions
and
146 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,150 +1,14 @@ | ||
| ## [1.5.0-beta6] / 28 February 2023 | ||
| ## [1.5.0] / 2 March 2023 | ||
|
|
||
| * [Update Akka.NET to 1.5.0-beta6](https://github.com/akkadotnet/akka.net/releases/tag/1.5.0-beta6) | ||
| Version 1.5.0 is the RTM release of Akka.Hosting and Akka.NET v1.5.0 RTM integration. | ||
|
|
||
| ## [1.5.0-beta4] / 28 February 2023 | ||
|
|
||
| Version 1.5.0-beta4 integrates Akka.NET v1.5 into Akka.Hosting | ||
|
|
||
| * [Update Akka.NET to 1.5.0-beta4](https://github.com/akkadotnet/akka.net/releases/tag/1.5.0-beta4) | ||
| Full changes | ||
| * [Update Akka.NET to 1.5.0](https://github.com/akkadotnet/akka.net/releases/tag/1.5.0) | ||
| * [Fix missing cluster configuration on certain edge cases](https://github.com/akkadotnet/Akka.Hosting/pull/214) | ||
| * [Add new Cluster.Sharding RememberEntitiesStore](https://github.com/akkadotnet/Akka.Hosting/pull/224) | ||
| * [Add Cluster.Sharding journal migration adapter convenience method](https://github.com/akkadotnet/Akka.Hosting/pull/226) | ||
| * [Add LogMessageFormatter formatter support to logging](https://github.com/akkadotnet/Akka.Hosting/pull/248) | ||
|
|
||
| #### Upgrading From v1.4 To v1.5 | ||
| As noted in [the upgrade advisories](https://github.com/akkadotnet/akka.net/blob/c9ccc25207b5a4cfa963a5a23f96c0676fbbef10/docs/community/whats-new/akkadotnet-v1.5-upgrade-advisories.md), 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: | ||
|
|
||
| ```csharp | ||
| 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): | ||
|
|
||
| ```csharp | ||
| 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: | ||
|
|
||
| 1. The old `PersitentShardCoordinator` state will be broken up - Remember entities data will be distributed to each of the `PersistentShard` actors, who will now use the new `RememberEntitiesStore = RememberEntitiesStore.Eventsourced` setting going forward; | ||
| 2. Old `Akka.Cluster.Sharding.ShardCoordinator.IDomainEvent` events will be upgraded to a new storage format via the injected Akka.Persistence event adapter; 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, 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", 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` | ||
|
|
||
| ```csharp | ||
| 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); | ||
| }) | ||
| ``` | ||
| As noted in [the upgrade advisories](https://getakka.net/community/whats-new/akkadotnet-v1.5-upgrade-advisories.html), there was some major changes inside Akka.NET that directly affects Akka.Hosting. To upgrade from v1.4 to v1.5, please watch our video [here](https://www.youtube.com/watch?v=-UPestlIw4k) covering this process. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters