|
| 1 | +--- |
| 2 | +title: Stream with Amazon Kinesis |
| 3 | +description: Configure Amazon Kinesis Data Streams for Orleans, including durable DynamoDB checkpoints. |
| 4 | +ms.date: 08/07/2026 |
| 5 | +ms.topic: how-to |
| 6 | +--- |
| 7 | + |
| 8 | +# Stream with Amazon Kinesis |
| 9 | + |
| 10 | +The [`Microsoft.Orleans.Streaming.Kinesis`](https://www.nuget.org/packages/Microsoft.Orleans.Streaming.Kinesis) package connects Orleans persistent streams to [Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/introduction.html). Each Kinesis shard is an Orleans queue, so the number of open shards bounds physical read parallelism. Kinesis retention determines how far a consumer can replay. |
| 11 | + |
| 12 | +Create the Kinesis data stream before starting Orleans. The provider discovers its shards but doesn't create, delete, split, or merge the stream. |
| 13 | + |
| 14 | +## Configure the silo |
| 15 | + |
| 16 | +Install the package and register a named provider: |
| 17 | + |
| 18 | +```csharp |
| 19 | +using Orleans.Hosting; |
| 20 | + |
| 21 | +siloBuilder |
| 22 | + .AddDynamoDBGrainStorage("PubSubStore", options => |
| 23 | + { |
| 24 | + options.Service = "us-east-1"; |
| 25 | + options.ServiceId = "orders"; |
| 26 | + options.TableName = "OrdersPubSub"; |
| 27 | + options.UseProvisionedThroughput = false; |
| 28 | + }) |
| 29 | + .AddKinesisStreams("Orders", stream => |
| 30 | + { |
| 31 | + stream.ConfigureKinesis(options => |
| 32 | + { |
| 33 | + options.StreamName = "orders"; |
| 34 | + options.Region = "us-east-1"; |
| 35 | + }); |
| 36 | + |
| 37 | + stream.UseDynamoDBCheckpointer(options => |
| 38 | + { |
| 39 | + options.Service = "us-east-1"; |
| 40 | + options.TableName = "OrdersStreamCheckpoints"; |
| 41 | + options.PersistInterval = TimeSpan.FromSeconds(30); |
| 42 | + }); |
| 43 | + }); |
| 44 | +``` |
| 45 | + |
| 46 | +`PubSubStore` persists explicit Orleans stream subscriptions. The checkpoint table has a different purpose: it records the last delivered Kinesis sequence number for each shard. |
| 47 | + |
| 48 | +Configure every Orleans client which publishes through the provider with the same provider name, stream name, and region: |
| 49 | + |
| 50 | +```csharp |
| 51 | +clientBuilder.AddKinesisStreams("Orders", options => |
| 52 | +{ |
| 53 | + options.StreamName = "orders"; |
| 54 | + options.Region = "us-east-1"; |
| 55 | +}); |
| 56 | +``` |
| 57 | + |
| 58 | +When explicit credentials aren't configured, the provider uses the [AWS SDK for .NET credential resolution chain](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/creds-assign.html). In production, prefer workload credentials such as an IAM role. Set <xref:Orleans.Streaming.Kinesis.KinesisStreamOptions.Service> when using a custom Kinesis-compatible endpoint. |
| 59 | + |
| 60 | +## Choose checkpoint storage |
| 61 | + |
| 62 | +Kinesis shard iterators are temporary. Orleans therefore stores the last delivered sequence number outside Kinesis and uses it to resume after a restart or queue reassignment. |
| 63 | + |
| 64 | +### DynamoDB table checkpoints |
| 65 | + |
| 66 | +Call <xref:Orleans.Hosting.SiloKinesisStreamConfigurator.UseDynamoDBCheckpointer*> to store checkpoints directly in DynamoDB. The checkpointer: |
| 67 | + |
| 68 | +- Uses one versioned item per Orleans service, provider, and Kinesis shard. |
| 69 | +- Uses consistent reads and conditional writes to prevent a previous queue owner from overwriting a newer checkpoint. |
| 70 | +- Creates an on-demand table by default. Set <xref:Orleans.Configuration.DynamoDBStreamQueueCheckpointerOptions.CreateIfNotExists> to `false` when infrastructure provisioning owns the table. |
| 71 | +- Limits writes using <xref:Orleans.Configuration.DynamoDBStreamQueueCheckpointerOptions.PersistInterval>. A shorter interval reduces replay after failure but increases DynamoDB write traffic. |
| 72 | + |
| 73 | +Set <xref:Orleans.Configuration.DynamoDBStreamQueueCheckpointerOptions.UseProvisionedThroughput>, <xref:Orleans.Configuration.DynamoDBStreamQueueCheckpointerOptions.ReadCapacityUnits>, and <xref:Orleans.Configuration.DynamoDBStreamQueueCheckpointerOptions.WriteCapacityUnits> when the table uses provisioned capacity. |
| 74 | + |
| 75 | +### Grain checkpoints |
| 76 | + |
| 77 | +If no checkpointer is selected, the provider uses Orleans grain-backed checkpoints. Checkpoint grains use `PubSubStore` by default, so that provider must be durable in production: |
| 78 | + |
| 79 | +```csharp |
| 80 | +using Orleans.Streams; |
| 81 | + |
| 82 | +siloBuilder.AddKinesisStreams("Orders", stream => |
| 83 | +{ |
| 84 | + stream.ConfigureKinesis(options => |
| 85 | + { |
| 86 | + options.StreamName = "orders"; |
| 87 | + options.Region = "us-east-1"; |
| 88 | + }); |
| 89 | + |
| 90 | + stream.UseGrainCheckpointer(options => |
| 91 | + { |
| 92 | + options.StorageProviderName = "PubSubStore"; |
| 93 | + options.CheckpointComparer = StreamCheckpointComparers.Numeric; |
| 94 | + options.PersistInterval = TimeSpan.FromSeconds(30); |
| 95 | + }); |
| 96 | +}); |
| 97 | +``` |
| 98 | + |
| 99 | +Both implementations preserve monotonic Kinesis sequence numbers and can replay a small number of already delivered records after an unclean shutdown. Consumers must tolerate duplicate delivery. |
| 100 | + |
| 101 | +## Operations and permissions |
| 102 | + |
| 103 | +Grant the application only the Kinesis data-plane and DynamoDB table permissions required by its configuration. The Kinesis provider lists shards, obtains shard iterators, reads records, and writes records. A provider-managed checkpoint table also requires permissions to describe and create the table and to read and conditionally write checkpoint items. |
| 104 | + |
| 105 | +Monitor Kinesis iterator age, read throttling, provisioned throughput, and retention together with the [Orleans streaming metrics](streaming-operations.md#observe-health). <xref:Orleans.Streaming.Kinesis.KinesisStreamOptions.GetRecordsInterval> defaults to the fastest interval allowed by Kinesis for each shard. |
| 106 | + |
| 107 | +Live resharding isn't supported. If the shard topology changes while the provider is running, receivers stop rather than risk incorrect queue ownership. Restart the Orleans stream provider after splitting or merging shards. |
| 108 | + |
| 109 | +For a complete configuration which uses DynamoDB for clustering, grain state, reminders, and Kinesis checkpoints, see the [AWS Kinesis and DynamoDB sample](https://github.com/dotnet/orleans/tree/main/samples/AWS/KinesisDynamoDB). |
0 commit comments