Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update RELEASE_NOTES.md for 1.5.0 RTM and update Akka,NET to 1.5.0 RTM #250

Merged
merged 2 commits into from
Mar 2, 2023
Merged

Update RELEASE_NOTES.md for 1.5.0 RTM and update Akka,NET to 1.5.0 RTM #250

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b185a2c
Update RELEASE_NOTES.md for 1.5.0 RTM and update Akka,NET to 1.5.0 RTM
Arkatufus Mar 2, 2023
364f91c
Update RELEASE_NOTES.md
Aaronontheweb Mar 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 9 additions & 145 deletions RELEASE_NOTES.md
View file
Open in desktop
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
View file
Open in desktop
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