Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ The [AWS SDK for .NET credential and profile resolution chain](https://docs.aws.

<xref:Orleans.Configuration.DynamoDBStorageOptions.ServiceId> must remain stable across deployments that share the same logical application state. The provider uses optimistic concurrency and rejects stale writes.

When <xref:Orleans.Configuration.DynamoDBStorageOptions.ServiceId> is empty, the keys start with an underscore instead of <xref:Orleans.Configuration.ClusterOptions.ServiceId>, unlike the other grain storage providers, and the provider logs a warning. Set <xref:Orleans.Configuration.DynamoDBStorageOptions.UseClusterServiceId> to use <xref:Orleans.Configuration.ClusterOptions.ServiceId> instead. State written before then stays under its old key unless <xref:Orleans.Configuration.DynamoDBStorageOptions.MigrateLegacyKeys> is also set: a grain with no state under the new key then reads it from the old one, and its next write moves it, in one transaction; a grain that has state under the new key keeps it, and its next write or clear deletes the old item in the same transaction. Set <xref:Orleans.Configuration.DynamoDBStorageOptions.MigrateLegacyKeys> together with <xref:Orleans.Configuration.DynamoDBStorageOptions.UseClusterServiceId>: once the keys have been built from <xref:Orleans.Configuration.ClusterOptions.ServiceId> without a migration, the provider refuses to start one, since a grain whose state there has since been deleted or has expired would read back its older state. Enable the migration once every silo runs a version that supports it, with the same options on every silo: a silo still writing the old keys, from an older version or with <xref:Orleans.Configuration.DynamoDBStorageOptions.UseClusterServiceId> set to `false`, is not protected from a migrating silo moving or deleting state it recreates, since an item recreated after <xref:Orleans.Configuration.DynamoDBStorageOptions.DeleteStateOnClear> starts again at ETag 0. While the migration is on, every write or clear is a transaction over two items, which uses more write capacity; set <xref:Orleans.Configuration.DynamoDBStorageOptions.MigrateLegacyKeys> to `false` when every grain has been written, to spare that and the second read for grains that have no state. The provider records its choice in the table, once for the whole table, so every provider that uses the table with an empty <xref:Orleans.Configuration.DynamoDBStorageOptions.ServiceId> must have the same options. It keeps that choice while these options are left unset, and refuses to start with <xref:Orleans.Configuration.DynamoDBStorageOptions.UseClusterServiceId> set to `false` once the table records <xref:Orleans.Configuration.ClusterOptions.ServiceId>, since the state written since would not be found.

## Serialization

Set <xref:Orleans.Configuration.DynamoDBStorageOptions.GrainStorageSerializer> to customize the stored representation. Changing serializers doesn't rewrite existing items, so the replacement must read the previous representation or be accompanied by a migration.
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,16 @@ public void Configure(ISiloBuilder builder, string? name, IConfigurationSection
options.ServiceId = serviceId;
}

if (bool.TryParse(configurationSection[nameof(options.UseClusterServiceId)], out var useClusterServiceId))
{
options.UseClusterServiceId = useClusterServiceId;
}

if (bool.TryParse(configurationSection[nameof(options.MigrateLegacyKeys)], out var migrateLegacyKeys))
{
options.MigrateLegacyKeys = migrateLegacyKeys;
Comment thread
Laurianti marked this conversation as resolved.
Resolved
}

var tableName = configurationSection[nameof(options.TableName)];
if (!string.IsNullOrEmpty(tableName))
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ public static IServiceCollection AddDynamoDBGrainStorage(this IServiceCollection
services.AddTransient<IConfigurationValidator>(sp => new DynamoDBGrainStorageOptionsValidator(sp.GetRequiredService<IOptionsMonitor<DynamoDBStorageOptions>>().Get(name), name));
services.ConfigureNamedOptionForLogging<DynamoDBStorageOptions>(name);
services.AddTransient<IPostConfigureOptions<DynamoDBStorageOptions>, DefaultStorageProviderSerializerOptionsConfigurator<DynamoDBStorageOptions>>();
services.TryAddEnumerable(ServiceDescriptor.Transient<IPostConfigureOptions<DynamoDBStorageOptions>, DynamoDBStorageClusterServiceIdConfigurator>());
return services.AddGrainStorage(name, DynamoDBGrainStorageFactory.Create);
}
}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Orleans.Configuration.Overrides;
using Orleans.Persistence.DynamoDB;
using Orleans.Runtime;
using Orleans.Storage;
Expand All @@ -12,9 +15,37 @@ public class DynamoDBStorageOptions : DynamoDBClientOptions, IStorageProviderSer
{
/// <summary>
/// Gets or sets a unique identifier for this service, which should survive deployment and redeployment.
/// When left empty, see <see cref="UseClusterServiceId"/>.
/// </summary>
public string ServiceId { get; set; } = string.Empty;

/// <summary>
/// Gets or sets whether an empty <see cref="ServiceId"/> falls back to <see cref="ClusterOptions.ServiceId"/>,
/// as the other grain storage providers do. When <see langword="false"/>, an empty <see cref="ServiceId"/> is used
/// as it is, and every key starts with an underscore; initialization fails if the table already records
/// <see cref="ClusterOptions.ServiceId"/>. When not set, the key format already recorded in the table is kept, and a
/// new table uses the empty <see cref="ServiceId"/>; this default changes in a future major version. The key format
/// is recorded once for the whole table. Has no effect when <see cref="ServiceId"/> is set.
/// </summary>
public bool? UseClusterServiceId { get; set; }

/// <summary>
/// Gets or sets whether state written with an empty <see cref="ServiceId"/> is read when a grain has no state under
/// <see cref="ClusterOptions.ServiceId"/>, and moved there on the grain's next write; a grain that has state there
/// keeps it, and its next write or clear deletes the legacy item as well, in a transaction over both items. When not
/// set, a migration recorded in the table goes on. Has an effect only when <see cref="ClusterOptions.ServiceId"/> is
/// used for an empty <see cref="ServiceId"/>, and set it together with <see cref="UseClusterServiceId"/>:
/// initialization fails if the table records <see cref="ClusterOptions.ServiceId"/> without a migration. Every silo
/// must run with the same options while it is set: a silo still writing the keys with an empty
/// <see cref="ServiceId"/> is not protected from a migrating one.
/// </summary>
public bool? MigrateLegacyKeys { get; set; }

/// <summary>
/// The <see cref="ClusterOptions.ServiceId"/> of the silo, used when <see cref="UseClusterServiceId"/> applies.
/// </summary>
internal string ClusterServiceId { get; set; } = ClusterOptions.DefaultServiceId;

/// <summary>
/// Use Provisioned Throughput for tables
/// </summary>
Expand Down Expand Up @@ -71,6 +102,23 @@ public class DynamoDBStorageOptions : DynamoDBClientOptions, IStorageProviderSer
public IGrainStorageSerializer GrainStorageSerializer { get; set; } = null!;
}

/// <summary>
/// Supplies <see cref="DynamoDBStorageOptions"/> with the <see cref="ClusterOptions.ServiceId"/> of the silo.
/// </summary>
internal sealed class DynamoDBStorageClusterServiceIdConfigurator(IServiceProvider serviceProvider) : IPostConfigureOptions<DynamoDBStorageOptions>
{
public void PostConfigure(string? name, DynamoDBStorageOptions options)
{
// a provider-specific override first, then the silo's
var clusterOptions = serviceProvider.GetProviderClusterOptions(name ?? Microsoft.Extensions.Options.Options.DefaultName).Value;

if (clusterOptions.ServiceId is { Length: > 0 } serviceId)
{
options.ClusterServiceId = serviceId;
}
}
}

/// <summary>
/// Configuration validator for DynamoDBStorageOptions
/// </summary>
Expand Down
Loading