Skip to content

Commit

Permalink
Update RELEASE_NOTES.md for 1.5.0 RTM and update Akka,NET to 1.5.0 RTM (
Browse files Browse the repository at this point in the history
#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
Arkatufus and Aaronontheweb authored Mar 2, 2023
1 parent 044f1e7 commit 4ea61d0
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 146 deletions.
154 changes: 9 additions & 145 deletions RELEASE_NOTES.md
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.
2 changes: 1 addition & 1 deletion src/Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
<TestSdkVersion>17.5.0</TestSdkVersion>
<CoverletVersion>3.2.0</CoverletVersion>
<XunitRunneVisualstudio>2.4.5</XunitRunneVisualstudio>
<AkkaVersion>1.5.0-beta6</AkkaVersion>
<AkkaVersion>1.5.0</AkkaVersion>
<MicrosoftExtensionsVersion>[3.0.0,)</MicrosoftExtensionsVersion>
</PropertyGroup>

Expand Down

0 comments on commit 4ea61d0

Please sign in to comment.